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…
| Request | Answer |
|---|---|
| No token | 401 with WWW-Authenticate naming the metadata and the mcp scope |
| Invalid, expired, or issued for another endpoint | 401 · invalid_token |
Valid, without the mcp scope | 403 · insufficient_scope |
| Valid | Served 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"}
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.
| URL | Serves |
|---|---|
/.well-known/oauth-protected-resource/protected/… | Protected Resource Metadata (RFC 9728), one document per protected endpoint |
/.well-known/oauth-authorization-server | Authorization server metadata (RFC 8414) |
/.well-known/openid-configuration | The same metadata, as OpenID Connect discovery |
/oauth/authorize | Authorization endpoint |
/oauth/token | Token endpoint |
/oauth/register | Dynamic 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.
| Switch | Where | Effect |
|---|---|---|
mcp-mock:deny scope | /oauth/authorize | The user denies access: the redirect carries error=access_denied |
mcp_mock_expires_in | /oauth/token | Issues 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
/protected/ in front of anything that matters.