MCP OAuth 2.1 and PKCE, Explained Step by Step

This walkthrough uses the MCP 2026-07-28 authorization specification for HTTP-based transports. Authorization is optional in MCP; HTTP implementations supporting it should follow the specification. Local stdio credentials follow a different model. MCP authorization scope.

This post walks the flow step by step, explaining what each moving part does and which attack it exists to prevent. If you want the strategic comparison against static credentials instead, see MCP server authentication: OAuth 2.1 vs API keys; for the full security surface beyond authentication, see the MCP server security checklist.

If your connection is already failing, start with MCP OAuth troubleshooting, which includes a downloadable local HTTP lab and repeatable negative cases.

The cast of characters

Four parties participate in MCP authorization:

• The MCP client — the agent, IDE, or application that wants to call tools. In OAuth terms, the client.
• The MCP server — the tool provider and protected resource. Token issuance is a separate role, even when an authorization server is hosted alongside it.
• The authorization server (AS) — the system that authenticates clients (and users, where flows are user-delegated), and mints tokens. May be your IdP, a cloud provider's OAuth service, or a dedicated service.
• The resource owner — for user-delegated flows, the human whose authority the client exercises; for machine-to-machine flows, effectively the organization.

The useful separation is between discovering an authorization service, establishing a client identity, and authorizing a particular resource operation. Discovery can reduce manual configuration, but pre-registration, enterprise policy, or user consent may still be needed.

Step 1: Discovery via protected-resource metadata

The client follows a resource_metadata pointer in a Bearer challenge when one is present, or falls back to the defined well-known metadata locations. Protected-resource metadata identifies the resource and its authorization servers. The client then discovers the selected server's OAuth or OpenID Connect metadata and checks that its issuer agrees with the expected issuer. MCP discovery requirements.

Deployment check: record the resource, issuer, and discovered endpoints together. A successfully fetched JSON document does not establish trust by itself; validate its contents and the transport before using its endpoints. RFC 9728 protected-resource metadata, RFC 8414 metadata validation.

Step 2: Client registration

Use available pre-registered client information first. Otherwise, use Client ID Metadata Documents when the authorization server advertises support, with Dynamic Client Registration as a deprecated compatibility fallback. CIMD uses a self-hosted HTTPS URL as the client ID. Pre-registered and DCR-issued credentials remain associated with the authorization server that issued them. MCP client registration.

Deployment check: test the mechanism your client actually uses. A CIMD URL is a client identifier, not a secret or an automatic grant of tool access. Confirm redirect URI validation and that credentials issued by one authorization server are not silently reused against another.

Step 3: The PKCE-protected authorization

For user-delegated access, the client runs the OAuth 2.1 authorization-code flow — and the MCP spec makes PKCE (Proof Key for Code Exchange) mandatory, for confidential clients as well as public ones.

PKCE works in three moves: the client generates a random secret (the code verifier) and sends a hash of it (the code challenge) with the authorization request; the AS remembers the challenge and issues an authorization code; when the client exchanges the code for tokens, it must present the original verifier, which the AS hashes and compares. The verifier never travels until the final, TLS-protected token request.

Deployment check: use the S256 challenge method and test that an incorrect verifier fails. Keep the verifier out of URLs and logs. PKCE addresses authorization-code interception; it does not repair an untrusted redirect target or stolen access token. RFC 7636.

For machine-to-machine access, a client credentials grant may fit when the authorization server, client, and deployment policy support it. Do not substitute a machine identity for a user's delegated access without checking the intended authority. The agent authentication guide covers that design decision.

Before redeeming an authorization code, compare a present iss against the issuer recorded for this request. A missing value requires rejection when the authorization server advertised support. Do not normalize strings to make a mismatch pass. RFC 9207 issuer validation.

Step 4: The resource-bound token request

Include resource in both the authorization request and token request, naming the intended MCP resource. Resource indicators let the authorization server restrict a token to its intended audience. The resource server must enforce that audience restriction; adding a request parameter without validating the resulting token is insufficient. RFC 8707.

Deployment check: obtain a token for a different test resource and confirm rejection. This checks an actual boundary, rather than assuming that two resources trusting the same issuer must have separate access.

Step 5: Presentation and verification

Present the access token in the Authorization: Bearer header, rather than a query string. Validate it using the authorization server's supported method: cryptographic validation for an applicable signed token, or the appropriate server-side validation for an opaque token. Enforce expiry, trusted issuer, intended audience, and the permissions required for the operation. Decoding a JWT payload alone does not validate it. Bearer token usage, MCP authorization security requirements.

Two server-side disciplines complete the picture. First, keep downstream authorization separate: do not pass the incoming MCP token to an unrelated API. Use credentials or an appropriately scoped downstream authorization flow for that resource. Second, token acceptance does not establish that every tool action is allowed. Enforce tool and argument permissions at the point of execution; see the MCP server governance guide.

The flow at a glance

1. Discover and validate protected-resource and authorization-server metadata.
2. Obtain a client ID through the supported registration mechanism.
3. For delegated access, run authorization code with PKCE and validate the response issuer.
4. Include the intended resource when authorizing and requesting the token.
5. Present the token; validate it and authorize the actual tool action.

Test the failure cases as well as the successful flow. Incorrect issuer, wrong resource, expired token, and insufficient permissions should produce distinct diagnostic evidence without exposing credentials in logs.

Common questions

Which protocol revision does this walkthrough use? MCP 2026-07-28 for HTTP-based authorization. Pin the supported protocol and SDK versions in your deployment; this walkthrough does not describe stdio credential handling.

What does PKCE actually protect against? Interception and injection of the authorization code. The code alone becomes worthless: redeeming it requires the code verifier, a secret that never leaves the client until the final token request. PKCE costs one random string and one hash per flow.

What is an RFC 8707 resource indicator? A parameter naming the intended resource. MCP includes it in authorization and token requests; verify that the resulting audience restriction is enforced by the resource server.

Does my MCP server need to be its own authorization server? No. It can publish metadata identifying a separate authorization server and validate its tokens. The roles may also be hosted together; keep their responsibilities distinct.

Is authentication enough to make an MCP server safe to expose? No. The flow above establishes verified identity and audience-bound access — the foundation. What the caller may do per tool, at what rate, with what content flowing through, is a governance layer on top: tool scoping, guardrails, and audit, covered in the MCP server security checklist.