MCPBouncer

Drop OAuth 2.1 onto any MCP server with a Traefik label.

What it does

MCPBouncer adds full OAuth 2.1 and OIDC support (DCR, PKCE, JWKS, key rotation) to MCP servers that lack native authentication—without modifying the server image.

Transparent to the MCP image. Configuration via Traefik labels only. The server behind the proxy sees authenticated requests with X-Mcp-Sub and X-Mcp-Scopes headers.
Multi-tenant per image. A single sidecar instance serves multiple MCP servers with different OAuth providers (e.g., /wiki → Google, /world → Zitadel).
Tiny footprint. Sidecar is ~10 MB, stdlib-only Yaegi plugin with no external dependencies beyond the Go standard library.
Standards-conformant. Implements MCP Authorization spec (rev. 2025-06-18), RFC 8414 (Authorization Server metadata), RFC 7591 (Dynamic Client Registration), RFC 8707 (Resource Indicators).

How it works

┌─ External Client ─┐
│   (MCP client)    │
└────────┬──────────┘
         │ HTTP request
         ↓
    ┌─────────────────────────────────┐
    │  Traefik (port 443/80)          │
    │  ┌─────────────────────────────┐│
    │  │ MCPBouncer Plugin (Yaegi)    ││
    │  │ Intercepts OAuth paths      ││
    │  │ Validates JWT in-process    ││
    │  └────────┬──────────┬──────────┘│
    └───────────┼──────────┼───────────┘
                │          │
        OAuth paths   Regular MCP paths
                │          │
                ↓          ↓
        ┌──────────────────────────┐
        │   Sidecar (internal)     │
        │ Port: 8080 (Docker net)  │
        │ Handles all OAuth flows  │
        │ Manages local JWT issuer │
        │ Stores refresh tokens    │
        └────────┬─────────────────┘
                 │
                 ↓ OIDC discovery
            ┌─────────────────┐
            │  Upstream IdP   │
            │ (Google/Zitadel)│
            └─────────────────┘

Plugin (in Traefik):

Intercepts requests under each MCP's PathPrefix.
Routes OAuth endpoints (.well-known/*, /oauth/*) to the sidecar.
Validates JWT locally with cached JWKS from the sidecar.
Forwards authenticated requests to the MCP server with X-Mcp-Sub and X-Mcp-Scopes.
Returns 401 with WWW-Authenticate header on missing/invalid token.

Sidecar (internal Docker network):

Never exposed externally. Binds only to internal Docker network.
Handles OAuth 2.1 flows: discovery, DCR, authorization, token exchange.
Acts as a local Authorization Server, issuing JWT signed with its own Ed25519 keypair.
Federates to upstream IdP (Google, Zitadel, etc.) for actual user authentication.
Encrypts upstream refresh tokens at rest using AES-GCM.
Rotates signing keys automatically with configurable overlap.

Quick start

Clone and prepare:

git clone https://github.com/Sipioteo/MCPBouncer
cd MCPBouncer/deploy
cp docker-compose.example.yml docker-compose.yml
# Edit docker-compose.yml and traefik.example.yml with your IdP credentials
# (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, etc.)

Launch the stack:

docker compose up --build

Test discovery:

curl -i https://mcp.localhost/wiki/anything

Expected response:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.localhost/wiki/.well-known/oauth-protected-resource"
Content-Type: application/json

{"error":"unauthorized"}

The client can now fetch .well-known/oauth-protected-resource to discover the OAuth server and begin DCR.

For local development with source plugin, use traefik.local.yml and bind-mount the plugin directory.

Labels reference

Attach these labels to your MCP container in docker-compose.yml:

| Label | Type | Required | Description | |-------|------|----------|-------------| | traefik.enable | bool | Yes | Must be true | | traefik.http.routers.<name>.rule | string | Yes | Path rule, e.g. Host(...) && PathPrefix(/wiki) | | traefik.http.routers.<name>.middlewares | string | Yes | Reference to middleware, e.g. mcpb-wiki@docker | | traefik.http.middlewares.<name>.plugin.mcpbouncer.providerIssuer | string | Yes | OIDC issuer URL (e.g., https://accounts.google.com) | | traefik.http.middlewares.<name>.plugin.mcpbouncer.clientID | string | Yes | OAuth client ID from upstream IdP | | traefik.http.middlewares.<name>.plugin.mcpbouncer.clientSecret | string | Yes | OAuth client secret from upstream IdP | | traefik.http.middlewares.<name>.plugin.mcpbouncer.resource | string | Yes | Resource name (e.g., wiki). Used as JWT aud claim. | | traefik.http.middlewares.<name>.plugin.mcpbouncer.scopes | string | No | Space-separated OAuth scopes (default: openid) | | traefik.http.middlewares.<name>.plugin.mcpbouncer.sidecarURL | string | Yes | Internal sidecar URL (e.g., http://bouncer:8080) | | traefik.http.middlewares.<name>.plugin.mcpbouncer.audience | string | No | JWT aud claim (default: same as resource) | | traefik.http.middlewares.<name>.plugin.mcpbouncer.jwksCacheTTLSeconds | int | No | JWKS cache TTL in seconds (default: 300) | | traefik.http.middlewares.<name>.plugin.mcpbouncer.requiredScopes | string | No | Space-separated scopes required for access (checked before forwarding to MCP) |

See docs/labels.md for extended examples and notes.

Sidecar environment variables

| Variable | Default | Description | |----------|---------|-------------| | BOUNCER_DB_PATH | /data/bouncer.db | SQLite database path (must be writable) | | BOUNCER_LISTEN_ADDR | :8080 | Bind address (typically :8080 for internal Docker network) | | BOUNCER_ENCRYPTION_KEY | (required) | 32-byte base64-encoded key for AES-GCM encryption of sensitive fields | | BOUNCER_KEY_ROTATION_DAYS | 30 | Days between signing key rotations | | BOUNCER_KEY_OVERLAP_HOURS | 24 | Hours that old and new keys coexist during rotation | | BOUNCER_ACCESS_TOKEN_TTL | 1 (hour) | Access token TTL in hours | | BOUNCER_REFRESH_TOKEN_TTL | 30 (days) | Refresh token TTL in days | | BOUNCER_LOG_LEVEL | info | Log level (debug or info) |

Generate a random 32-byte base64 key:

openssl rand -base64 32

Security notes

PKCE is mandatory. All OAuth flows require PKCE with S256 challenge method. code_challenge cannot be omitted.

Refresh tokens are encrypted at rest with the key specified in BOUNCER_ENCRYPTION_KEY using AES-GCM. The upstream refresh token is never exposed to clients.

Sidecar is never exposed externally. It binds only to an internal Docker network (bouncer_internal in examples). There is no Traefik routing to the sidecar. Verify in your deployment that the sidecar port (:8080) is not accessible from outside the Docker network.

JWT algorithm validation. Only Ed25519 (EdDSA) and RS256 are accepted. alg=none is rejected outright.

Audience claim is enforced. Every JWT includes an aud claim matching the resource name. A token issued for /wiki will not validate for /world.

Issuer is exact-match. The iss claim in every JWT must exactly match the public base URL (derived from request Host and PathPrefix). No wildcard or domain-level acceptance.

Status

Early stage. Targets the MCP Authorization spec rev. 2025-06-18.

License

MIT

MCP Servers