mcp-oauth2-proxy Server

Локальный MCP-сервер stdio, который проксирует запросы к удалённому HTTP MCP-серверу, защищённому OAuth2.

Документация

mcp-oauth2-proxy

A local stdio MCP server that proxies to a remote, OAuth2-protected HTTP MCP server. Drop it into Claude Desktop, Cursor, VS Code Copilot, or any other MCP client — log in once in your browser — done.

MCP client ─stdio (JSON-RPC)─▶ mcp-oauth2-proxy ─HTTP+SSE + Bearer─▶ upstream MCP server
                                      │
                                      └─ OAuth2 token endpoint (IdP)

Documentation

This README is a quick start. Full documentation lives in the wiki.

Page	What's there
Getting Started	Install, first run, wiring into a client.
Configuration	Every field and environment variable.
OAuth2 Grants and Tokens	Grants, interactive login, token + cache lifecycle.
Discovery	RFC 9728 / RFC 8414 endpoint discovery.
Security	Threat model and built-in defenses.
Remote Hosts (SSH Port Forwarding)	Logging in when the proxy runs remotely.
Troubleshooting	Common problems and a FAQ.
Architecture · Bridge · OAuth2 internals	How it works inside.
Contributing and Releases	Dev setup, tests, release process.

Features
How it works
Requirements
Install
Quick start
Wire it into an MCP client
Configuration
Security
Development
Out of scope
License

Features

Interactive authorization_code + PKCE flow with a built-in local browser callback listener — no manual code copy/paste.
Refresh-token cache on disk (AES‑256‑GCM, 0600), so the browser only opens once per machine.
client_credentials grant for headless / service-to-service use.
RFC 9728 + RFC 8414 discovery of token and authorization endpoints from the upstream — usually zero OAuth config required.
Proactive token refresh with skew, in-flight de-duplication, and a 401 → invalidate → retry loop.
Streamable-HTTP upstream support: single-shot JSON, SSE text/event-stream responses, and the optional long-lived server-notification channel. Honors Mcp-Session-Id.
Stderr-only logging (pino) with redaction of tokens, secrets, and Authorization headers — stdout stays a clean JSON-RPC channel.

How it works

Discovery. Optionally fetch RFC 9728/8414 metadata to fill in tokenUrl, authorizationUrl, and scope.
Token manager. Wrap the configured Grant with caching, refresh-skew, in-flight dedup, and 401 invalidation.
Prefetch. Call getToken() once at startup so the interactive browser flow (if needed) happens before the first MCP message arrives.
Bridge. For each stdin JSON-RPC line, POST to upstream.url with a Bearer token; single-shot JSON responses become one stdout line, SSE responses one line per event. A 401 triggers invalidate() and a single retry.
Server stream. After initialize, optionally hold open a GET text/event-stream channel for server-initiated notifications.

For the full internals, see the Architecture, Bridge Internals, and OAuth2 Internals wiki pages.

Requirements

Node.js 20+
An OAuth2-protected MCP server speaking the Streamable HTTP MCP transport.
An OAuth2 client registered with your 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 discovers the OAuth endpoints, opens your browser for a PKCE login, captures the code on http://127.0.0.1:53682/callback, caches the refresh token (encrypted) under your OS config dir, and starts the bridge. Subsequent launches reuse the cached token silently. Details: OAuth2 Grants and Tokens.

Headless / service account

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

{
  "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.

Configuration

The proxy can be configured by a JSON file (MCP_PROXY_CONFIG), by environment variables, or a mix — env vars override file values, then the merged result is validated. Minimal example file:

{
  "upstream": { "url": "https://mcp.example.com/mcp" },
  "oauth2": {
    "grant": "authorization_code",
    "clientId": "my-client",
    "scope": "mcp:read mcp:write"
  }
}

See config.example.json for a fuller sample.

Most-used environment variables:

Env var	Maps to
`UPSTREAM_URL`	`upstream.url`
`OAUTH2_GRANT`	`oauth2.grant`
`OAUTH2_CLIENT_ID`	`oauth2.clientId`
`OAUTH2_CLIENT_SECRET`	`oauth2.clientSecret`
`OAUTH2_TOKEN_URL`	`oauth2.tokenUrl`
`OAUTH2_SCOPE`	`oauth2.scope`
`LOG_LEVEL`	`log.level`

Full reference: every field, default, and environment variable is documented in the Configuration wiki page. Endpoint auto-discovery is covered in Discovery. Running the proxy on a remote machine? See Remote Hosts (SSH Port Forwarding). Hitting a snag? See Troubleshooting.

Security

Tokens are acquired by the proxy itself; the upstream Authorization header is always set by the proxy, never passed through from the client.
Access tokens live in memory only. Refresh tokens are cached encrypted (AES‑256‑GCM, key file mode 0600) — honest obfuscation against casual disk reads, not protection against a process running as the same OS user.
Cleartext http:// to non-loopback hosts is rejected at startup (override with ALLOW_INSECURE_HTTP=true); https:// and loopback http:// are always allowed. The interactive callback listener validates the Host header to defeat DNS-rebinding.
All logs go to stderr with tokens, secrets, and Authorization headers redacted; stdout is reserved for JSON-RPC.

Full threat model and defenses: Security.

Development

npm install
npm run build       # compile TS to dist/
npm run dev         # tsx watch
npm test            # vitest (unit + integration)

The integration test spins up a mock OAuth2 token endpoint and a mock MCP upstream in-process and drives the real bridge through PassThrough streams — no network required. Project layout, the full test strategy, and the automated release process are documented in Contributing and Releases.

Out of scope

Multiple upstream MCP servers per process
OS-keychain-backed refresh-token storage (DPAPI / Keychain / libsecret)
mTLS / JWT-bearer / device-code / ROPC grants
HTTP / SSE inbound transport (this is a stdio MCP server)

License

MIT