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.
This is a reference implementation and test platform for the MCP protocol.
Primary Purpose: Reference implementation for MCP protocol development and testing
Experimental Nature: Used as a test platform for future MCP protocol iterations
Security Disclaimer: While this implementation strives for security best practices, this implementation likely contains bugs and security vulnerabilities
Production Warning: NOT recommended for production use without thorough security review
Use at Your Own Risk: This is experimental software intended for development and testing
🏗️ Architecture
Overview
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:
Complete Separation of Concerns: Authentication, routing, and MCP protocol handling are strictly isolated
No MCP Server Modifications: Official MCP servers run unmodified, wrapped only for HTTP transport
Standards Compliance: Full OAuth 2.1, RFC 7591/7592, and MCP protocol compliance
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
Security Architecture
Authentication Layers
TLS/HTTPS: Enforced by Traefik for all external communication
OAuth Client Authentication: client_id + client_secret at token endpoint
User Authentication: GitHub OAuth with ALLOWED_GITHUB_USERS whitelist
Token Authentication: JWT Bearer tokens for API access
PKCE Protection: Mandatory S256 code challenges
Security Boundaries
Public Access: Only /register and /.well-known/* endpoints
registration_access_token: Bearer token for client management only (RFC 7592)
access_token: JWT containing user identity + client_id for MCP access
refresh_token: Opaque token for obtaining new access tokens
authorization_code: One-time code binding user to client
Architectural Decisions
Why Three Layers?
Traefik (Routing): Centralizes TLS, routing, and auth enforcement
Auth Service (OAuth): Isolated OAuth implementation, no MCP knowledge
MCP Services (Protocol): Pure MCP protocol handlers, no auth knowledge
Why mcp-streamablehttp-proxy?
Wraps official stdio-based MCP servers without modification
Provides HTTP transport required for web clients
Manages subprocess lifecycle and session state
Enables horizontal scaling possibilities
Why Redis?
Fast, reliable state storage for OAuth flows
Supports atomic operations for security
Built-in TTL for automatic cleanup
Enables distributed deployment if needed
Why GitHub OAuth?
Trusted identity provider for developers
No password management needed
Strong security with 2FA support
Rich user profile information
OAuth Architecture: Client Credentials + User Authentication
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:
GitHub Device Flow (RFC 8628) - For command-line/browserless scenarios
GitHub OAuth Web Flow - For browser-based end-user authentication
Dynamic Client Registration (RFC 7591) - For MCP client registration
Authentication Flow Decision Tree
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 │ ║
║ └─────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════╝
Purpose: Diagnostic MCP server without state management
Main Repository Components
auth/ - OAuth authorization server implementation
traefik/ - Reverse proxy configuration and routing
mcp- service directories* - Docker configurations for MCP services
tests/ - Comprehensive test suite
docs/ - Jupyter Book documentation
scripts/ - Utility and automation scripts
🚀 Installation
1. Clone and Setup
# 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
2. Configure Environment
# 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
[email protected] # Email for Let's Encrypt
Save the Client ID and Client Secret to your .env file
4. Start the Gateway
# Start all services
just up
# Check service health
just check-health
🔧 Configuration
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.
🔑 Token Requirements Summary
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!
Configuration Categories
1. Core Settings (REQUIRED)
# Domain Configuration - MUST be publicly accessible domains!
BASE_DOMAIN=your-domain.com
[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
2. Access Control
# User Whitelist Options:
ALLOWED_GITHUB_USERS=user1,user2,user3 # Specific users only
# OR
ALLOWED_GITHUB_USERS=* # Any GitHub user
3. Token Configuration
# Token Lifetimes (in seconds)
CLIENT_LIFETIME=7776000 # Client registration: 90 days (0 = eternal)
# Note: Access and refresh token lifetimes are configured in .env
4. MCP Service Management
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
5. Protocol Configuration
# 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
Available MCP Services
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.
Gateway Extensions Beyond MCP Protocol
The gateway adds several features not specified in the MCP protocol: