MCP OAuth Proxy

A lightweight OAuth 2.1 Client Credentials Flow proxy for MCP STDIO servers. Automatically fetches Bearer tokens and proxies JSON-RPC requests to your HTTP MCP server.

Features

• ✅ Automatic OAuth Token Management - Fetches and caches tokens, auto-refreshes when expired
• ✅ STDIO to HTTP Bridge - Converts STDIO protocol to HTTP with OAuth headers
• ✅ Zero Configuration for End Users - Just set one environment variable and use mcp.json config
• ✅ Client Credentials Flow - Perfect for server-to-server authentication
• ✅ Cross-Platform - Works on macOS, Linux, Windows
• ✅ Lightweight - Minimal dependencies, fast startup

Installation

Option 1: Global Installation

npm install -g mcp-oauth-proxy

Option 2: Use with npx (no installation needed)

npx mcp-oauth-proxy

Quick Start

1. Set Your OAuth Secret

export MCP_CLIENT_SECRET="your-oauth-client-secret"

2. Configure in VS Code (mcp.json)

Add to your VS Code settings file (~/.config/Code/User/mcp.json):

{
  "servers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-oauth-proxy"],
      "type": "stdio",
      "env": {
        "MCP_CLIENT_ID": "your-oauth-client-id",
        "MCP_CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}",
        "MCP_AUTH_SERVER_URL": "https://your-auth-server.com/token",
        "MCP_SERVER_URL": "http://localhost:8000/mcp"
      }
    }
  }
}

3. Reload VS Code

Press Cmd+K Cmd+W (macOS) or Ctrl+K Ctrl+W (Windows/Linux) to reload VS Code window.

Configuration

Required Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | MCP_CLIENT_ID | OAuth 2.1 client ID | my-client-id | | MCP_CLIENT_SECRET | OAuth 2.1 client secret | Set in system environment, reference with ${env:MCP_CLIENT_SECRET} | | MCP_SERVER_URL | Your HTTP MCP server endpoint | http://localhost:8000/mcp |

Optional Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MCP_AUTH_SERVER_URL | OAuth token endpoint | Perforce auth (Keycloak) |

How It Works

VS Code (STDIO)
    ↓ (JSON-RPC message)
mcp-oauth-proxy
    ├─ Fetches OAuth token from MCP_AUTH_SERVER_URL
    └─ Adds "Authorization: Bearer <token>" header
        ↓ (HTTP POST)
Your MCP Server (HTTP)
    ↓ (Validates Bearer token)
    ← Returns JSON-RPC response
    ↓
VS Code (STDIO)

Token Management

• Caching: Tokens are cached in memory for reuse
• Auto-Refresh: Tokens are automatically refreshed 30 seconds before expiry
• Error Handling: Invalid credentials return proper JSON-RPC error responses

Use Cases

1. Perforce OAuth - Integrate with Perforce auth servers
2. Keycloak - Works with any Keycloak instance
3. Generic OAuth 2.1 - Compatible with any OAuth 2.1 server supporting client credentials flow
4. Secure MCP Servers - Add authentication layer to existing HTTP MCP servers

Architecture

• bin/cli.js - Entry point, initializes proxy with environment variables
• lib/proxy.js - Core proxy logic, handles OAuth and request forwarding

Debugging

The proxy logs to stderr:

[OAuth Proxy] Initialized with:
  Client ID: your-client-id
  Client Secret length: 32
  Auth Server: https://...
  MCP Server: http://localhost:8000/mcp
[OAuth Proxy] Starting STDIO proxy...
[OAuth] Token fetched successfully (expires in 300s)

Check the VS Code Output panel (View → Output) and select "MCP Servers" from the dropdown.

Troubleshooting

Issue: "Client Secret length: NOT SET"

Solution: Make sure to set MCP_CLIENT_SECRET in your system environment before launching VS Code:

export MCP_CLIENT_SECRET="your-secret"

Issue: "OAuth token fetch failed: 401 Unauthorized"

Solution: Check that your client ID and secret are correct for the OAuth server.

Issue: "MCP server returned: 406"

Solution: Make sure your MCP server is running and MCP_SERVER_URL is correct.

License

MIT License - see LICENSE file for details

Contributing

Contributions welcome! Feel free to open issues or PRs.

Related Projects

• Model Context Protocol - Official MCP documentation
• @modelcontextprotocol/sdk - Official MCP SDK for TypeScript