Skip to main content
Some deployments terminate authentication at a reverse proxy or gateway. The proxy verifies the caller and forwards the resolved identity as request headers. Configure a RequestVerifier to accept that identity. It replaces the bearer-token TokenVerifier in FastMCPOptions.auth.
The verifier runs once per HTTP request, before dispatch. The returned AccessToken becomes ctx.auth, exactly as with a bearer token. Per-tool auth checks, tools/list filtering, and CachingMiddleware partitioning all keep working. Throw AuthorizationError to reject with HTTP 403. Any other error rejects with HTTP 401. The error message is returned to the client in the response body. Do not put secrets in thrown error messages.

Deployment checklist

A RequestVerifier is only as trustworthy as the path between the proxy and this server. Before you trust a header:
  1. Verify provenance in the verifier. Check a shared secret the proxy injects (as above), or terminate mTLS between proxy and server. Never trust identity headers on their own.
  2. Close the direct path. Bind the server to a loopback or private interface, and restrict ingress with network policy so only the proxy can reach it. Anyone who can reach the port directly can send any headers.
  3. Strip inbound identity headers at the proxy. Configure the proxy to overwrite x-auth-request-* (or your chosen names) on every request, so a client cannot smuggle its own values through.
  4. Redact your secret headers. Add the provenance secret and any other deployment credentials to http.redactHeaders. They then never appear in ctx.http.headers and can never be forwarded from it.
  5. Keep identity per request. Do not copy identity into session state. The verifier already runs on every request; let ctx.auth be the only identity source.
  6. Do not forward inbound credentials upstream. The MCP specification forbids passing inbound tokens to upstream APIs. Use forwardableHeaders() when forwarding request headers, and mint your own upstream credentials.