Home Integrations MCP Server — Connect AI Assistants to Humadroid

MCP Server — Connect AI Assistants to Humadroid

Last updated on Apr 14, 2026

Humadroid includes a built-in MCP (Model Context Protocol) server that lets AI assistants read your compliance data directly. This gives AI tools real-time access to your projects, controls, documents, sections, and evidences — so you can ask questions, generate reports, or get implementation guidance without copy-pasting.

What you get

The MCP server exposes 11 read-only tools:

  • list_projects / get_project — browse and inspect compliance projects

  • list_controls / get_control — query controls with filters (by project, section, implementation status)

  • list_documents / get_document — access policies, procedures, and other compliance documents (including content)

  • list_sections / get_section — navigate the section hierarchy within a project

  • list_evidences / get_evidence — review evidence records

  • search — full-text search across all compliance data (requires Global Search to be enabled)

All data is scoped to your account and respects user permissions. A user connecting via MCP sees exactly the same data they would see in the Humadroid UI.

Prerequisites

Before setting up MCP, you need:

  • API access enabled for your account (an admin must turn this on in Account Settings)

  • An API token for authentication

Step 1: Enable API Access

An account administrator must enable API access:

  1. Go to Account Settings

  2. Find the API Access toggle

  3. Enable it and save

Without this, all API and MCP requests will be rejected.

Step 2: Create an API Token

  1. Click your avatar in the top-right corner and go to Profile -> Edit profile (or Profile -> Manage profile)

  2. Navigate to the API Tokens tab

  3. Enter a descriptive name for the token (e.g., "Claude MCP")

  4. Set an expiration period (up to 30 days)

  5. Click Create Token

  6. Copy the token immediately — it will only be shown once

Keep this token secure. It grants the same read access as your user account. You can revoke it at any time from the same page.

Step 3: Connect your AI assistant

Your MCP endpoint URL follows this pattern:

https://YOUR-SUBDOMAIN.humadroid.io/mcp/sse

Replace YOUR-SUBDOMAIN with your actual Humadroid account subdomain (the part before .humadroid.io when you log in).

The server uses the SSE (Server-Sent Events) transport. All clients listed below support it.

Claude Code (CLI)

Run this command in your terminal:

claude mcp add humadroid \
  --transport sse \
  https://YOUR-SUBDOMAIN.humadroid.io/mcp/sse \
  --header "Authorization: Bearer YOUR-API-TOKEN"

This adds a project-scoped configuration. To share it with your team, add --scope project which writes to .mcp.json at the project root.

You can also create .mcp.json manually in your project root:

{
  "mcpServers": {
    "humadroid": {
      "type": "sse",
      "url": "https://YOUR-SUBDOMAIN.humadroid.io/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR-API-TOKEN"
      }
    }
  }
}

To use an environment variable instead of a hardcoded token:

{
  "mcpServers": {
    "humadroid": {
      "type": "sse",
      "url": "https://YOUR-SUBDOMAIN.humadroid.io/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${HUMADROID_API_TOKEN}"
      }
    }
  }
}

Then set HUMADROID_API_TOKEN in your shell environment.

After adding, verify with claude mcp list — you should see "humadroid" listed.

Claude Desktop (macOS / Windows app)

Claude Desktop's config file only supports local (stdio) servers. To connect to Humadroid's remote MCP server, you have two options:

Option A: Use the Connectors UI (simplest)

  1. Open Claude Desktop

  2. Go to Settings (gear icon)

  3. Navigate to Connectors

  4. Click Add custom connector

  5. Paste your MCP endpoint URL: https://SUBDOMAIN.humadroid.io/mcp/sse

  6. Open Advanced Settings

  7. In OAuth Client ID type humadroid, in OAuth Client Secret put your API Token

Humadroid MCP Server configuraiton in Claude Desktop

Option B: Use mcp-remote as a bridge

The mcp-remote npm package wraps a remote SSE server into a local stdio process that Claude Desktop can use.

  1. Make sure you have Node.js installed (v18+)

  2. Open Claude, go to Settings, Developer and Edit config OR

    1. Open your Claude Desktop config file:

      1. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

      2. Windows: %APPDATA%\Claude\claude_desktop_config.json

  3. Add the following (replace YOUR-SUBDOMAIN and YOUR-API-TOKEN):

{
  "mcpServers": {
    "humadroid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-SUBDOMAIN.humadroid.io/mcp/sse",
        "--header",
        "Authorization:${HUMADROID_TOKEN}"
      ],
      "env": {
        "HUMADROID_TOKEN": "Bearer YOUR-API-TOKEN"
      }
    }
  }
}

