Skip to main content

Setup OIDC

Use this guide to configure OIDC trust for Management MCP (/api/v1/mcp).

What this page covers​

  • IdP/OIDC settings needed for management MCP access.
  • Token expectations and required headers.
  • Session bootstrap checks (initialize + Mcp-Session-Id).

Configure OIDC for management MCP​

  1. Configure your management API OIDC trust:
    • issuer URL
    • audience
    • role claim path
  2. Ensure role mappings include intended management roles:
    • viewer
    • modifier
    • auditor
    • admin
  3. Keep Management MCP path explicit (/api/v1/mcp by default).
  4. Expose Management MCP only over TLS.

Request model (important)​

  • Always send Authorization: Bearer <OIDC access token>.
  • Do not send X-Client-ID / X-Profile-ID to Management MCP.
  • Use JSON-RPC methods (initialize, tools/list, tools/call).

Example MCP call​

curl -i https://gateway.example.com/api/v1/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "init-1",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name":"agent","version":"1.0.0"}
    }
  }'

Validation checklist​

  1. initialize returns 200 and includes Mcp-Session-Id.
  2. tools/list with that session succeeds.
  3. Missing/invalid token returns 401.
  4. Out-of-scope operation returns 403.

Common misconfigurations​

  • Wrong issuer/audience -> valid-looking token still rejected (401).
  • Missing role claim path -> everyone appears unauthorized (403).
  • Sending gateway headers to management MCP -> non-standard requests and confusion.