What is PKCE?
PKCE, Proof Key for Code Exchange, is an OAuth extension from RFC 7636 that protects the authorization code flow for apps that cannot keep a secret. The client invents a random verifier, sends its SHA-256 hash with the sign-in request, and later presents the verifier when it trades the code for a token. A stolen code alone buys nothing.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
The client generates a code_verifier: 43 to 128 random characters with at least 256 bits of entropy, new for every sign-in.
It SHA-256 hashes the verifier, base64url-encodes it, and sends that as code_challenge with code_challenge_method=S256 in the authorization request.
The authorization server stores the challenge next to the code it issues after you approve.
The client posts the code and the raw code_verifier to the token endpoint. The server hashes the verifier and compares; a mismatch returns invalid_grant.
Anyone who intercepted the code but not the verifier gets nothing, which is why OAuth 2.1 and the MCP spec make PKCE mandatory.
Source: RFC 7636: Proof Key for Code Exchange by OAuth Public Clients
The attack PKCE stops
In the authorization code flow the sign-in page hands the client a short-lived code, and the client swaps it for a token. The hand-off goes through a redirect, and on a phone or a laptop another program can register for the same redirect and receive the code instead. RFC 7636 calls this the authorization code interception attack. A confidential client would also need its secret to redeem the code; a public client such as a mobile app or a command-line agent has no secret, so the stolen code was enough.
PKCE adds a secret that exists for one sign-in only. The client invents a verifier, sends its hash up front, and reveals the verifier only at the token endpoint, over TLS, straight to the server. The code still travels through the redirect. The verifier never does.
Example: an agent signing in to a board
When Codex connects to a remote MCP server for the first time, it generates a verifier before it opens your browser, and the URL it opens carries the SHA-256 hash as code_challenge with code_challenge_method=S256. You sign in and approve. The server redirects back with a code; Codex posts that code and the raw verifier to the token endpoint. The server hashes what it received, compares it with the challenge it stored, and issues the token. If a process on your machine had grabbed the code first, its token request would fail with invalid_grant, because it never saw the verifier.
The MCP authorization spec makes all of this mandatory: clients must implement PKCE, must use S256 when they can, and must check code_challenge_methods_supported in the server's metadata before starting. If that field is missing the client is required to stop.
PKCE versus a client secret
A client secret proves which application is calling, and only works if the application can hide it. PKCE proves something different: that the party finishing the flow is the one that started it. It needs no shared secret, no server-side storage beyond one hash per pending code, and no change to how the redirect works. That is why OAuth 2.1 requires it for every client, confidential ones included. The two protections are not alternatives; a secret stops impersonation of the app, PKCE stops theft of one sign-in.
Common mistakes
- Falling back to plain. The plain method sends the verifier itself as the challenge, which defeats the purpose against anyone who can read the request. OAuth 2.1 removes it entirely, and a client that has tried S256 must never downgrade.
- Reusing a verifier. One verifier per authorization request. Reuse turns a one-time secret into a password.
- Too little randomness. The RFC asks for at least 256 bits of entropy, typically 32 random bytes base64url-encoded into 43 characters. Timestamps and counters are not random.
- Sending the verifier in the authorization request. Only the hash goes through the browser. The verifier goes to the token endpoint and nowhere else.
FAQ
- Is PKCE only for mobile apps?
- No. RFC 7636 was written in 2015 for native apps that could not hold a secret, but OAuth 2.1 requires PKCE for every client that uses the authorization code flow, including server-side apps that have a client secret. The two protections guard against different attacks.
- What is the PKCE plain method and should I use it?
- With plain, the challenge is the verifier itself, so anyone who can read the authorization request can finish the flow. RFC 7636 allowed it only when SHA-256 was impossible. OAuth 2.1 removes it, and the MCP spec requires S256 whenever the client is capable of it.
- How does an MCP client know the server supports PKCE?
- It reads the authorization server's metadata and looks for code_challenge_methods_supported. The MCP authorization spec says that if the field is absent the client must refuse to proceed, because a server without PKCE would leave the authorization code unprotected.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.