The token is passed via the env section and referenced as ${HUMADROID_TOKEN} in the header argument. The Authorization: header uses no space after the colon — this avoids a known issue where some platforms mangle spaces inside args.

  1. Save the file and restart Claude Desktop

  2. You should see "humadroid" in the tools menu (hammer icon)

Cursor

  1. Create or edit the file .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global access)

  2. Add the following:

{
  "mcpServers": {
    "humadroid": {
      "url": "https://YOUR-SUBDOMAIN.humadroid.io/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${env:HUMADROID_API_TOKEN}"
      }
    }
  }
}

  1. Set the HUMADROID_API_TOKEN environment variable to your API token

  2. Restart Cursor

You can also use the Settings UI: open Settings (Cmd+Shift+P, then "Cursor Settings"), go to the MCP section, and the JSON editor will show the same file.

Note: Cursor uses ${env:VAR_NAME} syntax for environment variables (different from Claude Code's ${VAR_NAME} syntax).

ChatGPT

ChatGPT supports MCP servers through its developer mode and connectors feature. This requires a ChatGPT Pro, Plus, Business, Enterprise, or Education plan.

  1. Open ChatGPT on the web

  2. Go to Settings then Connectors

  3. Click Create to add a new connector

  4. Enter the MCP endpoint URL: https://YOUR-SUBDOMAIN.humadroid.io/mcp/sse

  5. Follow the authentication configuration steps

Note: ChatGPT connectors may require OAuth-based authentication. If Bearer token auth is not directly supported in the connectors UI, contact your Humadroid administrator about OAuth setup options.

For more details, see OpenAI's documentation on developer mode and MCP apps.

Other MCP Clients

Any MCP-compatible client can connect using:

  • Transport: SSE (Server-Sent Events)

  • SSE endpoint: https://YOUR-SUBDOMAIN.humadroid.io/mcp/sse

  • Messages endpoint: https://YOUR-SUBDOMAIN.humadroid.io/mcp/messages (JSON-RPC via POST)

  • Authentication: Authorization: Bearer YOUR-API-TOKEN header on all requests

Optional: Enable Global Search

The MCP server includes a search tool that lets AI assistants search across all your compliance data using full-text search. This is much faster than browsing through lists when looking for specific controls or documents.

To enable it:

  1. Go to Account Settings

  2. Find the Compliance section

  3. Enable the Global Search checkbox

  4. Save

Note: enabling search indexing stores decrypted content (like document text and implementation notes) in a plaintext search index. This enables full-text search but means that data exists in an additional unencrypted form in the database.

If Global Search is not enabled, the search tool will return a message telling the AI to use the list tools with filters instead.

Usage Examples

Once connected, you can ask your AI assistant questions like:

  • "List all my compliance projects and their status"

  • "Show me the controls in my ISO 27001 project that are not yet implemented"

  • "Find the access control policy document and summarize it"

  • "What evidence do we have for control A.8.1?"

  • "Search for anything related to encryption in our compliance data"

  • "Give me a progress report on our SOC 2 project"

The AI will use the MCP tools to fetch real-time data from Humadroid and respond with accurate, up-to-date information.

Security and Rate Limits

  • Data isolation: MCP respects your account boundaries. You can only access data belonging to your account's subdomain.

  • Permissions: The MCP server enforces the same role-based permissions as the Humadroid UI. Users see only what they're authorized to see.

  • Token expiration: API tokens expire after the period you set (max 30 days). Create a new token when the current one expires.

  • Rate limiting: MCP requests are throttled to 100 requests per minute per token. Exceeding this returns a 429 (Too Many Requests) response.

  • Brute-force protection: Repeated unauthenticated requests from the same IP address will be throttled.

  • Read-only: The MCP server only provides read access. It cannot create, modify, or delete any data in Humadroid.

Troubleshooting

  • "Unauthorized" or connection refused: verify your API token is correct and has not expired. Check that API access is enabled for your account.

  • Empty results: make sure you have compliance projects set up in Humadroid. The MCP tools return data from your account — if there are no projects, controls, or documents, the results will be empty.

  • Search returns "not available": Global Search needs to be enabled in Account Settings. Ask an administrator to turn it on.

  • Token expired: create a new API token from your Profile page and update your MCP client configuration.

  • "Too many requests" (429): you've hit the rate limit. Wait a minute and try again, or reduce the frequency of requests.

  • Claude Desktop not connecting: make sure you're using the mcp-remote bridge (Option B) — Claude Desktop's config file does not support remote servers directly.

  • Cursor not picking up changes: restart Cursor after editing .cursor/mcp.json. Check that your environment variable is set in the shell that launched Cursor.