Skip to content

MCP authorization (OAuth 2.1)

The MCP endpoint is an OAuth 2.1 protected resource; the authorization server is the IdP of the deployment (Keycloak in the development Compose, or the customer's IdP). ExtractIt does not run its own authorization server.

Flow

  1. The client calls POST /mcp without a token and gets 401 with WWW-Authenticate: Bearer resource_metadata="<base>/.well-known/oauth-protected-resource/mcp", scope="read".
  2. It reads the metadata (RFC 9728; also at /.well-known/oauth-protected-resource): resource (<base>/mcp), authorization_servers, scopes_supported (read write review eval admin) and bearer_methods_supported: ["header"].
  3. It discovers the authorization server (RFC 8414), registers if needed, and runs the authorization-code flow with PKCE S256 and the resource indicator (RFC 8707) resource=<base>/mcp.
  4. The token must have aud equal to <base>/mcp (built from DX_MCP_BASE_URL, never from Host), the configured iss, a valid signature (RS256 from the JWKS) and no expiry. Anything else is 401 invalid_token. A token in the query string is ignored.
  5. Effective permissions = the token's scopes ∩ the user's role in the organization (T13 membership; the claim dx_org selects an organization). No membership → 403.
  6. Step-up: calling a tool that needs a scope the token lacks gives 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="write", resource_metadata=…; the client re-authorizes with the wider scope. When the role itself forbids it the 403 has no step-up.

Calls are forwarded to the API in process as a 60-second internal token (user, organization, project, role, scopes) signed with a per-process secret; the client's token never leaves the server.

Automated tests

tests/mcp/test_mcp_oauth.py runs the official MCP Python SDK OAuth client against a test authorization server (tests/mcp/oauth_as.py, PKCE S256 and resource indicator): discovery by PRM, code, token, tools/call, and a step-up from read to read write without reconfiguration. The same file checks the PRM, the 401/403 headers, audience, issuer, expiry, alg: none, the query-string token, scopes ∩ role, API key equivalence and Host/Origin.

Manual matrix with real clients

Client Version IdP Discovery PKCE + resource tools/call Step-up Result Log
Claude Code (claude mcp add --transport http) — Keycloak (dev Compose) — — — — not run —
MCP Inspector (UI, OAuth tab) 0.17.2 Keycloak (dev Compose) — — — — not run —

Status

The manual runs with real clients need a browser, a desktop client and the Keycloak of the development Compose; they were not run in the CI worker that built this page. Fill this table with the date, versions and an attached log (docs/mcp/logs/) when they are run. Keycloak's client ID metadata documents (CIMD) are experimental: pre-register the client if a real client fails at registration.