Getting Started

Getting Started

This page takes you from nothing to a working proxy wired into your MCP client.

Requirements

• Node.js 20+ (node --version).
• An OAuth2-protected MCP server speaking the Streamable HTTP MCP transport.
• An OAuth2 client registered with your identity provider (IdP). For the interactive flow, register http://127.0.0.1:53682/callback as a redirect URI (or whatever you set OAUTH2_CALLBACK_PORT to).

Install

You don't need to install anything — MCP clients can launch the proxy directly via npx:

npx -y mcp-oauth2-proxy

For development against a local checkout:

git clone https://github.com/ChengleiYuan/mcp-oauth2-proxy.git
cd mcp-oauth2-proxy
npm install
npm run build

Quick start

Interactive login (recommended for end users)

UPSTREAM_URL=https://mcp.example.com/mcp \
OAUTH2_GRANT=authorization_code \
OAUTH2_CLIENT_ID=<your-client-id> \
  npx -y mcp-oauth2-proxy

On first launch the proxy:

1. Discovers token_endpoint and authorization_endpoint from the upstream (RFC 9728 + RFC 8414 — see Discovery).
2. Opens your default browser at the IdP authorization endpoint with a PKCE S256 challenge.
3. Captures the authorization code on http://127.0.0.1:53682/callback.
4. Persists the refresh token under the OS user config dir, encrypted at rest.
5. Starts the MCP stdio bridge.

Subsequent launches reuse the cached refresh token silently — no browser, no prompts. For the mechanics, see OAuth2 Grants and Tokens.

Headless / service account

For service-to-service use where no human is present, use the client_credentials grant:

UPSTREAM_URL=https://mcp.example.com/mcp \
OAUTH2_GRANT=client_credentials \
OAUTH2_TOKEN_URL=https://idp.example.com/oauth2/token \
OAUTH2_CLIENT_ID=my-service \
OAUTH2_CLIENT_SECRET='…' \
OAUTH2_SCOPE='mcp:read mcp:write' \
  npx -y mcp-oauth2-proxy

Wire it into an MCP client

Most MCP clients accept a JSON server definition. Point command at npx and pass configuration through env:

{
  "mcpServers": {
    "remote-oauth2-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-oauth2-proxy"],
      "env": {
        "UPSTREAM_URL": "https://mcp.example.com/mcp",
        "OAUTH2_GRANT": "authorization_code",
        "OAUTH2_CLIENT_ID": "<your-client-id>"
      }
    }
  }
}

On Windows hosts that don't resolve .cmd shims (so command: "npx" fails to start), use the explicit form:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "mcp-oauth2-proxy"]
}

Paths in the env block must be absolute and use forward slashes on every platform.

Next steps

• Tune behavior in Configuration.
• Understand token caching and refresh in OAuth2 Grants and Tokens.
• Running on a remote machine? See Remote Hosts (SSH Port Forwarding).
• Hitting a snag? See Troubleshooting.