Skip to main content

Claude Setup

Use this page to connect Claude-compatible MCP clients to Zerq.

  • Use Gateway MCP for runtime API tooling.
  • Use Management MCP only for controlled platform automation identities.

Connection requirements​

Gateway MCP​

  • Endpoint: https://api.example.com/mcp
  • Required headers: Authorization, X-Client-ID, X-Profile-ID

Management MCP​

  • Endpoint: https://api.example.com/api/v1/mcp
  • Required header: Authorization (OIDC bearer token)

Desktop MCP config (Claude)​

If you use Claude Desktop, configure MCP servers in your desktop config JSON and restart the app after saving.

Template:

{
  "mcpServers": {
    "zerq-gateway": {
      "url": "https://api.example.com/mcp",
      "transport": "streamableHttp",
      "headers": {
        "Authorization": "Bearer <GATEWAY_TOKEN_OR_JWT>",
        "X-Client-ID": "<CLIENT_ID>",
        "X-Profile-ID": "<PROFILE_ID>"
      }
    },
    "zerq-management": {
      "url": "https://api.example.com/api/v1/mcp",
      "transport": "streamableHttp",
      "headers": {
        "Authorization": "Bearer <OIDC_ACCESS_TOKEN>"
      }
    }
  }
}

Notes:

  • Do not send X-Client-ID / X-Profile-ID to management MCP.
  • Use separate entries for staging and production.
  • Keep tokens out of git-tracked files.

Protocol sequence​

Claude-side MCP traffic must follow:

  1. initialize
  2. tools/list
  3. tools/call (or prompts/list/prompts/get for management MCP)

Always propagate Mcp-Session-Id after initialize.

Validation checklist​

  • initialize succeeds (200) and returns session header.
  • tools/list returns only expected tools.
  • Out-of-scope call returns 403.
  • Missing/expired auth returns 401.

Security controls​

  • Separate identities for read-only and mutating automations.
  • Restrict management roles to required minimum (viewer or modifier; keep admin isolated).
  • Apply ingress controls for concurrency spikes.