Labsco
ChengleiYuan logo

mcp-oauth2-proxy

★ 1

from ChengleiYuan

A local stdio MCP server that proxies to a remote, OAuth2-protected HTTP MCP server.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#browser#git#security

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.

PageWhat's there
Getting StartedInstall, first run, wiring into a client.
ConfigurationEvery field and environment variable.
OAuth2 Grants and TokensGrants, interactive login, token + cache lifecycle.
DiscoveryRFC 9728 / RFC 8414 endpoint discovery.
SecurityThreat model and built-in defenses.
Remote Hosts (SSH Port Forwarding)Logging in when the proxy runs remotely.
TroubleshootingCommon problems and a FAQ.
Architecture · Bridge · OAuth2 internalsHow it works inside.
Contributing and ReleasesDev setup, tests, release process.

Contents

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

  1. Discovery. Optionally fetch RFC 9728/8414 metadata to fill in tokenUrl, authorizationUrl, and scope.
  2. Token manager. Wrap the configured Grant with caching, refresh-skew, in-flight dedup, and 401 invalidation.
  3. Prefetch. Call getToken() once at startup so the interactive browser flow (if needed) happens before the first MCP message arrives.
  4. 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.
  5. 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.

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.

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)