Blog
11 min read

MCP Authorization Explained: OAuth 2.1, Protected Resource Metadata, and CIMD

How MCP OAuth works for remote servers in the 2026-07-28 spec: OAuth 2.1, protected resource metadata, discovery, CIMD vs dynamic registration, and PKCE.

MCP authorization is OAuth 2.1 with a fixed discovery path. A remote MCP server acts as an OAuth resource server: it answers an unauthenticated request with 401 and a pointer to its Protected Resource Metadata (RFC 9728), which names the authorization server. The client fetches that server's metadata, gets a client ID (preferably via a Client ID Metadata Document, since Dynamic Client Registration is now deprecated), runs the authorization code flow with PKCE and a resource parameter naming the MCP server, and sends the resulting access token as a bearer token on every request. The server must accept only tokens issued for itself, and must never pass them on to upstream APIs.

This applies to HTTP transports only. For local stdio servers the spec says implementations SHOULD NOT follow it and should take credentials from the environment instead (stdio vs Streamable HTTP).

Everything below is from the 2026-07-28 MCP authorization specification and its sub-pages on discovery, client registration and security considerations, checked in November 2026. For what else changed in that revision, see MCP's 2026-07-28 spec.

The roles

Role In MCP Responsibility
Resource server The MCP server Validates access tokens, returns 401/403 with metadata pointers
Client The MCP client (Claude Code, an IDE, an agent) Discovers, registers, runs the flow, stores tokens
Authorization server Your IdP or a dedicated AS Authenticates the user, issues tokens

The authorization server can be the same deployment as the MCP server or a completely separate one (Auth0, Keycloak, Entra ID, your own). The spec deliberately leaves its internals out of scope. That split dates from the 2025-06-18 revision, which classified MCP servers as OAuth resource servers and added protected resource metadata for discovery.

Authorization is optional in MCP. But if an HTTP server does it, it should do it this way, and the requirements below are mostly MUSTs.

Step 1: the 401 challenge

The client sends an MCP request with no token. The server responds:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

Two parameters matter:

  • resource_metadata is the URL of the server's Protected Resource Metadata document.
  • scope (a SHOULD) tells the client which scopes this request needs. The client must treat it as authoritative for the current operation.

Step 2: Protected Resource Metadata (RFC 9728)

MCP servers MUST implement OAuth 2.0 Protected Resource Metadata, and clients MUST use it to find the authorization server. The server must expose it through at least one of two mechanisms:

  1. the resource_metadata parameter in the WWW-Authenticate header, as above, or
  2. a well-known URI, either path-specific or at the root. For an MCP endpoint at https://example.com/public/mcp:
    • https://example.com/.well-known/oauth-protected-resource/public/mcp
    • https://example.com/.well-known/oauth-protected-resource

Clients MUST support both. They use the header value when present, and otherwise probe the well-known URIs in that order (path first, then root).

A minimal document, using RFC 9728's field names:

{
  "resource": "https://mcp.example.com",
  "authorization_servers": ["https://auth.example.com"],
  "scopes_supported": ["files:read"],
  "bearer_methods_supported": ["header"]
}

The MCP spec requires authorization_servers to contain at least one entry. If it lists several, each is an independent authorization server; the client picks one and MUST keep separate registrations and tokens per server.

