Skip to main content
A bearer token works for whoever holds it. (Agent tokens, the ta_ strings, can be bound too: see sender constrained agent tokens.) If an agent’s token leaks from a log or a proxy, the thief can call your tools. DPoP closes that gap: the token carries the thumbprint of a key the client holds, and every request has to include a short-lived proof signed with that key. DPoP is opt-in. Without dpop in your MCP config nothing changes.
A client sends a token and a DPoP proof signed with its key to the resource server, which accepts it. A thief with only the token is refused.

A stolen token is useless without the client's key.

Turn it on

Both metadata documents then list dpop_signing_alg_values_supported. The protected resource document also sets dpop_bound_access_tokens_required when required is on.

What the token endpoint does

When a request carries a DPoP header, the endpoint verifies the proof (typ, algorithm, public jwk, signature, htm, htu, iat, jti replay) and issues an access token with cnf: { jkt } and token_type: "DPoP". Without a header you get a normal bearer token, unless required is set. The non-interactive grants (client credentials, token exchange, jwt-bearer) honor the proof the same way. See MCP server grants. The proof is checked before the authorization code is consumed. When requireNonce is on and the proof has no valid nonce, the endpoint answers 400 use_dpop_nonce with a DPoP-Nonce header and leaves the code alone, so the client retries with the same code and a fresh proof. Refresh tokens inherit the binding. A refresh request signed by a different key is refused before the token rotates, so a thief cannot burn the real client’s token. Your storeToken callback should persist dpopJkt from the stored record, otherwise the binding is lost on refresh. The built-in createMcpResponseHelpers(...).tokenResponse and every framework adapter copy the nonce into the DPoP-Nonce header. If you write your own token route, read result.error.details?.dpopNonce.

Protect a handler

requireMcpAuth wraps any (Request) => Response function. It accepts Authorization: Bearer and, with DPoP enabled, Authorization: DPoP.
The client sends Authorization: DPoP <token> plus DPoP: <proof> where the proof is signed for the exact method and URL and includes ath, the base64url SHA-256 of the token. Use a new jti every time. The client helper below does all of that for you.

What gets checked

  • Token: signature, issuer, expiry, audience against expectedAudience or McpConfig.resource, then revocation (the jti denylist and, for delegated tokens, the live delegation binding, depending on the freshness mode).
  • Proof: htm, htu (query and fragment ignored), iat window, ath, nonce, jti not seen before, and the proof key matching cnf.jkt.
  • Bearer downgrade: a bound token sent as Bearer is refused. This also covers validateToken, middleware, withMcpAuth and requireScopes.
  • A DPoP scheme request carrying an unbound token is refused.
  • Scopes: a shortfall returns 403 insufficient_scope.
DPoP and revocation answer different questions. The cnf.jkt match says the caller holds the key the token was issued to. The revocation check says the authority behind the token is still alive. Both run, and the proof checks run first because they need no database read, so a request with a bad proof never reaches the revocation store. Revocation sits before the scope check, so a revoked token gets 401, never a 403 step up. An exchanged token is bound to the key of the exchange request, and a DPoP bound subject token needs a proof from the same key. Introspection reports cnf.jkt and token_type: "DPoP", but it does not see your request. A resource server that introspects must still verify the proof itself. Replay protection for proof jti values is per process unless you set a shared storage in the DPoP config, which matters with more than one instance. Options: requiredScopes, expectedAudience, resourceUrl (the public URL clients sign, for proxies), resourceMetadataUrl, requireDpop, requireNonce.

Challenges

With no credentials the response is 401 with Bearer resource_metadata="..." and, if DPoP is on, a second DPoP algs="ES256 ...", resource_metadata="..." header. Bad tokens return error="invalid_token", bad proofs error="invalid_dpop_proof", and a missing nonce error="use_dpop_nonce" with a DPoP-Nonce header. The resource_metadata URL points at the RFC 9728 document so MCP clients can find your authorization server.

The principal

Client helper

@glinr/theauth-client ships createDPoPClient and createDPoPProver. They use WebCrypto only, so they run in browsers, Node, Bun, Deno and edge runtimes. Both sign with ES256.
What it does on each call:
  • Builds a proof with htm, a normalized htu (scheme, host and path, query and fragment dropped), iat, a fresh jti, ath when there is an access token, and nonce when one is cached for the origin.
  • Sets Authorization: DPoP <token> when an access token is given, per request through the third argument or as the accessToken option (a string or a function).
  • Reads DPoP-Nonce from every response and caches it per origin.
  • On a use_dpop_nonce challenge (a 400 or 401 with a DPoP-Nonce header) it retries once with the new nonce and a new proof.

Nonce flow

With dpop.requireNonce on the server, the first request has no nonce:
  1. The client sends a proof without a nonce.
  2. The server answers 400 use_dpop_nonce (token endpoint) or 401 with WWW-Authenticate: DPoP error="use_dpop_nonce" (resource), plus a DPoP-Nonce header. The authorization code is not consumed.
  3. The helper stores the nonce, signs a new proof that carries it, and retries once.
  4. Later requests to the same origin send the cached nonce. When the server rotates it, the same challenge repeats.
The retry happens once per call. If the second attempt is also a challenge, the response is returned to you.

Keys

The generated private key is non-extractable and lives only as long as the object. A token is bound to that key, so keep using the same one for refresh. To persist it, pass your own key pair, for example one you store in IndexedDB:
Use createDPoPProver when you only need proofs and want to send the request yourself. It exposes createProof({ method, url, accessToken?, nonce? }), thumbprint(), publicJwk, getNonce(url) and setNonce(url, nonce). Share one prover between a token client and a resource client with createDPoPClient({ prover }) so both use the same key and nonce cache.

Adapters and CORS

The token endpoint returns the nonce in error.details.dpopNonce. All ten framework adapters (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit, SolidStart, TanStack and Astro) copy it into the DPoP-Nonce response header on /mcp/token errors, so the retry works through any of them. Before this, only the Hono and Express adapters did. The adapters’ MCP CORS headers also allow the DPoP request header and expose DPoP-Nonce and WWW-Authenticate, which a browser client needs to read the challenge. If you serve the token endpoint some other way, set the same headers yourself.

Limits

  • The replay cache is only as strict as its store. Cloudflare KV is not atomic, so two simultaneous replays can both pass. Use Redis or the database store when that matters.
  • The dpop_jkt authorization request parameter (binding the code to a key up front) is not implemented. The binding starts at the token request.
  • Unbound refresh tokens issued before you enabled DPoP are bound to whatever key first refreshes them. Rotate them out by setting required after a refresh cycle.
Last modified on October 19, 2026