Docs / OAuth

OAuth

Authorization is opt-in by URL: everything under /protected/ requires a bearer token, and everything else stays open. The mock is both the MCP server and its own authorization server, on the same origin and without state — so the official SDK's OAuth flow runs end to end against it.

Protected endpoints

Every endpoint is served again under /protected/, identical except for the token: /protected/mcp, /protected/2026-07-28/mcp, /protected/2024-11-05/sse…

RequestAnswer
No token401 with WWW-Authenticate naming the metadata and the mcp scope
Invalid, expired, or issued for another endpoint401 · invalid_token
Valid, without the mcp scope403 · insufficient_scope
ValidServed as the open endpoint would
curl -i http://localhost:3000/protected/mcp -X POST …

# HTTP/1.1 401 Unauthorized
# WWW-Authenticate: Bearer scope="mcp",
#   resource_metadata="http://localhost:3000/.well-known/oauth-protected-resource/protected/mcp"
#
# {"error":"unauthorized","error_description":"Authorization required"}
Tokens are only read from the Authorization header, and must have been issued for that very endpoint (RFC 8707): a token for /protected/mcp is refused on /protected/2025-11-25/mcp. The token is checked before x-mcp-mock-status, so a forced failure never hides a missing credential.

Discovery

URLs are built from the request's origin, so they are right behind a proxy or on a random test port.

URLServes
/.well-known/oauth-protected-resource/protected/…Protected Resource Metadata (RFC 9728), one document per protected endpoint
/.well-known/oauth-authorization-serverAuthorization server metadata (RFC 8414)
/.well-known/openid-configurationThe same metadata, as OpenID Connect discovery
/oauth/authorizeAuthorization endpoint
/oauth/tokenToken endpoint
/oauth/registerDynamic Client Registration (RFC 7591)
# GET /.well-known/oauth-protected-resource/protected/mcp
{ "resource": "http://localhost:3000/protected/mcp", "authorization_servers": ["http://localhost:3000"],
  "scopes_supported": ["mcp"], "bearer_methods_supported": ["header"] }

# GET /.well-known/oauth-authorization-server
{ "issuer": "http://localhost:3000",
  "authorization_endpoint": "http://localhost:3000/oauth/authorize",
  "token_endpoint": "http://localhost:3000/oauth/token",
  "registration_endpoint": "http://localhost:3000/oauth/register",
  "response_types_supported": ["code"], "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"], "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp"], "client_id_metadata_document_supported": true,
  "authorization_response_iss_parameter_supported": true }

The flow

Authorization code with PKCE, as the MCP spec requires. There is no login page: the user always approves at once.

1. Register (optional)

POST /oauth/register with JSON client metadata; redirect_uris must list absolute URLs. It answers 201 with the metadata plus a client_id derived from it — the same client always registers to the same id — and token_endpoint_auth_method: "none". Any non-empty client_id is accepted, so registration can also be skipped.

2. Authorize

GET /oauth/authorize with response_type=code, client_id, an absolute redirect_uri, code_challenge with code_challenge_method=S256, resource (the endpoint's canonical URI), and optionally scope (default mcp) and state. It redirects straight back with code, state and iss (RFC 9207). Codes live 60 seconds.

# 302 Found
Location: http://localhost:8080/callback?code=mcpmock_code.…&state=xyz&iss=http%3A%2F%2Flocalhost%3A3000

3. Exchange the code

curl http://localhost:3000/oauth/token \
  -d grant_type=authorization_code -d code=mcpmock_code.… -d client_id=my-client \
  -d redirect_uri=http://localhost:8080/callback -d code_verifier=…

# { "access_token": "…", "token_type": "Bearer", "expires_in": 3600,
#   "refresh_token": "…", "scope": "mcp" }

The client_id, redirect_uri and code_verifier must match the authorization request, and resource, if sent, too. Access tokens last an hour. grant_type=refresh_token issues a new access token for the same client, scope and resource, and keeps the refresh token.

With the SDK

Give the transport an authProvider. Because the mock redirects at once, your redirectToAuthorization can just fetch the URL and read the code off the Location header.

const url = new URL("http://localhost:3000/protected/mcp");
let code = "", iss = "";
const authProvider = {
  // redirectUrl, clientMetadata, clientInformation, saveClientInformation,
  // tokens, saveTokens, saveCodeVerifier, codeVerifier …
  async redirectToAuthorization(authUrl) {
    const res = await fetch(authUrl, { redirect: "manual" });
    const location = new URL(res.headers.get("location"));
    code = location.searchParams.get("code");
    iss = location.searchParams.get("iss");
  },
};

// 1. The first connection discovers everything, registers and redirects → UnauthorizedError
await new Client(info).connect(new StreamableHTTPClientTransport(url, { authProvider })).catch(() => {});

// 2. Exchange the code for tokens
await new StreamableHTTPClientTransport(url, { authProvider }).finishAuth(code, iss);

// 3. Connect for real
const client = new Client(info);
await client.connect(new StreamableHTTPClientTransport(url, { authProvider }));

The flow works on modern and legacy connections alike.

Provoking failures

Two mock-only switches reach the failure paths a real authorization server rarely offers on demand.

SwitchWhereEffect
mcp-mock:deny scope/oauth/authorizeThe user denies access: the redirect carries error=access_denied
mcp_mock_expires_in/oauth/tokenIssues an access token that expires after that many seconds, from 1 to 86400 — to test expiry and refresh

The spec's own failures are there too: a missing PKCE challenge is invalid_request, a resource that is not an absolute URI is invalid_target, a wrong verifier, client or redirect URI is invalid_grant, an unknown grant type is unsupported_grant_type. Errors that cannot be trusted to a redirect URI — a missing client_id or a malformed redirect_uri — are answered directly instead of redirected.

Caveats

This is a test double, not an authorization server for real users. Codes and tokens are signed with a fixed, public key and are self-contained, so nothing is stored — and an authorization code is not single-use. Never put /protected/ in front of anything that matters.