README
¶
mcp-gate
OAuth 2.1 reverse proxy for MCP servers. Implements RFC 9728 Protected Resource Metadata and JWT validation, delegating authentication to an external authorization server.
Read the blog post: I couldn't find an OAuth 2.1 proxy for MCP servers, so I built one
What it does
mcp-gate sits in front of any MCP server and adds the MCP Authorization specification (2026-07-28) endpoints required by Claude.ai custom connectors:
/.well-known/oauth-protected-resource— Serves RFC 9728 metadata pointing clients to the authorization server/healthz— Health check for container orchestration/*— Validates Bearer JWT tokens via JWKS, then reverse-proxies to the upstream MCP server
Every request is logged as structured JSON (method, path, status, duration_ms, client_ip, user_agent) for Loki/Alloy ingestion.
Architecture
Claude.ai → Reverse Proxy → mcp-gate (JWT validation) → MCP Server → Backend
↕
Authorization Server (OAuth 2.1 / OIDC)
Quick Start
export LISTEN_ADDR=0.0.0.0:8080
export UPSTREAM_URL=http://mcp-server:8000
export RESOURCE_URI=https://mcp.example.com
export AUTHORIZATION_SERVER=https://auth.example.com/application/o/mcp/
export JWKS_URI=https://auth.example.com/application/o/mcp/jwks/
export EXPECTED_ISSUER=https://auth.example.com/application/o/mcp/
export EXPECTED_AUDIENCE=your-client-id
go run ./cmd/mcp-gate
Docker
docker pull cpremus/mcp-gate:latest
Images are published to Docker Hub and GHCR on each release. Available tags: latest, version (e.g. v1.2.0).
Setup
See the Setup Guide for step-by-step instructions on:
- Creating an OAuth client in your OIDC provider (Keycloak, Authentik, Okta, Auth0, etc.)
- Configuring mcp-gate
- Connecting Claude.ai to the protected MCP server
Configuration
All configuration is via environment variables. See the Setup Guide for the full list.
Horizontal scaling
mcp-gate validates JWTs statelessly and is safe to run as multiple replicas behind a load balancer. The per-IP rate limiter defaults to in-memory state, which means the configured RPS holds per replica. Set REDIS_ADDR=host:port to back the limiter with Redis so the configured RPS is enforced globally across replicas. REDIS_USERNAME, REDIS_PASSWORD, and REDIS_DB are read separately so Vault can inject a password as a single secret. Redis errors fail open (the request passes through and a counter is incremented) so a Redis hiccup never blackholes user traffic.
License
MIT
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
mcp-gate
command
Package main is the entrypoint for mcp-gate.
|
Package main is the entrypoint for mcp-gate. |
|
internal
|
|
|
auth
Package auth provides JWT validation middleware using JWKS.
|
Package auth provides JWT validation middleware using JWKS. |
|
metadata
Package metadata serves RFC 9728 Protected Resource Metadata.
|
Package metadata serves RFC 9728 Protected Resource Metadata. |
|
metrics
Package metrics provides Prometheus metric definitions and a metrics server.
|
Package metrics provides Prometheus metric definitions and a metrics server. |
|
origin
Package origin implements opt-in Origin header validation.
|
Package origin implements opt-in Origin header validation. |
|
otel
Package otel provides OpenTelemetry tracing setup with OTLP HTTP export.
|
Package otel provides OpenTelemetry tracing setup with OTLP HTTP export. |
|
proxy
Package proxy provides the reverse proxy to upstream MCP servers.
|
Package proxy provides the reverse proxy to upstream MCP servers. |
|
ratelimit
Package ratelimit provides per-IP rate limiting and concurrent request limiting.
|
Package ratelimit provides per-IP rate limiting and concurrent request limiting. |
|
realip
Package realip extracts the real client IP from HTTP requests.
|
Package realip extracts the real client IP from HTTP requests. |