How an MCP Client Actually Authenticates

A 15-slide walkthrough

The OAuth 2.1 discovery dance that runs before the first tools/list — hop by hop, from a real logged handshake.

6hops

2servers

0dependencies

15slides

Read the long-form version

Press → or space to flip through

THE SETUP

It's a discovery protocol, not 'send a token'

A client doesn't just have a token — it has to find metadata, register itself (or not), prove it owns a client, and only then retry the request that started everything.

To watch every hop, I built a zero-dependency playground: two servers in one Node process, every request and response printed to a log.

MCP resource server

http://localhost:3001/mcp — minimal streamable-HTTP MCP server. Answers 401, serves metadata, runs tools.

OAuth authorization server

http://localhost:3002 — discovery metadata, Dynamic Client Registration, authorize + token endpoints.

Zero dependencies

No npm install. Point a real MCP client at it and watch the whole handshake happen hop by hop.

Ring-buffer logs

Every request and response — headers included — prints to the console and lands in a log buffer.

STEP 1 OF 6

POST the request, get a 401

1401
2resource
3discover
4register
5PKCE
6Bearer

The client optimistically POSTs initialize with no token.
The server answers 401 with a WWW-Authenticate challenge. The resource_metadata parameter is the first hint about where to go.

POST /mcp — no token
POST /mcp HTTP/1.1
Content-Type: application/json
 
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}

401 Unauthorized
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="http://localhost:3001/.well-known/oauth-protected-resource/mcp", scope="mcp"

STEP 2 OF 6

Fetch the protected-resource metadata

1401
2resource
3discover
4register
5PKCE
6Bearer

The resource_metadata URL from the 401 serves an RFC 9728 document.
It names the trust chain: authorization_servers, supported scopes, and bearer methods.
This is a resource saying: "I don't do auth myself — go talk to this authorization server."

.well-known/oauth-protected-resource/mcp
{
  "resource": "http://localhost:3001/mcp",
  "authorization_servers": ["http://localhost:3002"],
  "scopes_supported": ["mcp", "tools:execute"],
  "bearer_methods_supported": ["header"]
}

STEP 3 OF 6

Discover the authorization server

1401
2resource
3discover
4register
5PKCE
6Bearer

Given the AS URL, the client fetches RFC 8414 metadata for authorization_endpoint and token_endpoint.
One field matters more than it looks: registration_endpoint. If it exists, the client can try to register dynamically.

.well-known/oauth-authorization-server
{
  "issuer": "http://localhost:3002",
  "authorization_endpoint": "http://localhost:3002/authorize",
  "token_endpoint": "http://localhost:3002/token",
  "registration_endpoint": "http://localhost:3002/register",
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"]
}

STEP 4 OF 6

Register — or use a preconfigured client

1401
2resource
3discover
4register
5PKCE
6Bearer

If registration_endpoint exists, the client POSTs a Dynamic Client Registration (RFC 7591) request.
Success yields a fresh client_id — often with no secret for public clients.
If registration fails — or there is no endpoint — it falls back to a preconfigured client_id.

POST /register
POST /register HTTP/1.1
Content-Type: application/json
 
{
  "client_name": "demo-mcp-client",
  "application_type": "native",
  "redirect_uris": ["http://localhost:8899/callback"],
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "none"
}

201 Created
HTTP/1.1 201 Created
 
{"client_id":"dcr_29fb191653353561","client_name":"demo-mcp-client","redirect_uris":["http://localhost:8899/callback"],"token_endpoint_auth_method":"none"}

STEP 5 OF 6

Run the authorization-code flow with PKCE

1401
2resource
3discover
4register
5PKCE
6Bearer

Textbook public-client flow: PKCE S256 because there is no secret, plus a resource parameter so the token is scoped to the MCP server.
The client validates iss on the redirect, then exchanges the code at the token endpoint.

GET /authorize
GET /authorize?
  response_type=code&
  client_id=dcr_...&
  redirect_uri=http://localhost:8899/callback&
  scope=mcp+tools:execute&
  code_challenge=...&code_challenge_method=S256&
  resource=http://localhost:3001/mcp

POST /token — access granted
HTTP/1.1 200 OK
 
{"access_token":"mcp_...","token_type":"Bearer","expires_in":3600,"scope":"mcp tools:execute"}

STEP 6 OF 6

Retry the request with the token

1401
2resource
3discover
4register
5PKCE
6Bearer

The original initialize is retried with Authorization: Bearer ….
200. The client can now do the real work — tools/list, tools/call, and friends.

POST /mcp — Bearer token
POST /mcp HTTP/1.1
Authorization: Bearer mcp_...
Content-Type: application/json

200 OK
HTTP/1.1 200 OK
 
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"understanding-mcp","version":"0.1.0"}}}

Finding

METADATA HUNTING

The 401 may not tell you where the metadata lives