If the 401 has no scope, the client falls back to requesting all of scopes_supported (or omits scope entirely if that's undefined). The spec intends scopes_supported to be the minimal set for basic functionality, with more requested later through step-up (below). It also says servers SHOULD NOT put offline_access in either place, because refresh tokens are a client concern, not a resource requirement.

Step 3: authorization server discovery

With the issuer URL in hand, the client fetches the authorization server's metadata. The AS must offer RFC 8414 OAuth metadata or OpenID Connect Discovery, and clients MUST support both. For an issuer with a path such as https://auth.example.com/tenant1, clients try, in order:

  1. https://auth.example.com/.well-known/oauth-authorization-server/tenant1
  2. https://auth.example.com/.well-known/openid-configuration/tenant1
  3. https://auth.example.com/tenant1/.well-known/openid-configuration

For an issuer with no path, the first two without the suffix.

Then comes a check that is easy to skip and important not to: the issuer in the fetched document MUST be identical to the issuer used to build the URL. If they differ, the client MUST NOT use the metadata. The spec's example is a document served from attacker.example that claims "issuer": "https://honest.example".

The client also needs code_challenge_methods_supported. If it's missing, the client must assume no PKCE support and refuse to proceed. That applies to OIDC providers too: OIDC Discovery doesn't define the field, so the MCP spec requires authorization servers that offer OIDC Discovery to include it.

Step 4: getting a client ID

MCP clients and servers usually have no prior relationship. Claude Code has never been registered with your company's IdP. The spec offers three ways to get a client_id, with this priority for clients that support all of them:

  1. Pre-registration, if the client already has credentials for this AS.
  2. Client ID Metadata Documents (CIMD), if the AS metadata has "client_id_metadata_document_supported": true.
  3. Dynamic Client Registration (DCR), if the AS metadata has a registration_endpoint.
  4. Otherwise, ask the user to enter client details.

Client ID Metadata Documents

With CIMD, the client ID is an HTTPS URL. The client hosts a JSON document at that URL, and the authorization server fetches it when it sees a URL-shaped client_id:

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback",
    "http://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

The rules, from the client-registration page:

  • The URL MUST be https with a path component, and the client_id inside MUST match the URL exactly.
  • The document MUST include at least client_id, client_name and redirect_uris.
  • The AS MUST validate the match, the JSON structure, and that the redirect URI in the request is in the document. It SHOULD cache the document according to HTTP cache headers.
  • Clients MAY authenticate with private_key_jwt if they publish keys.

The advantage over DCR is that nothing is stored per client on the AS, and the identity is anchored to a domain the client controls. Because the ID is a self-hosted URL, the spec notes that CIMD client IDs are portable across authorization servers, so no re-registration is needed if the server's AS changes.

The security costs land on the AS. Fetching arbitrary client-supplied URLs is a textbook SSRF vector, and the spec tells authorization servers to defend against it. CIMD also can't stop someone impersonating a client that only uses localhost redirects, so authorization servers SHOULD warn about localhost-only redirect URIs and MUST clearly show the redirect hostname on the consent screen. Domain-based trust policies (only accept documents from domains you allow) are permitted.

Dynamic Client Registration (deprecated)

DCR (RFC 7591) lets a client POST to the AS's registration endpoint and receive a fresh client_id. In the 2026-07-28 revision it's deprecated, kept for authorization servers that don't support CIMD. Two requirements still apply if you use it:

  • The client MUST send an appropriate application_type: "native" for desktop apps, CLIs and localhost-served apps, "web" for remotely hosted ones. Under OIDC the default is "web", which can conflict with localhost redirect URIs.
  • Registrations are bound to the issuer that created them. If protected resource metadata starts pointing at a different AS, the client MUST NOT reuse the old credentials and MUST register again.

Step 5: the authorization code flow

Before redirecting the user, the client:

  • generates PKCE values. PKCE is mandatory, with S256 whenever technically possible (PKCE explained),
  • chooses scopes per the strategy above,
  • includes a resource parameter (RFC 8707), and
  • records the expected issuer alongside the PKCE verifier and state.

The resource parameter MUST be sent in both the authorization request and the token request, and MUST be the MCP server's canonical URI, such as https://mcp.example.com or https://mcp.example.com/mcp (no fragment, and preferably no trailing slash). Clients must send it even if the AS doesn't advertise support.

When the code comes back, the client checks the iss parameter (RFC 9207) against the issuer it recorded, before sending the code anywhere. This defends against mix-up attacks, where a malicious AS tricks a client into sending it a code issued by an honest one. The rule is keyed on the AS metadata: if it advertises authorization_response_iss_parameter_supported: true and iss is missing, reject the response; if iss is present, it must match by simple string comparison with no URL normalisation. This applies to error responses too, and on a mismatch the client must not display the error text.

The client then exchanges the code, with code_verifier and resource, for an access token and possibly a refresh token. It MUST NOT assume a refresh token will be issued. For public clients, the AS MUST rotate refresh tokens.

Step 6: using the token

Every HTTP request carries the token in the header:

POST /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list

Never in the query string. Since 2026-07-28 MCP has no sessions, so "every request" really means every request.

On the server side, validation follows OAuth 2.1 section 5.2, plus one MCP-specific requirement: the server MUST verify the token was issued for this server. In practice that usually means checking the aud claim of a JWT access token against your canonical URI, or using token introspection. Invalid or expired tokens get 401.

Step-up: 403 insufficient_scope

If the token is valid but lacks a scope for a particular tool call, the server SHOULD respond:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                         scope="files:write",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"

The client re-authorizes with the union of its previous scopes and the challenged ones, so it doesn't lose permissions it already had. Servers should put every scope the operation needs into a single challenge rather than drip-feeding them, and clients should cap retries.

Token passthrough and the confused deputy

Two rules prevent the most damaging MCP-specific mistakes. Both appear in the spec and in its security best practices.

No token passthrough. Many MCP servers wrap a third-party API. It's tempting to accept whatever token the client sends and forward it upstream. The spec forbids it: servers MUST NOT accept or transit tokens not issued for them, and if the server calls an upstream API, it acts as an OAuth client to that API with a separate token from the upstream AS. Passthrough bypasses the server's own controls (rate limits, audit, validation), and lets a token issued for one service be replayed at another. Audience binding via resource and server-side aud checks is what makes this enforceable.

Confused deputy in OAuth proxies. The best-practices doc describes a specific attack on MCP proxy servers that use one static client ID with a third-party AS, while letting MCP clients register dynamically:

  1. A user authorizes normally; the third-party AS sets a consent cookie for the proxy's static client ID.
  2. An attacker registers a new client with their own redirect URI and sends the user a crafted authorization link.
  3. The third-party AS sees the cookie, skips consent, and the code ends up at the attacker's redirect URI.

The fix: the proxy MUST get the user's consent per MCP client before forwarding to the third-party AS. That means a consent screen showing the client name, the scopes and the redirect URI; consent stored per user and per client_id; exact redirect URI matching; and a single-use state value that's set only after consent is approved. DCR being deprecated doesn't retire this attack while proxies still support it.

Securing MCP servers covers the wider threat model (tool poisoning, prompt injection through tool output, DNS rebinding), and building an MCP server covers the server itself.

A checklist for server builders

  • Return 401 with WWW-Authenticate: Bearer resource_metadata="..." (plus scope).
  • Serve Protected Resource Metadata with at least one authorization_servers entry.
  • Choose an AS that publishes RFC 8414 or OIDC metadata with code_challenge_methods_supported, ideally supports CIMD, and emits iss in authorization responses.
  • Validate every token's audience against your canonical URI. Reject everything else.
  • Use 403 insufficient_scope for step-up, with all required scopes in one challenge.
  • If you call upstream APIs, get your own tokens for them. Never forward the client's.
  • If you're a proxy with a static upstream client ID, implement per-client consent.
  • Serve everything over HTTPS. The spec requires HTTPS for all AS endpoints and HTTPS or localhost for redirect URIs.

EasySpawn gives each environment a live HTTPS URL on a persistent server, which is what a remote MCP server and its metadata endpoints need when you're testing this flow outside localhost. See how it works or join the waitlist.

Related: MCP Transports: stdio vs Streamable HTTP (and What the 2026 Spec Changed) · MCP's 2026-07-28 Specification: A Stateless Protocol and What Breaks · SSRF Explained: When Your Server Fetches URLs for Attackers · OAuth PKCE Explained: Why Every OAuth Flow Should Use It

Keep reading