mcp-auth-proxy

Stdio-to-HTTP MCP proxy with OAuth 2.1 authentication (PKCE + browser login).

Bridges the gap when your LLM harness only supports stdio MCP servers but the remote MCP server requires OAuth (e.g., Microsoft Entra ID).

LLM Harness (stdio only)
  ↕ stdin/stdout (JSON-RPC)
mcp-auth-proxy
  ↕ Streamable HTTP + Bearer token
Remote MCP Server (OAuth-protected)

Features

• RFC 9728 discovery — auto-discovers authorization server and scopes from the MCP server's protected resource metadata

• OAuth 2.1 + PKCE — browser-based login, no client secrets needed (public client)

• Random callback port — each instance uses a random port, safe to run multiple instances simultaneously

• Auto token refresh — handled transparently by the SDK transport

• In-memory only — tokens are never written to disk

• Full proxy — tools, resources, and prompts are all proxied

Related MCP server: outsystems-mcp-relay

Installation

⚠️ This package is not published on npm. Install from source using npm link.

git clone https://github.com/manio143/mcp-stdio-proxy.git
cd mcp-stdio-proxy
npm install
npm run build
npm link

Usage

# Basic — discovers client ID from server metadata
mcp-auth-proxy https://mcp.company.com/api

# With explicit client ID
mcp-auth-proxy https://mcp.company.com/api --clientId=my-app-client-id

In MCP client config (e.g., Claude Desktop, VS Code)

{
  "mcpServers": {
    "my-server": {
      "command": "mcp-auth-proxy",
      "args": ["https://mcp.company.com/api", "--clientId=my-app-id"]
    }
  }
}

How authentication works

1. Proxy probes the remote MCP endpoint → gets 401

2. Parses WWW-Authenticate header for resource metadata URL (RFC 9728)

3. Fetches protected resource metadata → finds authorization server + scopes

4. Fetches authorization server metadata (RFC 8414 / OIDC Discovery)

5. Opens browser for OAuth 2.1 authorization code flow with PKCE

6. Receives callback on http://localhost:{random-port}/callback

7. Exchanges code for tokens

8. All subsequent requests include Authorization: Bearer <token>

9. Token refresh happens automatically when tokens expire

Client ID resolution

1. If --clientId is provided, uses that

2. If the server's protected resource metadata advertises a client ID, uses that

3. If the server supports dynamic client registration (RFC 7591), registers automatically

4. Otherwise, exits with an error

Requirements

• Node.js ≥ 20

• A browser for the OAuth login flow

• The remote MCP server must support Streamable HTTP transport

Security

• Tokens held in memory only — process exit clears them

• PKCE prevents authorization code interception

• Callback server binds to 127.0.0.1 only

• Random port prevents port conflicts and prediction

License

MIT