Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/abj453demo/mcp-oauth-gateway.git
cd mcp-oauth-gateway
uv venv
source .venv/bin/activate
uv pip install -e .Register it in Claude Code
claude mcp add mcp-oauth-gateway -- mcp-oauth-gateway --port 8002 --upstream-rs https://api.githubcopilot.com/mcp/ --upstream-client-id YOUR_ID --upstream-client-secret YOUR_SECRETReplace any placeholder paths in the command with the real path on your machine.
Make your agent remember this setup
mcp-oauth-gateway's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Transparent proxying between MCP clients and upstream MCP servers
- Chains local OAuth layer with upstream OAuth credentials
- Supports OAuth 2.0 Dynamic Client Registration (RFC 7591)
- Manages dual token sets behind a single client-facing interface
- Implements a two-screen authorization flow for secure access
Environment Variables
MCP_GATEWAY_USERNAMEUsername for the gateway login screenMCP_GATEWAY_PASSWORDPassword for the gateway login screenTry it
Original README from abj453demo/mcp-oauth-gateway
MCP OAuth Gateway
Quick Start
Prerequisites
- Python 3.10+
- uv (recommended) or pip
Create a GitHub OAuth App
- Go to GitHub Developer Settings → OAuth Apps → New OAuth App
- Set Authorization callback URL to
http://localhost:8002/upstream/callback - Fill in any Application name and Homepage URL
- Click Register application
- 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).
- Client discovers the gateway via
GET /.well-known/oauth-protected-resource, which returns the gateway as both the resource and its own authorization server. - Client fetches
GET /.well-known/oauth-authorization-serverto learn the gateway's OAuth endpoints (/authorize,/token,/register). - Client calls
POST /registerwith its redirect URIs and grant types. The gateway stores the client in memory and returns aclient_idandclient_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
- Client →
GET /authorize— Gateway stores the client's redirect URI, PKCEcode_challenge, and state. Redirects to its own/loginpage. - **Screen 1: Gat