RFC 9728 lets the challenge carry resource_metadata — but it does not have to.
When it's missing, the client constructs the well-known URI from a fixed template — an educated guess baked into the MCP spec.
Flip it off in the playground and the log shows the client deriving the URI instead of trusting the header.

no resource_metadata?
WWW-Authenticate: Bearer scope="mcp"
 
<base_url>/.well-known/oauth-protected-resource/<remaining_path>
https://example.com/.well-known/oauth-protected-resource/mcp

Finding

DCR IS BEST-EFFORT

Metadata is a promise, not a guarantee

A registration_endpoint only means the endpoint exists — not that your registration will be accepted.
Real servers (Figma is famous for it) enforce redirect-URI whitelists. /register responds, yet registration fails.
A robust client treats DCR as best-effort and falls back to a preconfigured client_id.

400 — registration rejected
HTTP/1.1 400 Bad Request
 
{"error":"invalid_redirect_uri","error_description":"redirect_uri not allowed by server policy"}

fallback path
!! registration rejected (400)
registration_endpoint was advertised but registration failed - falling back to preconfigured client_id
client_id=preconfigured-client, redirect_uri=http://localhost:8899/callback

Finding

THE SHORTCUT

A preconfigured client_id skips DCR entirely

Configure a client_id for a server and /register is never called.
The client jumps from AS metadata straight to authorization_endpoint + token_endpoint.
Debugging frame shift: a client that "just works" with a token may never have registered at all.

notice what is missing
AUTH REQUEST  GET /.well-known/oauth-authorization-server  ->  200
AUTH REQUEST  GET /authorize?...&code_challenge=S256&resource=http://localhost:3001/mcp  ->  302
AUTH REQUEST  POST /token  ->  200
     {"access_token":"mcp_...","token_type":"Bearer","expires_in":3600,"scope":"mcp tools:execute"}

Finding

SCOPE AT RUNTIME

Scope checks happen at runtime, not just at login

A token with mcp but not tools:execute can call initialize and tools/list fine.
tools/call → 403 insufficient_scope. That is a step-up trigger, not a login failure.
Treat it as an instruction to re-negotiate scope — not a bug in your token.

403 — authenticated but under-scoped
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="tools:execute"

FROM THE LOGS

A real trace, start to finish

A real IDE client negotiating 2025-11-25 down to the server's 2025-06-18, registering dynamically, and getting a token:

captured handshake
MCP  REQUEST  POST /mcp   ->  401
     WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource/mcp", scope="mcp"
MCP  REQUEST  GET /.well-known/oauth-protected-resource/mcp  ->  200
     {"resource":"http://localhost:3001/mcp","authorization_servers":["http://localhost:3002"],...}
AUTH REQUEST  GET /.well-known/oauth-authorization-server  ->  200
     {"issuer":"http://localhost:3002", ...,"registration_endpoint":"http://localhost:3002/register"}
AUTH REQUEST  POST /register  ->  201
     {"client_id":"dcr_29fb191653353561","client_name":"Windsurf","redirect_uris":["http://127.0.0.1:8765/auth/callback"],"token_endpoint_auth_method":"none"}
AUTH REQUEST  GET /authorize?...&code_challenge=...&code_challenge_method=S256&resource=http://localhost:3001/mcp  ->  302
AUTH REQUEST  POST /token  ->  200
     {"access_token":"mcp_...","token_type":"Bearer","expires_in":3600,"scope":"mcp tools:execute"}
MCP  REQUEST  POST /mcp  (Authorization: Bearer mcp_...)  ->  200
     {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},...}}
MCP  REQUEST  POST /mcp  (tools/list)  ->  200
     {"tools":[{"name":"echo",...}]}

TRY IT

Reproduce it yourself

Zero-dependency repo — no npm install, just Node 18+:

two terminals
node server.js        # terminal 1: watch every request/response
node client.js        # terminal 2: drive the full flow end-to-end
 
# Finding 1: 401 without resource_metadata -> client derives the URI
WWW_AUTH_RESOURCE_METADATA=off node server.js
 
# Finding 2: DCR advertised but redirect URI not whitelisted -> fallback
DCR_ALLOWED_REDIRECT_URIS='http://only-whitelisted.example/callback' node server.js
 
# Finding 3: no DCR at all -> preconfigured client_id only
AUTH_DCR=off node server.js

github.com/igagansingh/understanding-mcp

TAKEAWAYS

The MCP auth story is a discovery protocol

Challenge, two metadata documents, registration-or-preconfigured, PKCE, and scope checks that outlive the login. The spec covers the happy path; the interesting engineering is in the fallbacks.

Register best-effort

DCR is a fallback path, not a guarantee.

Fall back to a configured client

A preconfigured client_id skips /register entirely.

Validate iss

Public clients live and die by PKCE + issuer checks.

403 ≠ token bug

insufficient_scope means re-negotiate scope.

Read the long-form version Previous: connecting to an MCP server

← → or space to flip

long-form ↗

Prefer reading over flipping? Read the full written version →