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
- The client calls
POST /mcpwithout a token and gets401withWWW-Authenticate: Bearer resource_metadata="<base>/.well-known/oauth-protected-resource/mcp", scope="read". - 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) andbearer_methods_supported: ["header"]. - 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. - The token must have
audequal to<base>/mcp(built fromDX_MCP_BASE_URL, never fromHost), the configurediss, a valid signature (RS256 from the JWKS) and no expiry. Anything else is401 invalid_token. A token in the query string is ignored. - Effective permissions = the token's scopes ∩ the user's role in the organization (T13
membership; the claim
dx_orgselects an organization). No membership →403. - Step-up: calling a tool that needs a scope the token lacks gives
403withWWW-Authenticate: Bearer error="insufficient_scope", scope="write", resource_metadata=…; the client re-authorizes with the wider scope. When the role itself forbids it the403has 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.