OAuth Gateway
HTTP-SSEOAuth 2.1 authorization server adding authentication to MCP servers without code modification
OAuth 2.1 authorization server adding authentication to MCP servers without code modification
An OAuth 2.1 Authorization Server that adds authentication to any MCP (Model Context Protocol) server without code modification. The gateway acts as an OAuth Authorization Server while using GitHub as the Identity Provider (IdP) for user authentication.
📖 View Documentation | 🔧 Installation Guide | 🏗️ Architecture Overview
This is a reference implementation and test platform for the MCP protocol.
The MCP OAuth Gateway is a zero-modification authentication layer for MCP servers. It implements OAuth 2.1 with dynamic client registration (RFC 7591/7592) and leverages GitHub as the identity provider for user authentication. The architecture follows these core principles:
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ EXTERNAL CLIENTS │
│ (Claude.ai, MCP CLI tools, IDE extensions, Custom integrations) │
└─────────────────────────────────────────────────────────────────────────────────────┘
│
HTTPS │ :443
↓
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ TRAEFIK REVERSE PROXY │
│ (Layer 1: Routing & TLS Termination) │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ • Let's Encrypt automatic HTTPS certificates for all subdomains │
│ • Priority-based routing rules (OAuth > Verify > MCP > Catch-all) │
│ • ForwardAuth middleware for MCP endpoints → Auth Service /verify │
│ • Request routing based on subdomain and path: │
│ - auth.domain.com/* → Auth Service (no auth required) │
│ - *.domain.com/.well-known/* → Auth Service (OAuth discovery) │
│ - *.domain.com/mcp → MCP Services (auth required via ForwardAuth) │
│ • Docker service discovery via labels │
└─────────────────────────────────────────────────────────────────────────────────────┘
│ │
│ OAuth/Auth Requests │ MCP Requests
│ (unauthenticated) │ (authenticated)
↓ ↓
┌───────────────────────────────────────────┐ ┌─────────────────────────────────────┐
│ AUTH SERVICE │ │ MCP SERVICES │
│ (Layer 2: OAuth Authorization Server) │ │ (Layer 3: Protocol Handlers) │
├───────────────────────────────────────────┤ ├─────────────────────────────────────┤
│ Container: auth:8000 │ │ Containers: │
│ Package: mcp-oauth-dynamicclient │ │ • mcp-echo-stateful:3000 │
│ │ │ • mcp-echo-stateless:3000 │
│ │ │ • mcp-fetch:3000 │
│ OAuth Endpoints: │ │ • mcp-memory:3000 │
│ • POST /register (RFC 7591) │ │ • mcp-time:3000 │
│ • GET /authorize + /callback │ │ • ... (dynamically enabled) │
│ • POST /token │ │ │
│ • GET /.well-known/* (RFC 8414) │ │ Architecture: │
│ • POST /revoke, /introspect │ │ • mcp-streamablehttp-proxy wrapper │
│ │ │ • Spawns official MCP stdio servers │
│ Management Endpoints (RFC 7592): │ │ • Bridges stdio ↔ HTTP/SSE │
│ • GET/PUT/DELETE /register/{client_id} │ │ • No OAuth knowledge │
│ │ │ • Receives user identity in headers │
│ Internal Endpoints: │ │ │
│ • GET/POST /verify (ForwardAuth) │ │ Protocol Endpoints: │
│ │ │ • POST /mcp (JSON-RPC over HTTP) │
│ External Integration: │←---│ • GET /mcp (SSE for async messages) │
│ • GitHub OAuth (user authentication) │ │ • Health checks on /health │
└───────────────────────────────────────────┘ └─────────────────────────────────────┘
│ ↑
│ │
└──────────────┬───────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ REDIS STORAGE LAYER │
│ (Persistent State Management) │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ Container: redis:6379 │
│ Persistence: AOF + RDB snapshots │
│ │
│ Data Structures: │
│ • oauth:client:{client_id} → OAuth client registrations (90 days / eternal) │
│ • oauth:state:{state} → Authorization flow state (5 minutes) │
│ • oauth:code:{code} → Authorization codes + user info (1 year) │
│ • oauth:token:{jti} → JWT token tracking for revocation (30 days) │
│ • oauth:refresh:{token} → Refresh token data (1 year) │
│ • oauth:user_tokens:{username} → User's active tokens index │
│ • redis:session:{id}:state → MCP session state (managed by proxy) │
│ • redis:session:{id}:messages → MCP message queues │
└─────────────────────────────────────────────────────────────────────────────────────┘
NETWORK TOPOLOGY: • All services connected via 'public' Docker network • Internal service communication only (except Traefik ingress) • Redis exposed on localhost:6379 for debugging only • Each MCP service runs in isolated container with no shared state
The gateway implements a multi-layered OAuth 2.1 authorization system that integrates client credential authentication with GitHub OAuth identity federation:
The gateway implements a sophisticated OAuth 2.1 system with three distinct authentication flows:
Need Authentication?
├─> For Gateway's Own GitHub Access?
│ └─> Use Device Flow: `just generate-github-token`
│ - Shows code: "Visit github.com/login/device"
│ - No browser redirect needed
│ - Stores GITHUB_PAT in .env
│
├─> For MCP Client Token?
│ └─> Use Device Flow: `just mcp-client-token`
│ - Client uses device flow for browserless auth
│ - Stores MCP_CLIENT_ACCESS_TOKEN in .env
│
└─> For End User Access (Browser)?
└─> Use Standard OAuth Flow
- User visits protected resource
- Redirected to GitHub for login
- Redirected back to gateway
- JWT issued with user+client identity
The gateway implementation combines client credential authentication with GitHub user authentication:
╔═══════════════════════════════════════════════════════════════════════════════════╗
║ OAUTH CLIENT REGISTRATION (RFC 7591/7592) ║
╠═══════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ 📝 STEP 1: CLIENT REGISTRATION (No Authentication Required) ║
║ ┌─────────────────────────────────────────────────────────────────────────────┐ ║
║ │ POST /register │ ║
║ │ • Public endpoint - any MCP client can register │ ║
║ │ • Creates OAuth client application credentials │ ║
║ │ │ ║
║ │ Request Body: │ ║
║ │ { │ ║
║ │ "redirect_uris": ["https://example.com/callback"], │ ║
║ │ "client_name": "My MCP Client" │ ║
║ │ } │ ║
║ │ │ ║
║ │ Response: │ ║
║ │ • client_id: "client_abc123..." ← OAuth client credentials │ ║
║ │ • client_secret: "secret_xyz789..." ← Used at /token endpoint │ ║
║ │ • registration_access_token: "reg_tok..."← ONLY for client management │ ║
║ │ • registration_client_uri: "https://auth.../register/client_abc123" │ ║
║ └─────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
║ 🔧 OPTIONAL: CLIENT MANAGEMENT (Requires registration_access_token) ║
║ ┌─────────────────────────────────────────────────────────────────────────────┐ ║
║ │ Authorization: Bearer <registration_access_token> │ ║
║ │ │ ║
║ │ • GET /register/{client_id} - View client configuration │ ║
║ │ • PUT /register/{client_id} - Update redirect URIs, etc. │ ║
║ │ • DELETE /register/{client_id} - Delete client registration │ ║
║ │ │ ║
║ │ Note: This token is ONLY for managing the client registration, │ ║
║ │ NOT for accessing MCP resources! │ ║
║ └─────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════╝
↓
Client has credentials, now needs user authorization
↓
╔═══════════════════════════════════════════════════════════════════════════════════╗
║ USER AUTHENTICATION FLOW (GitHub OAuth) ║
╠═══════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ 👤 STEP 2: USER AUTHORIZATION (Human authenticates via GitHub) ║
║ ┌─────────────────────────────────────────────────────────────────────────────┐ ║
║ │ GET /authorize?client_id=client_abc123&redirect_uri=...&code_challenge=... │ ║
║ │ │ ║
║ │ 1. Gateway validates client_id exists │ ║
║ │ 2. Redirects user to GitHub OAuth: │ ║
║ │ → User logs into GitHub │ ║
║ │ → GitHub authenticates the human user │ ║
║ │ → Returns to gateway /callback with GitHub user info │ ║
║ │ 3. Gateway checks ALLOWED_GITHUB_USERS whitelist │ ║
║ │ 4. Creates authorization code tied to: │ ║
║ │ • The OAuth client (client_id) │ ║
║ │ • The GitHub user (username, email, etc.) │ ║
║ │ 5. Redirects back to client with code │ ║
║ └─────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
║ 🎫 STEP 3: TOKEN EXCHANGE (Client credentials + Authorization code) ║
║ ┌─────────────────────────────────────────────────────────────────────────────┐ ║
║ │ POST /token │ ║
║ │ Content-Type: application/x-www-form-urlencoded │ ║
║ │ │ ║
║ │ Request: │ ║
║ │ • client_id=client_abc123 ← Authenticates the OAuth client │ ║
║ │ • client_secret=secret_xyz789 ← Proves client identity │ ║
║ │ • code=auth_code_from_step_2 ← Contains GitHub user info │ ║
║ │ • code_verifier=pkce_verifier ← PKCE verification │ ║
║ │ │ ║
║ │ Response: │ ║
║ │ • access_token: JWT containing: │ ║
║ │ - sub: GitHub user ID │ ║
║ │ - username: GitHub username │ ║
║ │ - email: GitHub email │ ║
║ │ - client_id: client_abc123 │ ║
║ │ • refresh_token: For renewing access │ ║
║ └─────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
║ 🛡️ STEP 4: RESOURCE ACCESS (Using the access token) ║
║ ┌─────────────────────────────────────────────────────────────────────────────┐ ║
║ │ Authorization: Bearer <access_token> │ ║
║ │ │ ║
║ │ • Token contains BOTH client_id AND user identity │ ║
║ │ • Traefik ForwardAuth validates token via /verify │ ║
║ │ • User identity passed to MCP services as headers: │ ║
║ │ - X-User-Id: GitHub user ID │ ║
║ │ - X-User-Name: GitHub username │ ║
║ │ • Access granted to /mcp endpoints on all enabled services │ ║
║ └─────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════╝
🔑 ARCHITECTURAL PRINCIPLES:
client_id + client_secret establish OAuth client identity (e.g., Claude.ai application)access_token JWT encapsulates both client and user identity claimsregistration_access_token is scoped exclusively to client lifecycle management operationsMCP OAuth Gateway - OAuth 2.1 Authorization Server
registration_access_token: Only for managing client registrations (RFC 7592)access_token: JWT with user claims + client_id for accessing MCP resourcesrefresh_token: For renewing access tokensGitHub OAuth - Identity Provider (IdP)
MCP Servers - Protected Resources
These servers are configured to accept any GitHub user for authentication:
The test servers implement the full OAuth 2.1 + MCP 2025-06-18 integration:
These servers are ideal for:
auth.your-domain.com - OAuth authorization serverservice.your-domain.com - Each MCP service subdomainYou'll need to create a GitHub OAuth App that serves two distinct purposes:
End-User Authentication (Browser-based OAuth flow)
https://auth.yourdomain.com/callbackGateway Self-Authentication (Device flow)
just generate-github-tokenThis repository uses Git submodules for better modularity. All Python packages are maintained as submodules:
mcp-streamablehttp-client - OAuth-enabled stdio-to-HTTP bridge client
mcp-streamablehttp-clientmcp-streamablehttp-proxy - Stdio to StreamableHTTP proxy server
mcp-streamablehttp-proxymcp-oauth-dynamicclient - OAuth 2.0 dynamic client registration
mcp-oauth-dynamicclientmcp-fetch-streamablehttp-server - Native fetch server
mcp-fetch-streamablehttp-servermcp-echo-streamablehttp-server-stateful - Stateful echo server
mcp-echo-streamablehttp-server-statefulmcp-echo-streamablehttp-server-stateless - Stateless echo server
mcp-echo-streamablehttp-server-stateless# Clone the repository with submodules git clone --recurse-submodules https://github.com/atrawog/mcp-oauth-gateway.git cd mcp-oauth-gateway # If you already cloned without submodules, initialize them git submodule update --init --recursive # Install dependencies with pixi pixi install # Run initial setup just setup
# 1. Copy the example configuration cp .env.example .env # 2. Generate required secrets just generate-all-secrets # Generates JWT secret, RSA keys, and Redis password # 3. Edit .env with your configuration nano .env
Edit your .env file with the required configuration:
Domain Setup (REQUIRED)
BASE_DOMAIN=your-domain.com # Your actual domain ACME_EMAIL=[email protected] # Email for Let's Encrypt
GitHub OAuth App (REQUIRED)
GITHUB_CLIENT_ID=your_client_id GITHUB_CLIENT_SECRET=your_client_secret
Access Control (REQUIRED)
# Option 1: Whitelist specific users ALLOWED_GITHUB_USERS=user1,user2,user3 # Option 2: Allow any authenticated GitHub user ALLOWED_GITHUB_USERS=*
MCP OAuth Gatewayhttps://your-domain.comhttps://auth.your-domain.com/callback.env file# Start all services just up # Check service health just check-health
All configuration is managed through the .env file. The gateway uses dynamic service selection - you can enable or disable individual MCP services based on your needs.
Minimum tokens required to run the gateway:
| Token | Purpose | How to Get | Required? |
|---|---|---|---|
GITHUB_CLIENT_ID | GitHub OAuth App ID | Create at github.com/settings/developers | ✅ YES |
GITHUB_CLIENT_SECRET | GitHub OAuth App Secret | Create at github.com/settings/developers | ✅ YES |
GATEWAY_JWT_SECRET | JWT signing secret | Run: just generate-jwt-secret | ✅ YES |
JWT_PRIVATE_KEY_B64 | RSA key for JWT | Run: just generate-rsa-keys | ✅ YES |
REDIS_PASSWORD | Redis security | Run: just generate-redis-password | ✅ YES |
Tokens only needed for testing:
| Token | Purpose | How to Get | Required? |
|---|---|---|---|
GITHUB_PAT | GitHub API access in tests | Run: just generate-github-token | ❌ NO |
GATEWAY_OAUTH_* tokens | Test suite authentication | Generated during test setup | ❌ NO |
MCP_CLIENT_* tokens | Testing MCP clients | Run: just mcp-client-token | ❌ NO |
⚡ Key Point: The gateway itself doesn't use OAuth tokens - it only needs GitHub OAuth App credentials to authenticate users!
# Domain Configuration - MUST be publicly accessible domains! BASE_DOMAIN=your-domain.com ACME_EMAIL=[email protected] # GitHub OAuth App Credentials GITHUB_CLIENT_ID=your_client_id GITHUB_CLIENT_SECRET=your_client_secret # Security Keys (generated by just commands) GATEWAY_JWT_SECRET=<generated-by-just-generate-jwt-secret> # Redis Security REDIS_PASSWORD=your_secure_redis_password
# User Whitelist Options: ALLOWED_GITHUB_USERS=user1,user2,user3 # Specific users only # OR ALLOWED_GITHUB_USERS=* # Any GitHub user
# Token Lifetimes (in seconds) CLIENT_LIFETIME=7776000 # Client registration: 90 days (0 = eternal) # Note: Access and refresh token lifetimes are configured in .env
The gateway allows you to enable/disable individual MCP services. All services default to true (enabled) if not specified.
# Core MCP Services MCP_FETCH_ENABLED=true # Web content fetching (stdio proxy) MCP_FETCHS_ENABLED=true # Native Python fetch implementation MCP_FILESYSTEM_ENABLED=true # File system access (sandboxed) MCP_MEMORY_ENABLED=true # Persistent memory/knowledge graph MCP_TIME_ENABLED=true # Time and timezone operations # Advanced MCP Services MCP_SEQUENTIALTHINKING_ENABLED=true # Structured problem solving MCP_TMUX_ENABLED=true # Terminal multiplexer integration MCP_PLAYWRIGHT_ENABLED=false # Browser automation (resource intensive) MCP_EVERYTHING_ENABLED=true # Test server with all features # Echo Diagnostic Services (Choose one or both) MCP_ECHO_STATEFUL_ENABLED=true # Echo with session state & replayLastEcho MCP_ECHO_STATELESS_ENABLED=true # Echo without state management
# MCP Protocol Version (used by services that support it) MCP_PROTOCOL_VERSION=2025-06-18 # Note: Some services only support specific versions: # - mcp-memory: 2024-11-05 # - mcp-sequentialthinking: 2024-11-05 # - mcp-fetch, mcp-filesystem, mcp-time: 2025-03-26 # - Others: 2025-06-18
| Service | Description | Protocol Version | Container Port |
|---|---|---|---|
| mcp-echo-stateful | Diagnostic tools with session state & memory | 2025-06-18 | 3000 |
| mcp-echo-stateless | Diagnostic tools without state management | 2025-06-18 | 3000 |
| mcp-fetch | Web content fetching (stdio wrapper) | 2025-03-26 | 3000 |
| mcp-fetchs | Native Python fetch implementation | 2025-06-18 | 3000 |
| mcp-filesystem | File system access (sandboxed) | 2025-03-26 | 3000 |
| mcp-memory | Persistent memory/knowledge graph | 2024-11-05 | 3000 |
| mcp-sequentialthinking | Structured problem solving | 2024-11-05 | 3000 |
| mcp-time | Time and timezone operations | 2025-03-26 | 3000 |
| mcp-tmux | Terminal multiplexer integration | 2025-06-18 | 3000 |
| mcp-playwright | Browser automation | 2025-06-18 | 3000 |
| mcp-everything | Test server with all features | 2025-06-18 | 3000 |
All services use mcp-streamablehttp-proxy to wrap official MCP stdio servers, exposing them via HTTP on port 3000.
The gateway adds several features not specified in the MCP protocol:
# Enable/disable tests for specific services MCP_FETCH_TESTS_ENABLED=false MCP_FETCHS_TESTS_ENABLED=false MCP_FILESYSTEM_TESTS_ENABLED=false MCP_MEMORY_TESTS_ENABLED=false MCP_PLAYWRIGHT_TESTS_ENABLED=false MCP_SEQUENTIALTHINKING_TESTS_ENABLED=false MCP_TIME_TESTS_ENABLED=false MCP_TMUX_TESTS_ENABLED=false MCP_EVERYTHING_TESTS_ENABLED=false MCP_ECHO_STATEFUL_TESTS_ENABLED=false MCP_ECHO_STATELESS_TESTS_ENABLED=true # Test parameters TEST_HTTP_TIMEOUT=30.0 TEST_MAX_RETRIES=3 TEST_RETRY_DELAY=1.0