MCP OAuth 2.1 Quick Reference

The Five MCP OAuth 2.1 Endpoints

• the MCP spec adopted CIMD (Client ID Metadata Documents) as the default registration method in the 2025-11-25 revision. if a client uses a CIMD URL as its client_id, /register is never called — the authorization server fetches the client's metadata from the URL instead. /register is still important for backwards compatibility with DCR clients, so don't rip it out.
• opinion: /revoke is listed as "optional" in OAuth 2.1, but that's the kind of optional that turns into a security incident in 18 months. MCP clients sign users out, devices get lost, refresh tokens leak. ship /revoke. it's twelve lines of code and it's the difference between "user logged out" and "token still works until it expires three days from now." it's the most underused endpoint in the whole spec and arguably should have been required.

The PKCE Flow, in One Diagram

1. client generates a random code_verifier (43-128 chars, unreserved URL characters).
2. client computes code_challenge = BASE64URL(SHA256(code_verifier)). method must be S256. plain exists in the spec but provides no security benefit — do not use it.
3. client opens the system browser to /authorize with code_challenge, client_id, redirect_uri, scope, state, and resource.
4. user logs in and consents. server redirects to the client's redirect_uri with ?code=<code>&state=<state>.
5. client POSTs the code and the original code_verifier to /token. server verifies SHA256(code_verifier) == code_challenge from step 3 and returns tokens.

curl -X POST https://auth.example.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=abc123" \
  -d "redirect_uri=http://127.0.0.1:34567/callback" \
  -d "client_id=https://cursor.com/.well-known/oauth-client/mcp" \
  -d "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" \
  -d "resource=https://server.example/v1/mcp"

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dhl3kJo9sE...",
  "scope": "mcp:tools mcp:resources"
}

• the MCP spec requires S256. always check code_challenge_methods_supported in the discovery document before assuming. if plain shows up, the server is non-compliant for MCP — don't paper over it, fix it.
• MCP clients usually redirect to a loopback address with a dynamic port (http://127.0.0.1:<port>/callback). the authorization server must allow flexible port matching per RFC 8252. if an auth server insists on an exact port match, every client restart breaks the flow.
• include the state parameter and verify it on the callback. skipping state opens the door to CSRF on the authorization response. it's two extra lines. just do it.

Scopes and Audience-Bound Tokens

• mcp:tools — call tools/list and tools/call
• mcp:resources — read MCP resources
• mcp:prompts — read MCP prompts

resource=https://server.example/v1/mcp

What the Discovery Document Looks Like

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "registration_endpoint": "https://auth.example.com/register",
  "revocation_endpoint": "https://auth.example.com/revoke",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_basic"],
  "scopes_supported": ["mcp:tools", "mcp:resources"]
}

• token_endpoint_auth_methods_supported must include none to support public clients (desktop apps, CLIs). public clients can't safely store a client_secret — that's the whole reason PKCE exists.
• code_challenge_methods_supported must be ["S256"]. if plain shows up, the server is non-compliant for MCP.
• jwks_uri is not strictly required by RFC 8414, but if the server issues JWT access tokens, it's needed so resource servers can validate signatures.
• if the server supports the device-code flow for headless clients (CLI agents, CI runners), also include "urn:ietf:params:oauth:grant-type:device_code" in grant_types_supported.

{
  "resource": "https://server.example/v1/mcp",
  "authorization_servers": ["https://auth.example.com"],
  "scopes_supported": ["mcp:tools", "mcp:resources"]
}

What Changes for Enterprise