mcp-proxy
MCP proxy that connects stdio/HTTP clients to remote MCP servers with OAuth support
Installation
npx mcp-proxyAsk AI about mcp-proxy
Powered by Claude Β· Grounded in docs
I know everything about mcp-proxy. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
| Flag | Description | Default |
|---|---|---|
--listen, -l | Listen address for HTTP mode (e.g., :8080) | - |
--header, -H | Custom headers (KEY:VALUE) | - |
--transport | Upstream transport strategy (http-first, sse-first, http-only, sse-only) | http-first |
--host | OAuth callback hostname | localhost |
--allow-http | Allow non-HTTPS connections | false |
--log-level | Log level (debug, info, warn, error) | info |
--enable-proxy | Use HTTP_PROXY/HTTPS_PROXY | false |
--ignore-tool | Ignore tools matching pattern (wildcards) | - |
--auth-timeout | OAuth callback timeout (seconds) | 30 |
--resource | OAuth resource parameter | - |
--static-oauth-client-metadata | Static OAuth client metadata (JSON or @file) | - |
--static-oauth-client-info | Static OAuth client info (JSON or @file) | - |
Transport Strategy
Controls how mcp-proxy connects to the upstream server:
http-first(default): Try HTTP, fall back to SSE on 404sse-first: Try SSE, fall back to HTTP on 405http-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
auth.Provider.Initialize()loads existing tokens or prepares for auth- On 401: start callback server, open browser to authorization URL
- Callback receives code, exchanges for tokens via PKCE
- 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
