Mcp Proxy

What is Mcp Proxy about?

Mcp Proxy enables two-way transport switching for MCP services: it can read from a local stdio process and expose an SSE/Streamable‑HTTP endpoint, or it can connect to a remote SSE/Streamable‑HTTP server and present a stdio interface to a local client.

How to use Mcp Proxy?

1. Install – via PyPI (uv tool install mcp-proxy or pipx install mcp-proxy), Smithery, a GitHub checkout, or the provided container image.
2. Run in stdio‑to‑SSE mode – supply the remote SSE URL as the first argument, optionally specifying --transport=streamablehttp and any required headers.

   mcp-proxy http://example.com/sse --headers Authorization "Bearer $API_ACCESS_TOKEN"
   

3. Run in SSE‑to‑stdio mode – start the proxy with --port (and optional --host) and provide the command that launches the local stdio server after a -- separator.

   mcp-proxy --port 8080 -- uvx mcp-server-fetch --user-agent MyAgent
   

4. Define named servers – use --named-server NAME 'COMMAND STRING' or a JSON file via --named-server-config to expose multiple back‑ends under /servers/<NAME>/.

Key features of Mcp Proxy

• Dual modes: stdio → SSE/Streamable‑HTTP and SSE → stdio.
• Transparent header injection and environment‑variable support.
• Named server routing for multi‑service setups.
• CORS control with --allow-origin.
• Stateless option for Streamable‑HTTP transports.
• Containerised distribution with easy extension via a custom Dockerfile.

Use cases of Mcp Proxy

• Claude Desktop integration – allow Claude Desktop (which only speaks stdio) to talk to remote MCP servers that only provide SSE.
• Expose local development servers – run a local stdio‑based MCP tool and make it reachable over the network via SSE.
• Multi‑backend API gateway – host several MCP services (e.g., GitHub, custom fetcher) behind a single proxy, each reachable via distinct URL paths.
• Testing & debugging – spin up a temporary proxy in CI pipelines to validate SSE‑based clients against a stdio mock server.

FAQ

Q: Do I need to set API_ACCESS_TOKEN when using headers? A: No. If you set the API_ACCESS_TOKEN environment variable, the proxy will automatically add an Authorization: Bearer <TOKEN> header.

Q: How do I run the proxy inside Docker? A: Pull the image (ghcr.io/sparfenyuk/mcp-proxy:<tag>) and run it with the same CLI arguments, e.g., docker run -p 8080:8080 ghcr.io/sparfenyuk/mcp-proxy --port 8080 -- uvx mcp-server-fetch.

Q: What is the difference between --port and the deprecated --sse-port? A: They are equivalent; --port is the preferred modern flag.

Q: Can I pass all host environment variables to the spawned stdio server? A: Yes, use --pass-environment (default is off) to inherit the entire environment.

Q: How do I configure CORS for the SSE endpoint? A: Provide one or more origins with --allow-origin, e.g., --allow-origin "*".

mcp-proxy

• mcp-proxy
  • About
  • 1. stdio to SSE/StreamableHTTP
    • 1.1 Configuration
    • 1.2 Example usage
  • 2. SSE to stdio
    • 2.1 Configuration
    • 2.2 Example usage
  • Named Servers
  • Installation
    • Installing via Smithery
    • Installing via PyPI
    • Installing via Github repository (latest)
    • Installing as container
    • Troubleshooting
  • Extending the container image
  • Docker Compose Setup
  • Command line arguments
    • Example config file
  • Testing

About

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

1. stdio to SSE/StreamableHTTP
2. SSE to stdio

1. stdio to SSE/StreamableHTTP

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 providing the URL of the MCP Server's SSE endpoint as the program’s first argument. If the server uses Streamable HTTP transport, make sure to enforce it on the mcp-proxy side by passing --transport=streamablehttp.

Arguments

Environment Variables

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 a 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

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
# (deprecated) mcp-proxy --sse-port=8080 uvx mcp-server-fetch
mcp-proxy --port=8080 uvx mcp-server-fetch

# Start the MCP server behind the proxy with a custom host and port
# (deprecated) mcp-proxy --sse-host=0.0.0.0 --sse-port=8080 uvx mcp-server-fetch
mcp-proxy --host=0.0.0.0 --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
# (deprecated) mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent
mcp-proxy --port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent

# Start multiple named MCP servers behind the proxy
mcp-proxy --port=8080 --named-server fetch 'uvx mcp-server-fetch' --named-server fetch2 'uvx mcp-server-fetch'

# Start multiple named MCP servers using a configuration file
mcp-proxy --port=8080 --named-server-config ./servers.json

Named Servers

• NAME is used in the URL path /servers/NAME/.
• COMMAND_STRING is the command to start the server (e.g., 'uvx mcp-server-fetch').
  • Can be used multiple times.
  • This argument is ignored if --named-server-config is used.
• FILE_PATH - If provided, this is the exclusive source for named servers, and --named-server CLI arguments are ignored.

