Home

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)

Many MCP servers are exposed over the network and protected by OAuth2, but most MCP clients only know how to launch a local stdio child process and have no built-in OAuth. mcp-oauth2-proxy sits in the middle: it speaks stdio JSON-RPC to the client, acquires and refreshes OAuth2 tokens on its own, and forwards every message to the remote server over authenticated HTTP + SSE.

Why use it

• No OAuth in your MCP client required. The proxy owns the whole token lifecycle.
• Browser login once per machine. Refresh tokens are cached, encrypted, on disk — subsequent launches are silent.
• Two grant types. Interactive authorization_code + PKCE for humans, client_credentials for headless/service use.
• Zero-config when possible. RFC 9728 / RFC 8414 discovery fills in the token and authorization endpoints straight from the upstream.
• Secure by default. Cleartext HTTP to non-loopback hosts is rejected, tokens never touch stdout, and logs redact every secret.

Choose your path

I want to…	Start here
Get it running in 2 minutes	Getting Started
See every config field and env var	Configuration
Understand the OAuth2 flows and token caching	OAuth2 Grants and Tokens
Let the proxy auto-find OAuth endpoints	Discovery
Review the security posture	Security
Run it on a remote VM / container	Remote Hosts (SSH Port Forwarding)
Fix a problem	Troubleshooting
Understand how it works inside	Architecture
Contribute or cut a release	Contributing and Releases

At a glance

• Runtime: Node.js 20+, distributed on npm, launchable via npx -y mcp-oauth2-proxy.
• Transport in: MCP stdio (newline-delimited JSON-RPC on stdin/stdout).
• Transport out: MCP Streamable HTTP (POST + optional long-lived GET text/event-stream) with a Bearer token.
• Dependencies: undici (HTTP), pino (stderr logging), zod (config validation).

This wiki expands on the project README with deeper, source-grounded detail. For a quick reference, the README in the repository root is a good companion.