Skip to content

ADR-018: roles, scopes and the OAuth flow of the MCP endpoint

Context. Roles and permissions (six roles, 17 permissions, five key scopes) are defined in src/extractit/api/auth/matrix.py and documented in Roles and permissions. T47 adds OAuth 2.1 access to the MCP endpoint.

Decision (T47).

  • The MCP endpoint is an OAuth 2.1 protected resource (RFC 9728 metadata at /.well-known/oauth-protected-resource[/mcp]); the authorization server is the deployment's IdP (T13). No own authorization server.
  • Tokens are validated with FastMCP's JWTVerifier: JWKS signature (RS256), configured issuer, aud equal to the canonical resource URL built from DX_MCP_BASE_URL (never from Host), expiry. API keys are accepted next to tokens (MultiAuth).
  • Effective permissions = token scopes ∩ the permissions of the user's role in the organization. A wider scope that the role allows is requested by step-up (403 insufficient_scope with scope and resource_metadata); a role that forbids it gives a plain 403.
  • Calls reach the API in process as a 60-second internal token (DX-Internal-Auth, HMAC with a per-process secret) accepted by an extra link of the T12 authenticator chain; the client's token is never forwarded.
  • Destructive tools need a person's approval (approval table, 10 minutes, single use, bound to the canonical arguments). Approving needs a human Admin/Owner or a key with admin; agent keys are created without it.

See MCP authorization for the flow and the test matrix.