If a default server is specified (the command_or_url argument without --named-server or --named-server-config), it will be accessible at the root paths (e.g., http://127.0.0.1:8080/sse).

Named servers (whether defined by --named-server or --named-server-config) will be accessible under /servers/<server-name>/ (e.g., http://127.0.0.1:8080/servers/fetch1/sse). The /status endpoint provides global status.

JSON Configuration File Format for --named-server-config:

The JSON file should follow this structure:

{
  "mcpServers": {
    "fetch": {
      "disabled": false,
      "timeout": 60,
      "command": "uvx",
      "args": [
        "mcp-server-fetch"
      ],
      "transportType": "stdio"
    },
    "github": {
      "timeout": 60,
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      },
      "transportType": "stdio"
    }
  }
}

• mcpServers: A dictionary where each key is the server name (used in the URL path, e.g., /servers/fetch/) and the value is an object defining the server.
• command: (Required) The command to execute for the stdio server.
• args: (Optional) A list of arguments for the command. Defaults to an empty list.
• enabled: (Optional) If false, this server definition will be skipped. Defaults to true.
• timeout and transportType: These fields are present in standard MCP client configurations but are currently ignored by mcp-proxy when loading named servers. The transport type is implicitly "stdio".

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. You can install it using the following command:

# 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. See configuration options for each mode above.

Installing via Github repository (latest)

The latest version of the package can be installed from the git repository using the following command:

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

[!NOTE] If you have already installed the server, you can update it using uv tool upgrade --reinstall command.

[!NOTE] If you want to delete the server, use the uv tool uninstall mcp-proxy command.

Installing as container

Starting from version 0.3.2, it's possible to pull and run the corresponding 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: Try to use the full path to the binary. To do so, open a terminal and run the commandwhere mcp-proxy ( macOS, Linux) or where.exe mcp-proxy (Windows). Then, use the output path as a value for '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 instance, uv is not included by default, but you can create a custom image with it:

# 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, you can 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 --port=8096 --sse-host 0.0.0.0 uvx mcp-server-fetch"

[!NOTE] Don't forget to set --pass-environment argument, otherwise you'll end up with the error "No interpreter found in managed installations or search path"

Command line arguments

usage: mcp-proxy [-h] [--version] [-H KEY VALUE] [--transport {sse,streamablehttp}]
                 [-e KEY VALUE] [--cwd CWD]
                 [--pass-environment | --no-pass-environment] [--debug | --no-debug]
                 [--named-server NAME COMMAND_STRING]
                 [--named-server-config FILE_PATH] [--port PORT] [--host HOST]
                 [--stateless | --no-stateless] [--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 a client or a server.

positional arguments:
  command_or_url        Command or URL to connect to. When a URL, will run an SSE/StreamableHTTP client. Otherwise, if --named-server is not used, this will be the command for the default stdio client. If --named-server is used, this argument is ignored for stdio mode unless no default server is desired. See corresponding options for more details.

options:
  -h, --help            show this help message and exit
  --version             Show the version and exit

SSE/StreamableHTTP client options:
  -H, --headers KEY VALUE
                        Headers to pass to the SSE server. Can be used multiple times.
  --transport {sse,streamablehttp}
                        The transport to use for the client. Default is SSE.

stdio client options:
  args                  Any extra arguments to the command to spawn the default server. Ignored if only named servers are defined.
  -e, --env KEY VALUE   Environment variables used when spawning the default server. Can be used multiple times. For named servers, environment is inherited or passed via --pass-environment.
  --cwd CWD             The working directory to use when spawning the default server process. Named servers inherit the proxy's CWD.
  --pass-environment, --no-pass-environment
                        Pass through all environment variables when spawning all server processes.
  --debug, --no-debug   Enable debug mode with detailed logging output.
  --named-server NAME COMMAND_STRING
                        Define a named stdio server. NAME is for the URL path /servers/NAME/. COMMAND_STRING is a single string with the command and its arguments (e.g., 'uvx mcp-server-fetch --timeout 10'). These servers inherit the proxy's CWD and environment from --pass-environment.
  --named-server-config FILE_PATH
                        Path to a JSON configuration file for named stdio servers. If provided, this will be the exclusive source for named server definitions, and any --named-server CLI arguments will be ignored.

SSE server options:
  --port PORT           Port to expose an SSE server on. Default is a random port
  --host HOST           Host to expose an SSE server on. Default is 127.0.0.1
  --stateless, --no-stateless
                        Enable stateless mode for streamable http transports. Default is False
  --sse-port SSE_PORT   (deprecated) Same as --port
  --sse-host SSE_HOST   (deprecated) Same as --host
  --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 --transport streamablehttp http://localhost:8080/mcp
  mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
  mcp-proxy --port 8080 -- my-default-command --arg1 value1
  mcp-proxy --port 8080 --named-server fetch1 'uvx mcp-server-fetch' --named-server tool2 'my-custom-tool --verbose'
  mcp-proxy --port 8080 --named-server-config /path/to/servers.json
  mcp-proxy --port 8080 --named-server-config /path/to/servers.json -- my-default-command --arg1
  mcp-proxy --port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE -- my-default-command
  mcp-proxy --port 8080 --allow-origin='*' -- my-default-command

Example config file

{
  "mcpServers": {
    "fetch": {
      "enabled": true,
      "timeout": 60,
      "command": "uvx",
      "args": [
        "mcp-server-fetch"
      ],
      "transportType": "stdio"
    },
    "github": {
      "timeout": 60,
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      },
      "transportType": "stdio"
    }
  }
}

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 --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