## How It Works

When OAuth is enabled, every HTTP request to the MCP server must include a valid JWT bearer token in the `Authorization` 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](https://cosmo-docs.wundergraph.com/router/mcp/oauth/scopes#token-upgrade-flow).

## 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](https://cosmo-docs.wundergraph.com/router/authentication-and-authorization), 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](https://datatracker.ietf.org/doc/rfc9728/). 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.](https://cosmo-docs.wundergraph.com/router/mcp/oauth/quickstart)

[**Scope Enforcement**  
Understand the multi-level scope enforcement model and how scopes combine.](https://cosmo-docs.wundergraph.com/router/mcp/oauth/scopes)

[**Configuration Reference**  
Complete reference for all OAuth configuration options, JWKS settings, and error responses.](https://cosmo-docs.wundergraph.com/router/mcp/oauth/configuration)