MCP OAuth Gateway

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

⚠️ Important Notice

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
• Production-Ready Security: HTTPS everywhere, PKCE mandatory, JWT tokens, secure session management
• Dynamic Service Discovery: Services can be enabled/disabled via configuration

System Components

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                                   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)
                    ↓                                              ↓
┌───────────────────────────────────────────┐   

... [View full README on GitHub](https://github.com/atrawog/mcp-oauth-gateway#readme)