← All guides · MCP in practice

How to Implement OAuth 2.1 for an MCP Server

Part 2 of MCP in practice · 1,548 words · published 2026-08-07 · updated 2026-08-07 · Markdown variant

A wire-level implementation walkthrough for OAuth 2.1 on a remote MCP server: what the discovery documents actually contain, CIMD vs. Dynamic Client Registration in your server code, per-SEP detail from the 2026-07-28 hardening set, and token-validation mechanics.

Part of the MCP Server in Production: How to Build, Ship and Run One guide.

The auth section of MCP server in production covers what a compliant OAuth 2.1 flow requires: PKCE, RFC 8707 audience binding, the confused-deputy prohibition. It is a checklist, not a wire trace — it tells you the five steps exist without showing what actually crosses the network at each one, or what changes in your server's own code between the two client-registration paths. This article is that wire trace, plus what the six 2026-07-28 hardening SEPs concretely make you implement.

Everything below assumes a remote Streamable HTTP server; a stdio server has no OAuth surface at all, and that decision is covered in stdio vs. Streamable HTTP.

What the discovery documents actually contain

A client does not guess your authorization endpoints — it fetches two static JSON documents, in order, before it can authenticate at all.

/.well-known/oauth-protected-resource, served from your MCP server's own base URL, is the Protected Resource Metadata defined by RFC 9728. Its job is narrow: tell the client which authorization server(s) your server trusts. A client reads it once at the start of the flow to know where to go next — nothing in it is a credential; it is pure discovery.

/.well-known/oauth-authorization-server, served from the authorization server's own base URL (not yours), is the Authorization Server Metadata defined by RFC 8414. This is the document a client actually parses to build the flow: it returns the authorization_endpoint a client redirects a user to for login and consent, the token_endpoint it POSTs to for the code exchange, and the registration_endpoint it uses if Dynamic Client Registration is in play. If either document is missing, malformed, or wrong, no client can complete the flow regardless of how correctly it implements everything downstream — the most common early-implementation failure is getting PKCE and audience binding right while serving a broken or absent metadata document that never lets a client reach that code at all.

Once discovery resolves, the authorization and token requests each carry two things worth naming because they are easy to omit silently: the resource parameter from RFC 8707, set to your MCP server's own URL, which is what lets the authorization server bind the issued token's audience to your server specifically; and the PKCE pair — a code_verifier the client generates and keeps, and a code_challenge derived from it (S256 only, per the pillar's security guidance) that travels in the authorization request. Your server never sees either PKCE value directly — that exchange happens between the client and the authorization server — but the token your server later validates is the downstream product of both being present and correct.

CIMD vs. DCR: what actually changes in your server's code

The pillar names the priority order between these two client-registration paths; what it does not show is what each one actually requires you to build, and that is where the real implementation cost differs.

Dynamic Client Registration (RFC 7591) requires your authorization server to run a registration endpoint: a POST handler that accepts a JSON payload describing the client (redirect URIs, a display name, a client type), validates it, mints a new client_id (and, for confidential clients, a secret), persists a client record somewhere durable, and returns the credentials. From then on your AS owns a client-record table it has to manage — updating entries when a redirect URI changes, pruning stale registrations, and treating the endpoint itself as attack surface, since it is an unauthenticated POST that creates state.

A Client ID Metadata Document (CIMD) removes that table entirely. The client_id a CIMD-using client presents is itself an HTTPS URL — something the client's own operator controls and serves — pointing at a JSON document describing the client the same way a DCR payload would (redirect URIs, a display name). Your authorization server's job changes from "look up a row this client_id should match" to "fetch this URL and parse what comes back": an HTTP GET at authorization time, rather than a database read against a row a registration call wrote earlier. No registration endpoint to write or secure and no stale-registration cleanup — but a new obligation to fetch that document reliably (sane timeout, TLS verification) every time it is needed, since there is no local "this client is known good" cache the way a database row provides.

If you are implementing the authorization-server side yourself rather than delegating to a provider such as Auth0 or Keycloak: DCR means writing and hardening a registration handler; CIMD means writing a document fetcher and validator, treating the fetched JSON with the same untrusted-input discipline as any external content. Both are legitimate simultaneously — CIMD as the default, DCR retained for clients that have not adopted it — the priority order the pillar describes.

Three of the six 2026-07-28 hardening SEPs, in implementation detail

The pillar lists all six 2026-07-28 authorization SEPs in one paragraph. Three of them require you to actually write new validation or registration-handling code, not just be aware the SEP exists (MCP goes stateless):

• SEP-2468 — iss validation per RFC 9207. Your token-validation code needs an explicit check, separate from audience validation, that the iss claim names the authorization server your Protected Resource Metadata lists as trusted. Without it, a token issued by a different AS your server never declared trust in — but that still passes signature verification — could be redeemed against you. This closes a wrong-server token-redemption bug class that audience binding alone does not.
• SEP-837 — application_type on Dynamic Client Registration. A DCR-capable registration endpoint now needs to read an application_type field from the payload and branch on it, rather than defaulting every client to "web." The failure this fixes: servers assuming "web" for every client were rejecting localhost redirect URIs from desktop and CLI clients, for whom localhost is the normal pattern, not a misconfiguration.
• SEP-2350 — incremental step-up scopes. If your server supports scoped permissions, the re-authorization path needs to accept a request for additional scopes on top of what a client already holds, instead of forcing a full re-grant from zero — a distinct, supported code path, not a config flag.

The other three — SEP-2351 (discovery-suffix clarification), SEP-2352 (credential reissuance on AS migration), SEP-2207 (refresh tokens from OIDC-style servers) — are narrower and situational, and don't reshape every server's validation code the way the three above do.

Token validation: what your handler actually checks, in order

Every authenticated request needs the same sequence of checks, and skipping or reordering them is where implementations quietly become insecure rather than obviously broken:

1. Audience. Does aud match this server's own URL — the resource parameter (RFC 8707) set at authorization time? A token that passes every other check but names a different audience must still be rejected; this is the check that stops a confused-deputy replay.
2. Issuer. Does iss match the authorization server your Protected Resource Metadata names as trusted, per RFC 9207 and SEP-2468? A token can have the right audience and still fail here if issued by an AS you never declared trust in.
3. Signature and validity. Is the token genuine and unexpired — a local signature check against the AS's published signing keys, or a live introspection call to the AS, depending on the token format it issues? The corpus this article draws from specifies the audience- and issuer-binding requirements but not one mandated token format, so confirm which mechanism your AS supports before building against it.

A request failing any of these three gets an HTTP 401, and a compliant response does more than reject it: the WWW-Authenticate header should point back at your Protected Resource Metadata document, so the client can restart discovery from a known-good location. Confirm exact header syntax against RFC 9728 directly before shipping it — the shape is a signpost back to /.well-known/oauth-protected-resource, not a bare rejection.

An honest example, extended

ChangeGamer's own /mcp endpoint is unauthenticated as of August 2026 — no OAuth flow, no RFC 9728 metadata — because it is public and read-only, with paid content gated at the application layer instead. What that gate actually covers — the current premium resource list and its pricing — is published separately at access and pricing, not embedded in the MCP tool schema. Adding OAuth would concretely mean: standing up the two discovery documents above (a minimal Protected Resource Metadata pointing at one trusted AS), choosing CIMD over a registration endpoint (ChangeGamer only needs to vet its own clients, not arbitrary ones), and replacing the current api_key argument check with the three-step token validation above — a materially larger surface than today's single string comparison. That gap is why the pillar treats unauthenticated-but-key-gated as legitimate for a narrow, read-only case, not a shortcut every server should take.

Where this leaves you

The discovery documents, CIMD's document-fetch model, the three SEPs that add real validation code, and the three-check token-validation sequence above are the parts of OAuth 2.1 for MCP that only show up once you are implementing it, not just deciding to require it. For the decision-level version — whether you need OAuth at all, the confused-deputy rule, the CIMD/DCR priority order — see the auth section of MCP server in production; for the broader security posture beyond auth specifically, see the agentic security checklist.

#mcp #agents #protocols #oauth #security #production