mcp-proxy

You can install mcp-proxy using uv, pipx, or by pulling a container image.

Using uv (Recommended)

uv tool install mcp-proxy

Using pipx

pipx install mcp-proxy

Using Docker

Pull and run the multi-platform image (supports linux/amd64 and linux/arm64):

docker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.12.0 --help

The default mcp-proxy container image does not include uv. To use uv inside the container, create a custom Dockerfile:

FROM ghcr.io/sparfenyuk/mcp-proxy:latest

# Install the 'uv' package
RUN python3 -m ensurepip && pip install --no-cache-dir uv

ENV PATH="/usr/local/bin:$PATH" \
    UV_PYTHON_PREFERENCE=only-system

ENTRYPOINT ["catatonit", "--", "mcp-proxy"]

This mode allows clients that only support stdio (like Claude Desktop) to communicate with a remote MCP server over SSE or Streamable HTTP. The proxy acts as a bridge: the client talks to the proxy via stdio, and the proxy talks to the remote server via SSE.

{
  "mcpServers": {
    "mcp-proxy": {
      "command": "mcp-proxy",
      "args": [
        "http://example.io/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "access-token"
      }
    }
  }
}

This mode exposes a local stdio MCP server as an SSE server. The proxy opens a network port to listen for SSE requests and spawns a local process to handle the MCP requests via stdio. This allows remote clients to connect to a local MCP server.

# Start the MCP server behind the proxy on a default port
mcp-proxy uvx mcp-server-fetch

# Start the MCP server behind the proxy with a custom port
mcp-proxy --port=8080 uvx mcp-server-fetch

# Start the MCP server with a custom host and port
mcp-proxy --host=0.0.0.0 --port=8080 uvx mcp-server-fetch

If Claude Desktop fails to start the server with an ENOENT error, it is likely because the binary path is not being resolved correctly.

Solution: Use the absolute path to the binary in your configuration.

1. Find the path using which mcp-proxy (macOS/Linux) or where.exe mcp-proxy (Windows).
2. Use that full path in the command field of your configuration.

Example:

"fetch": {
  "command": "/full/path/to/bin/mcp-proxy",
  "args": [
    "http://localhost:8932/sse"
  ]
}

To run a custom mcp-proxy image (e.g., one containing uv) via Docker Compose, use the following configuration.

Important: You must include the --pass-environment argument to ensure the proxy can find interpreters/installations.

services:
  mcp-proxy-custom:
    build:
      context: .
      dockerfile: mcp-proxy.Dockerfile
    network_mode: host
    restart: unless-stopped
    ports:
      - 8096:8096
    command: "--pass-environment --port=8096 --sse-host 0.0.0.0 uvx mcp-server-fetch"

Use the MCPServerSettings dataclass to define how the proxy server binds to the network and handles security/logging.

Available fields:

• bind_host: The host address to bind to.
• port: The port number to listen on.
• stateless: Boolean indicating if the server should operate in stateless mode (default: False).
• allow_origins: A list of allowed CORS origins. If provided, CORSMiddleware is enabled.
• expose_headers: A list of HTTP headers to expose to the client (defaults to ("mcp-session-id",)).
• log_level: The logging level. Supported values: "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL" (default: "INFO").

When running in stdio to SSE mode, provide the remote MCP server's SSE endpoint as the first argument.

Arguments:

• command_or_url (Required): The MCP server SSE endpoint (e.g., http://example.io/sse).
• --transport: Specifies the protocol. Options: sse or streamablehttp. Use streamablehttp if the server requires it.
• --headers: Headers for the SSE connection (e.g., Authorization 'Bearer my-token').
• --client-id, --client-secret, --token-url: OAuth2 authentication parameters.

Environment Variables:

• API_ACCESS_TOKEN: Can be used instead of the --headers Authorization 'Bearer <TOKEN>' argument.