mcp-server-proxy

mcp-server-proxy

Proxy a remote HTTP/HTTPS MCP server over stdio. This lets any MCP client that speaks stdio connect to remote MCP servers running over HTTP.

Supports both Streamable HTTP and SSE transports, auto-detected from the URL.

Install

uv sync

Usage

# Streamable HTTP
uv run mcp-server-proxy http://remote-server:8000/mcp

# SSE (auto-detected when URL ends in /sse)
uv run mcp-server-proxy https://remote-server:8000/sse

# Custom display name
uv run mcp-server-proxy --name "My API" http://example.com/mcp

# With auth header (value visible in process args)
uv run mcp-server-proxy --header "Authorization: Bearer tok_123" http://example.com/mcp

# With auth from environment variable (recommended for secrets)
export MCP_TOKEN="Bearer tok_123"
uv run mcp-server-proxy --env-header "Authorization=MCP_TOKEN" http://example.com/mcp

# Multiple headers
uv run mcp-server-proxy \
  --env-header "Authorization=MCP_TOKEN" \
  --header "X-Custom: value" \
  http://example.com/mcp

Headers

| Flag | Format | Description | |------|--------|-------------| | --header | "Name: Value" | Pass a literal header value | | --env-header | "Name=ENV_VAR" | Read the header value from an environment variable |

Use --env-header for secrets like API keys and tokens — values passed via --header are visible in the process argument list.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "my-remote-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/mcp-server-proxy",
        "mcp-server-proxy",
        "--name", "My Remote Server",
        "--env-header", "Authorization=MCP_TOKEN",
        "https://remote-server.com/mcp"
      ],
      "env": {
        "MCP_TOKEN": "Bearer tok_123"
      }
    }
  }
}

Claude Code

Add to your Claude Code config (.claude/settings.json or ~/.claude/settings.json):

{
  "mcpServers": {
    "my-remote-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/mcp-server-proxy",
        "mcp-server-proxy",
        "--name", "My Remote Server",
        "--env-header", "Authorization=MCP_TOKEN",
        "https://remote-server.com/mcp"
      ],
      "env": {
        "MCP_TOKEN": "Bearer tok_123"
      }
    }
  }
}

Codex

Add to your Codex config (~/.codex/config.toml):

[mcp_servers.my-remote-server]
command = "uv"
args = [
  "run",
  "--directory", "/path/to/mcp-server-proxy",
  "mcp-server-proxy",
  "--name", "My Remote Server",
  "--env-header", "Authorization=MCP_TOKEN",
  "https://remote-server.com/mcp",
]

[mcp_servers.my-remote-server.env]
MCP_TOKEN = "Bearer tok_123"

How it works

The proxy uses FastMCP's create_proxy() to connect to the remote server as a client and re-expose all its tools, resources, and prompts over stdio. The transport is inferred from the URL:

• URLs ending in /sse use SSE transport
• All other http:// / https:// URLs use Streamable HTTP transport