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: Gateway login — User enters gateway credentials. On success, the gateway generates a PKCE pair for the upstream and redirects the user to the upstream AS's /authorize.
3. Screen 2: Upstream login — User authenticates with the upstream. The upstream AS redirects back to the gateway's /upstream/callback with an auth code.
4. Gateway callback — The gateway exchanges the upstream auth code for upstream access + refresh tokens (using PKCE). It generates a gateway auth code, stashes the upstream tokens, and redirects back to the client's original redirect_uri with the gateway auth code.
5. Client → POST /token — Client exchanges the gateway auth code (with its own PKCE verifier). The gateway creates its own access + refresh tokens, pairs them with the upstream tokens, and returns concatenated tokens to the client.

Token Format

Tokens returned to the client are base64-encoded pairs:

access_token  = base64url( gateway_access_token + ":" + upstream_access_token )
refresh_token = base64url( gateway_refresh_token + ":" + upstream_refresh_token )

The client treats these as opaque strings. The gateway splits them on every request to validate the gateway half and forward the upstream half.

expires_in is set to min(gateway_ttl, upstream_ttl) so the client refreshes before either token expires.

MCP Proxying

On every POST /mcp request:

1. Extract the Bearer token from the Authorization header.
2. Look up the token record — validate the gateway access token (expiry, revocation).
3. Extract the upstream access token from the pair.
4. Forward the request to the upstream RS with Authorization: Bearer <upstream_token>, passing through Content-Type, Accept, Mcp-Session-Id, and Mcp-Protocol-Version headers.
5. Stream the upstream response (including SSE) back to the client.

GET (SSE streams) and DELETE (session teardown) are proxied similarly.

Token Refresh

The client only interacts with the gateway for refresh — it never contacts the upstream directly.

1. Client sends POST /token with grant_type=refresh_token and the concatenated refresh token.
2. Gateway splits the refresh token, validates the gateway half.
3. If a real upstream refresh token exists, the gateway calls the upstream AS's /token with grant_type=refresh_token. If the upstream doesn't use refresh tokens (e.g., GitHub), the existing upstream access token is reused.
4. Gateway revokes old tokens, creates new gateway + upstream pairs, and returns new concatenated tokens.

In-Memory State

All state is held in memory (no database). Key stores:

Store	Contents	Lifetime
clients	Registered OAuth clients	Until restart
auth_codes	Gateway auth codes	Consumed on /token exchange
tokens / refresh_tokens	Gateway-issued tokens	Until expiry or revocation
state_mapping	In-flight authorize flow state	Consumed on callback
upstream_tokens	Raw upstream token responses	Consumed on /token exchange
GatewayTokenStore	Concatenated token → token pair records	Until expiry or revocation

Configuration

Flag / Env Var	Purpose
--upstream-rs	Upstream MCP Resource Server URL (required)
--upstream-as	Upstream AS URL (auto-discovered from RS if omitted)
--upstream-client-id / MCP_GATEWAY_UPSTREAM_CLIENT_ID	Pre-configured upstream client ID (skips dynamic registration)
--upstream-client-secret / MCP_GATEWAY_UPSTREAM_CLIENT_SECRET	Pre-configured upstream client secret
--upstream-authorize-endpoint / MCP_GATEWAY_UPSTREAM_AUTHORIZE_ENDPOINT	Direct upstream authorize URL (skips .well-known discovery)
--upstream-token-endpoint / MCP_GATEWAY_UPSTREAM_TOKEN_ENDPOINT	Direct upstream token URL (skips .well-known discovery)
MCP_GATEWAY_USERNAME / MCP_GATEWAY_PASSWORD	Gateway login credentials (default: gateway_user / gateway_pass)