OAuth is disabled by default. Existing MCP configurations continue to work unchanged.
How It Works
When OAuth is enabled, every HTTP request to the MCP server must include a valid JWT bearer token in theAuthorization header. The server validates the token using configured JWKS providers and enforces scope requirements at multiple levels.
All scope enforcement happens at the HTTP transport level per the MCP specification, returning 403 Forbidden responses with WWW-Authenticate headers that enable step-up authorization.
Token Validation
The MCP server validates JWT bearer tokens using JWKS (JSON Web Key Sets). You can configure one or more JWKS providers - either remote JWKS URLs (for production with providers like Keycloak, Auth0, Okta) or symmetric secrets (for development and testing). The MCP OAuth config uses the same JWKS format as the router’s top-level authentication configuration, though it is configured independently. You can point the MCP JWKS to the same JWKS URL as your router authentication, or to a different identity provider entirely.OAuth Discovery (RFC 9728)
When OAuth is enabled, the MCP server exposes a public metadata endpoint at/.well-known/oauth-protected-resource/mcp following RFC 9728. MCP clients use this endpoint to automatically discover the authorization server and all supported scopes without any manual configuration.
The scopes_supported field is automatically computed as the union of all configured static scopes and all scopes extracted from @requiresScopes directives on fields used by registered operations. This means MCP clients can request all supported scopes upfront during the initial OAuth authorization, avoiding step-up challenges entirely.
Get Started
Quickstart
Step-by-step guide to adding OAuth to your MCP server with a working example.
Scope Enforcement
Understand the multi-level scope enforcement model and how scopes combine.
Configuration Reference
Complete reference for all OAuth configuration options, JWKS settings, and error responses.