Auth Modes

Auth Modes

Three modes. Set with MCP_AUTH env var.

none

No auth. Default. Use for stdio mode (the OS already enforces process boundaries) or behind a private network.

api_key

Set MCP_API_KEY to a long random string. Clients must send it in the X-API-Key header (HTTP transport only).

curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/tools

Generate a key:

openssl rand -hex 32

oauth

OAuth 2.1 with PKCE. Use for multi-tenant deployments where each user has their own session.

Set:

MCP_AUTH=oauth
MCP_OAUTH_ISSUER=https://your-id-provider.com
MCP_OAUTH_AUDIENCE=mcp-toolkit
MCP_OAUTH_JWKS_URI=https://your-id-provider.com/.well-known/jwks.json

The skeleton in auth/oauth.py validates JWTs against the issuer's JWKS. For full provider-specific flows (Auth0, Clerk, Supabase Auth, Keycloak) see the provider docs and adapt.

Picking a mode

Scenario	Pick
Local agent only (Claude Desktop, Cursor)	none (stdio)
Single-tenant team server	api_key
Multi-tenant SaaS	oauth
Public demo with rate limiting	api_key plus a rate limiter in front