MCP-OAUTH2-PROXY

What is MCP-OAUTH2-PROXY?

MCP-OAUTH2-PROXY is a local stdio MCP server that proxies to a remote, OAuth2-protected HTTP MCP server. It runs on Node.js 20+ and is designed for use with Claude Desktop, Cursor, VS Code Copilot, or any other MCP client.

How to use MCP-OAUTH2-PROXY?

Install is not required—MCP clients can launch the proxy via npx -y mcp-oauth2-proxy. Configuration is done through environment variables or a JSON config file. For interactive login, set UPSTREAM_URL, OAUTH2_GRANT=authorization_code, and OAUTH2_CLIENT_ID. For headless use, supply OAUTH2_GRANT=client_credentials along with client secret and token URL. Wire it into an MCP client's mcpServers configuration with command: "npx" and appropriate env settings.

Key features of MCP-OAUTH2-PROXY

• Interactive authorization_code + PKCE flow with built-in browser callback listener.
• Refresh-token cache on disk (AES‑256‑GCM, 0600) for silent reuse.
• client_credentials grant for headless or service-to-service use.
• RFC 9728 + RFC 8414 discovery of token/authorization endpoints (usually zero OAuth config).
• Proactive token refresh with skew, de-duplication, and 401 retry.
• Streamable-HTTP upstream support: JSON, SSE, optional server-notification channel.
• Stderr-only logging (pino) with redaction of tokens and secrets.

Use cases of MCP-OAUTH2-PROXY

• Connect MCP clients to remote OAuth2-protected MCP servers with a one-time browser login.
• Run automated MCP tools in headless environments using client credentials.
• Integrate with any MCP client that supports stdio (Claude Desktop, Cursor, VS Code Copilot, etc.).
• Relay server-to-server MCP communication with encrypted token storage.

FAQ from MCP-OAUTH2-PROXY

How does MCP-OAUTH2-PROXY differ from a direct HTTP MCP client?

It acts as a local stdio proxy that handles OAuth2 authentication transparently, so any stdio-based MCP client can access an OAuth2-protected upstream server without implementing OAuth flows themselves.

What MCP transports does it support upstream?

It supports the Streamable HTTP MCP transport, including single-shot JSON, SSE text/event-stream responses, and the optional long-lived server-notification channel. It honors Mcp-Session-Id.

What platforms and MCP clients are supported?

It runs on Node.js 20+, on any OS where Node.js runs. It works with any MCP client that can launch a subprocess with stdio (JSON-RPC), such as Claude Desktop, Cursor, and VS Code Copilot.

Is MCP-OAUTH2-PROXY free and open source?

Yes, it is licensed under MIT and available on npm. There is no pricing or licensing fee.

What are the known limits of the refresh-token cache?

The cache is AES‑256‑GCM encrypted but stored in the user's config directory with file mode 0600. It protects against casual disk reads but not against a process running as the same OS user. OS-keychain integration is on the roadmap.