mcp-auth

MCP-Auth acts as a centralized OAuth 2.1 authorization server for MCP servers. It implements PKCE (S256), RFC 8707 resource indicators, token introspection, revocation, and discovery metadata so MCP servers can delegate authentication to a trusted OAuth provider without building their own authorization infrastructure. Clients (such as Claude Code or install-mcp) discover endpoints via the well-known metadata and perform the standard OAuth 2.1 flow to obtain access tokens that are scoped to specific MCP servers and audiences. The server coordinates with a shared Auth-Agent ecosystem and stores session and token data in a PostgreSQL database (via Supabase integration) and optional caching in Redis for performance.

Prerequisites:

• Docker installed and running
• Access to a PostgreSQL database (or a Supabase instance) for shared storage
• Optional Redis for caching

1. Provision the environment

• Ensure your database URL and Redis URL are available to the container via environment variables.
• Prepare a base URL for the OAuth server (AUTH_BASE_URL) and an issuer URL (ISSUER_URL).

2. Pull and run the Docker image

# Run the MCP-Auth server container
docker run -d --name mcp-auth \
  -e DATABASE_URL="postgres://user:pass@host:5432/dbname" \
  -e REDIS_URL="redis://host:6379" \
  -e AUTH_BASE_URL="https://auth.yourdomain.com" \
  -e ISSUER_URL="https://auth.yourdomain.com" \
  -e PKCE_METHOD="S256" \
  -e LOG_LEVEL="info" \
  -p 8080:8080 \
  auth-agent-mcp-auth:latest

3. Configure MCP servers to use this provider

• Point your MCP server(s) to the discovery endpoints at https://auth.yourdomain.com/.well-known/oauth-authorization-server and https://auth.yourdomain.com/.well-known/oauth-protected-resource.
• Use the token introspection, revocation, and userinfo endpoints as documented by the server.

4. Verify installation

• Check container logs: docker logs -f mcp-auth
• Ensure the endpoints respond and that access tokens minted by this server are accepted by your MCP services.

Notes and tips:

• PKCE is required; ensure your clients perform the PKCE challenge/verification using S256.
• Token audience (RFC 8707) ensures tokens are bound to a specific MCP server; do not reuse tokens across different servers.
• If you use Supabase/PostgreSQL, keep database credentials in a secure secret manager and rotate keys periodically.
• Enable introspection and revocation endpoints to allow MCP servers to validate and revoke tokens as needed.
• If you encounter connection issues to Redis or Postgres, verify network access, TLS settings, and correct environment variable values.
• Monitor logs for authentication failures to identify misconfigured client IDs, redirect URIs, or scopes.