mcp-auth-proxy

Authenticating reverse proxy for MCP servers — credential isolation, OAuth2 token management, and composite tool aggregation.

What it does

mcp-auth-proxy sits between an LLM orchestrator and one or more upstream services (MCP servers, REST APIs, etc.). It provides:

• Credential injection — per-route header injection so the orchestrator process never holds service tokens.
• OAuth2 consent flow — browser-based OAuth2 authorization code flow for remote MCP providers. Tokens are stored encrypted at rest (AES-256-GCM) and refreshed automatically.
• Composite MCP server — aggregates tools from all linked OAuth2 providers into a single tools/list response, namespaced by provider (e.g. google_calendar-create_event). Includes built-in proxy-link_provider for runtime provider linking.
• Tiered approval system — configurable per-route and per-tool autonomy tiers. Tier 2 actions require single-use or standing approval tokens, preventing the double-send class of bugs.
• Rate limiting — sliding-window per-route rate limiter.
• Prometheus metrics — request counts, latency histograms, upstream errors, and approval token lifecycle metrics.
• Structured logging — JSON-formatted logs for Loki/Promtail/Alloy ingestion.

Architecture

┌─────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ Orchestrator │────▶│ mcp-auth-proxy  │────▶│ Upstream Service │
│   (LLM)     │     │                 │     │  (MCP / REST)    │
└─────────────┘     │ • auth inject   │     └──────────────────┘
                    │ • rate limit    │
                    │ • tier enforce  │     ┌──────────────────┐
                    │ • MCP aggregate │────▶│ OAuth2 Provider  │
                    │ • metrics       │     │ (Google, etc.)   │
                    └─────────────────┘     └──────────────────┘

The orchestrator authenticates to the proxy with a shared virtual key (X-Gateway-Key header). The proxy matches the request path to a configured route, injects the upstream's credentials, and forwards the request.

For MCP, the proxy presents itself as an MCP server on POST /mcp (Streamable HTTP transport) and GET /mcp/events (SSE notifications). It aggregates tools from all OAuth2-linked providers and dispatches tools/call to the correct upstream.

Quick start

# Install
pip install .

# Run with a config file
mcp-auth-proxy --config config.yaml

# Or with Docker
docker build -t mcp-auth-proxy .
docker run -v ./config.yaml:/etc/mcp-auth-proxy/config.yaml mcp-auth-proxy

Configuration

See config.example.yaml for a fully documented example configuration.

Routes

Each route maps a path prefix to an upstream URL with optional credential injection:

routes:
  - prefix: /api
    upstream: http://internal-service:8080
    inject_headers:
      Authorization: "Bearer ${SERVICE_TOKEN}"
    rate_limit: 60  # requests per minute
    tier: 1         # 1 = autonomous, 2 = requires approval token

OAuth2 providers

Remote MCP servers accessed via OAuth2:

oauth:
  encryption_key: "${OAUTH_ENCRYPTION_KEY}"  # 64 hex chars (32 bytes AES-256)
  external_url: "https://proxy.example.com"
  providers:
    google_calendar:
      display_name: "Google Calendar"
      auth_url: "https://accounts.google.com/o/oauth2/v2/auth"
      token_url: "https://oauth2.googleapis.com/token"
      client_id: "${GOOGLE_CLIENT_ID}"
      client_secret: "${GOOGLE_CLIENT_SECRET}"
      scopes: ["https://www.googleapis.com/auth/calendar"]
      mcp_server_url: "https://calendar-mcp.example.com/mcp"

Approval tokens

Tier 2 actions require an approval token obtained from POST /approve:

# Issue a single-use token
curl -X POST http://localhost:8090/approve \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{"action": "email.send", "scope": {"to": "user@example.com"}}'

# Use it in a proxied request
curl -X POST http://localhost:8090/email/send \
  -H "X-Gateway-Key: $VIRTUAL_KEY" \
  -H "X-Approval-Token: apt-abc123..." \
  -d '{"to": "user@example.com", "body": "Hello"}'

Endpoints

Endpoint	Method	Description
/health	GET	Health check with route count and MCP status
/_routes	GET	List configured routes (no credentials exposed)
/mcp	POST	MCP JSON-RPC endpoint (tools/list, tools/call)
/mcp/events	GET	SSE stream for MCP notifications
/approve	POST	Issue an approval token (admin)
/approve	GET	List active tokens (admin)
/approve/standing	POST	Issue a standing (multi-use) token
/approve/audit	GET	Audit trail of token lifecycle
/approve/{id}	DELETE	Revoke a token
/auth/{provider}/start	GET	Start OAuth2 consent flow
/auth/{provider}/callback	GET	OAuth2 callback
/auth/status	GET	Show linked providers for user
/admin/refresh-tools	POST	Force tool cache refresh
/admin/tool-cache	GET	Tool cache status
/{path}	*	Catch-all reverse proxy

Security headers

Header	Direction	Purpose
X-Gateway-Key	Client → Proxy	Orchestrator authentication
X-Admin-Key	Client → Proxy	Approval endpoint authentication
X-MCP-User	Client → Proxy	User identification for MCP
X-Approval-Token	Client → Proxy	Tier 2 action authorisation
Remote-User	Auth proxy → Proxy	Authenticated user (from SSO)

Metrics

Prometheus metrics are served on port 9091 (configurable):

• mcp_proxy_request_total — requests by route, method, status
• mcp_proxy_request_duration_seconds — latency histogram
• mcp_proxy_rate_limited_total — rate-limited requests
• mcp_proxy_upstream_error_total — upstream errors
• mcp_proxy_approval_* — approval token lifecycle

License

0BSD — do whatever you want with it.