MCP OAuth Gateway MCP Server

MCP OAuth Gateway

Quick Start

Prerequisites

• Python 3.10+
• uv (recommended) or pip

Create a GitHub OAuth App

1. Go to GitHub Developer Settings → OAuth Apps → New OAuth App
2. Set Authorization callback URL to http://localhost:8002/upstream/callback
3. Fill in any Application name and Homepage URL
4. Click Register application
5. Copy the Client ID and generate a Client Secret

Install & Run

# Clone and install
git clone https://github.com/abj453demo/mcp-oauth-gateway.git
cd mcp-oauth-gateway
uv venv && source .venv/bin/activate
uv pip install -e .

# Start the gateway (proxies to GitHub's remote MCP server)
mcp-oauth-gateway --port=8002 \
  --upstream-rs=https://api.githubcopilot.com/mcp/ \
  --upstream-client-id=<YOUR_GITHUB_CLIENT_ID> \
  --upstream-client-secret=<YOUR_GITHUB_CLIENT_SECRET> \
  --upstream-authorize-endpoint=https://github.com/login/oauth/authorize \
  --upstream-token-endpoint=https://github.com/login/oauth/access_token

Replace <YOUR_GITHUB_CLIENT_ID> and <YOUR_GITHUB_CLIENT_SECRET> with the values from your GitHub OAuth App.

The gateway will be available at http://localhost:8002. Point your MCP client at http://localhost:8002/mcp.

Gateway Credentials

When prompted at the gateway login screen (Screen 1):

• Username: gateway_user
• Password: gateway_pass

Configurable via MCP_GATEWAY_USERNAME and MCP_GATEWAY_PASSWORD environment variables.

After gateway login, you'll be redirected to GitHub for OAuth authorization (Screen 2).

Overview

The MCP OAuth Gateway is a transparent proxy that sits between an MCP client and an upstream MCP server. It implements its own OAuth 2.1 layer and chains it with the upstream's OAuth, so the client sees a single auth surface while two independent token sets are managed behind the scenes.

The gateway acts as both an Authorization Server (AS) and a Resource Server (RS) to the client. To the upstream, it acts as a regular OAuth client.

┌──────────┐       ┌─────────────────────┐       ┌─────────────────────────────┐
│  Client   │──────▶│  Gateway (AS + RS)   │──────▶│  GitHub OAuth + MCP Server   │
│ (Cascade) │◀──────│  localhost:8002      │◀──────│  api.githubcopilot.com/mcp/  │
└──────────┘       └─────────────────────┘       └─────────────────────────────┘

Client Registration

The gateway supports OAuth 2.0 Dynamic Client Registration (RFC 7591).

1. Client discovers the gateway via GET /.well-known/oauth-protected-resource, which returns the gateway as both the resource and its own authorization server.
2. Client fetches GET /.well-known/oauth-authorization-server to learn the gateway's OAuth endpoints (/authorize, /token, /register).
3. Client calls POST /register with its redirect URIs and grant types. The gateway stores the client in memory and returns a client_id and client_secret.

The gateway uses pre-configured credentials (--upstream-client-id / --upstream-client-secret) to authenticate with the upstream AS (e.g., a GitHub OAuth App). For upstreams that support it, dynamic registration is also available.

Two-Screen Auth Flow

The authorization flow chains two OAuth flows into one client-facing redirect sequence.

Client                     Gateway                    Upstream AS
  │                           │                           │
  ├─ GET /authorize ─────────▶│                           │
  │                           ├─ redirect to /login       │
  │◀──────────────────────────┤  (Screen 1: gateway creds)│
  │                           │                           │
  ├─ POST /login/callback ───▶│                           │
  │   (gateway_user/pass)     ├─ redirect to upstream ───▶│
  │                           │  /authorize (Screen 2)    │
  │◀──────────────────────────┤◀──────────────────────────┤
  │                           │                           │
  │  (user logs in upstream)  │                           │
  │───────────────────────────┼──▶ upstream callback ────▶│
  │                           │◀── upstream code ─────────┤
  │                           │                           │
  │                           ├─ exchange upstream code    │
  │                           │  for upstream tokens ─────▶
  │                           │◀── upstream access_token ─┤
  │                           │    + refresh_token        │
  │                           │                           │
  │◀─ redirect with gw code ──┤                           │
  │                           │                           │
  ├─ POST /token (gw code) ──▶│                           │
  │◀── concatenated tokens ───┤                           │

Step-by-step

1. Client → GET /authorize — Gateway stores the client's redirect URI, PKCE code_challenge, and state. Redirects to its own /login page.
2. **Screen 1: Gat