Skip to content

Auth Modes

Jump to bottom
sarmakska edited this page May 31, 2026 · 2 revisions

Auth Modes

Three modes, selected with the MCP_AUTH env var. Auth applies to the HTTP transport; stdio relies on the operating system process boundary. /health is always open so it works as a readiness probe.

none

No auth. The default. Use it for stdio or behind a trusted private network.

api_key

Set a long random key and clients send it in the X-API-Key header. The comparison is constant time, so it does not leak the key through timing.

MCP_AUTH=api_key
MCP_API_KEY=$(openssl rand -hex 32)
curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/tools

A missing or wrong key returns 401.

oauth

OAuth 2.1. The server acts as a protected resource: it validates the bearer token as a JWT against the issuer's published JWKS, checking the issuer and audience and requiring an expiry. The accepted signing algorithm set is fixed to asymmetric algorithms (RS256, ES256, RS384, RS512).

MCP_AUTH=oauth
MCP_OAUTH_ISSUER=https://your-id-provider.com
MCP_OAUTH_AUDIENCE=mcp-toolkit
# Optional: skip discovery by pointing straight at the JWKS endpoint
MCP_OAUTH_JWKS_URI=https://your-id-provider.com/.well-known/jwks.json

When MCP_OAUTH_JWKS_URI is unset the server discovers it from the issuer's /.well-known/openid-configuration. Keys are cached and refetched on rotation, so a key roll upstream does not need a restart.

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/mcp -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Getting a token: the PKCE login flow

mcp-toolkit login runs the OAuth 2.1 authorisation code flow with PKCE against a hosted server. It discovers the authorisation server metadata, opens the browser, captures the redirect on a one-shot loopback listener, and exchanges the code for a token.

MCP_OAUTH_CLIENT_ID=your-public-client-id
MCP_OAUTH_REDIRECT_URI=http://127.0.0.1:8765/callback

uv run mcp-toolkit login --issuer https://your-id-provider.com --client-id your-public-client-id

It prints the access token, which you then send as a bearer token to the server.

Picking a mode

Scenario Pick
Local agent only (desktop, IDE) none (stdio)
Single-tenant team server api_key
Multi-tenant or user-scoped sessions oauth
Public deployment api_key or oauth plus MCP_RATE_LIMIT_RPS

Rate limiting is independent of the auth mode: set MCP_RATE_LIMIT_RPS (and optionally MCP_RATE_LIMIT_BURST) to cap per-client request rates. Clients are keyed by API key, bearer token, or remote address. Exhausted clients receive 429.

Clone this wiki locally