📌Overview

Purpose: The mcp-proxy framework facilitates communication between different server transports, specifically enabling the connection between stdio and SSE (Server-Sent Events).

Overview: mcp-proxy serves as a versatile tool designed to enable seamless integration between clients and servers that may not natively support the required communication protocols. It operates in two primary modes: connecting stdio clients to an external SSE server, and exposing a local stdio server through an SSE interface.

Key Features:

stdio to SSE Mode: This feature allows clients, such as Claude Desktop, to connect to remote SSE servers, bridging compatibility gaps for applications that do not support SSE natively.
SSE to stdio Mode: This feature facilitates external clients connecting to a local stdio server over SSE, allowing remote interactions with local processing instances effectively.

mcp-proxy

About

The mcp-proxy is a tool that lets you switch between server transports. There are two supported modes:

stdio to SSE
SSE to stdio

1. stdio to SSE

Run a proxy server from stdio that connects to a remote SSE server. This mode allows clients like Claude Desktop to communicate to a remote server over SSE even though it is not supported natively.

1.1 Configuration

This mode requires passing the URL to the MCP Server SSE endpoint as the first argument to the program.

Arguments

Name	Required	Description	Example
`command_or_url`	Yes	The MCP server SSE endpoint to connect to	http://example.io/sse
`--headers`	No	Headers to use for the MCP server SSE connection	Authorization 'Bearer my-secret-access-token'

Environment Variables

Name	Required	Description	Example
`API_ACCESS_TOKEN`	No	Can be used instead of `--headers Authorization 'Bearer <API_ACCESS_TOKEN>'`	YOUR_TOKEN

1.2 Example usage

mcp-proxy is supposed to be started by the MCP Client, so the configuration must be done accordingly.

For Claude Desktop, the configuration entry can look like this:

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

2. SSE to stdio

Run a proxy server exposing an SSE server that connects to a local stdio server. This allows remote connections to the local stdio server. The mcp-proxy opens a port to listen for SSE requests, spawns a local stdio server that handles MCP requests.

2.1 Configuration

This mode requires the --sse-port argument to be set. The --sse-host argument can be set to specify the host IP address that the SSE server will listen on. Additional environment variables can be passed to the local stdio server using the --env argument. The command line arguments for the local stdio server must be passed after the -- separator.

Arguments

Name	Required	Description	Example
`command_or_url`	Yes	The command to spawn the MCP stdio server	uvx mcp-server-fetch
`--sse-port`	No, random available	The SSE server port to listen on	8080
`--sse-host`	No, `127.0.0.1` by default	The host IP address that the SSE server will listen on	0.0.0.0
`--env`	No	Additional environment variables to pass to the MCP stdio server	FOO=BAR
`--pass-environment`	No	Pass through all environment variables when spawning the server	--no-pass-environment
`--allow-origin`	No	Allowed CORS origins for the SSE server	--allow-cors "*"

2.2 Example usage

To start the mcp-proxy server that listens on port 8080 and connects to the local MCP server:

# Start the MCP server behind the proxy
mcp-proxy uvx mcp-server-fetch

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

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

# Start the MCP server behind the proxy with a custom user agent
# Note that the `--` separator is used to separate the `mcp-proxy` arguments from the `mcp-server-fetch` arguments
mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent

This will start an MCP server that can be connected to at http://127.0.0.1:8080/sse

Installation

Installing via Smithery

To install MCP Proxy for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-proxy --client claude

Installing via PyPI

The stable version of the package is available on the PyPI repository. Install it using:

# Option 1: With uv (recommended)
uv tool install mcp-proxy

# Option 2: With pipx (alternative)
pipx install mcp-proxy

Once installed, you can run the server using the mcp-proxy command.

Installing via Github repository (latest)

Install the latest version from the git repository:

uv tool install git+https://github.com/sparfenyuk/mcp-proxy

To update, use:

uv tool upgrade --reinstall

To uninstall:

uv tool uninstall mcp-proxy

Installing as container

Starting from version 0.3.2, pull and run the container image:

docker run -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --help

Troubleshooting

Problem: Claude Desktop can't start the server: ENOENT code in the logs
Solution: Use the full path to the binary. Find it with where mcp-proxy (macOS, Linux) or where.exe mcp-proxy (Windows) and use the output as the value for the command attribute:

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

Extending the container image

You can extend the mcp-proxy container image to include additional executables. For example, to add uv:

# file: mcp-proxy.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 [ "mcp-proxy" ]

Docker Compose Setup

With the custom Dockerfile, define a service in your Docker Compose file:

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

Note: Set --pass-environment to avoid "No interpreter found" errors.

Command line arguments

usage: mcp-proxy [-h] [-H KEY VALUE] [-e KEY VALUE] [--pass-environment | --no-pass-environment] [--sse-port SSE_PORT] [--sse-host SSE_HOST]
                 [--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]]
                 [command_or_url] [args ...]

Start the MCP proxy in one of two possible modes: as an SSE or stdio client.

positional arguments:
  command_or_url        Command or URL to connect to. When a URL, will run an SSE client, otherwise will run the given command and connect as a stdio client. See corresponding options for more details.

options:
  -h, --help            show this help message and exit

SSE client options:
  -H KEY VALUE, --headers KEY VALUE
                        Headers to pass to the SSE server. Can be used multiple times.

stdio client options:
  args                  Any extra arguments to the command to spawn the server
  -e KEY VALUE, --env KEY VALUE
                        Environment variables used when spawning the server. Can be used multiple times.
  --pass-environment, --no-pass-environment
                        Pass through all environment variables when spawning the server.
  --debug, --no-debug   Enable debug mode with detailed logging output.

SSE server options:
  --sse-port SSE_PORT   Port to expose an SSE server on. Default is a random port
  --sse-host SSE_HOST   Host to expose an SSE server on. Default is 127.0.0.1
  --allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]
                        Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed.

Examples:
  mcp-proxy http://localhost:8080/sse
  mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
  mcp-proxy --sse-port 8080 -- your-command --arg1 value1 --arg2 value2
  mcp-proxy your-command --sse-port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE
  mcp-proxy your-command --sse-port 8080 --allow-origin='*'

Testing

Check the mcp-proxy server by running it with the mcp-server-fetch server. You can use the inspector tool to test the target server.

# Run the stdio server called mcp-server-fetch behind the proxy over SSE
mcp-proxy --sse-port=8080 uvx mcp-server-fetch &

# Connect to the SSE proxy server spawned above using another instance of mcp-proxy given the URL of the SSE server
mcp-proxy http://127.0.0.1:8080/sse

# Send CTRL+C to stop the second server

# Bring the first server to the foreground
fg

# Send CTRL+C to stop the first server