Proxy OAuth authentication for MCP clients

mcp-proxy

A Go implementation of a proxy that connects MCP clients to remote MCP servers with OAuth support.

Features

• Dual mode operation: Stdio (default) or HTTP/SSE server
• OAuth 2.0: Full support with PKCE, dynamic client registration, and token refresh
• Transport flexibility: HTTP and SSE with configurable fallback strategies
• Tool filtering: Block specific tools from being exposed to clients

Installation

Homebrew (macOS/Linux)

brew install mikluko/tap/mcp-proxy

Go

go install github.com/mikluko/mcp-proxy/cmd/mcp-proxy@latest

Binary releases

Download from GitHub Releases.

Usage

Stdio Mode (Default)

Standard mode for MCP clients that communicate via stdio (Claude Code, Claude Desktop, Cursor, Windsurf).

Claude Code

claude mcp add remote-example mcp-proxy https://remote.mcp.server/sse

Claude Desktop, Cursor, Windsurf

{
  "mcpServers": {
    "remote-example": {
      "command": "mcp-proxy",
      "args": [
        "https://remote.mcp.server/sse"
      ]
    }
  }
}

HTTP/SSE Server Mode

Run as an HTTP server that accepts MCP client connections via SSE. Useful for:

• Web-based MCP clients
• Sharing a single upstream connection among multiple clients
• Environments where stdio isn't available

# Listen on port 8080
mcp-proxy https://remote.mcp.server/sse --listen :8080

# Listen on specific interface
mcp-proxy https://remote.mcp.server/sse --listen localhost:8080

Clients connect via:

• SSE endpoint: GET /sse - Establishes SSE stream for server→client messages
• Message endpoint: POST /message - Sends client→server messages

Custom Headers

{
  "mcpServers": {
    "remote-example": {
      "command": "mcp-proxy",
      "args": [
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization:Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "your-token"
      }
    }
  }
}

Flags

Transport Strategy

Controls how mcp-proxy connects to the upstream server:

• http-first (default): Try HTTP, fall back to SSE on 404
• sse-first: Try SSE, fall back to HTTP on 405
• http-only/sse-only: No fallback

Multiple Instances

Use --resource to isolate OAuth sessions:

{
  "mcpServers": {
    "tenant1": {
      "command": "mcp-proxy",
      "args": [
        "https://mcp.example.com/sse",
        "--resource",
        "https://tenant1.example.com/"
      ]
    },
    "tenant2": {
      "command": "mcp-proxy",
      "args": [
        "https://mcp.example.com/sse",
        "--resource",
        "https://tenant2.example.com/"
      ]
    }
  }
}

Cache Location

OAuth tokens and client registration are stored in:

• Linux: ~/.cache/mcp-proxy/
• macOS: ~/Library/Caches/mcp-proxy/
• Windows: %LocalAppData%\mcp-proxy\

To clear authentication state:

rm -rf ~/.cache/mcp-proxy # Linux
rm -rf ~/Library/Caches/mcp-proxy # macOS

Architecture

                     ┌─────────────────────────────────────────┐
                     │              mcp-proxy                  │
                     │                                         │
  ┌──────────┐       │  ┌────────────┐      ┌────────────────┐ │       ┌──────────┐
  │  Client  │──────▶│  │ Downstream │──────│     Proxy      │─│──────▶│ Upstream │
  │ (stdio   │       │  │ Transport  │      │   (filtering,  │ │       │  Server  │
  │  or SSE) │◀──────│  │            │◀─────│  modification) │◀│───────│          │
  └──────────┘       │  └────────────┘      └────────────────┘ │       └──────────┘
                     │     stdio or              HTTP or       │
                     │     HTTP/SSE                SSE         │
                     └─────────────────────────────────────────┘

Directory Structure

cmd/
└── mcp-proxy/          # Main CLI binary

internal/
├── auth/               # OAuth 2.0 implementation (PKCE, tokens, callback server)
├── config/             # Cross-platform cache directory management
├── proxy/              # Bidirectional JSON-RPC proxy with tool filtering
├── server/             # HTTP/SSE server for downstream client connections
├── stdio/              # Stdio transport for downstream client connections
└── transport/          # HTTP and SSE transports for upstream connections

pkg/
└── jsonrpc/            # JSON-RPC 2.0 message types

OAuth Flow

1. auth.Provider.Initialize() loads existing tokens or prepares for auth
2. On 401: start callback server, open browser to authorization URL
3. Callback receives code, exchanges for tokens via PKCE
4. Tokens persisted to cache dir, auto-refreshed on expiry

Release

Releases via goreleaser + GitHub Actions. Creates:

• Multi-platform binaries (linux/darwin/windows × amd64/arm64)
• Homebrew formula in mikluko/homebrew-tap

Prior Art

• geelen/mcp-remote - Original TypeScript implementation
• sparfenyuk/mcp-proxy - Python implementation
• Model Context Protocol - MCP specification