The mcp-proxy is a tool that lets you switch between server transports. There are two supported modes:
stdio to SSE/StreamableHTTP
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.
graph LR
A["Claude Desktop"] <--> |stdio| B["mcp-proxy"]
B <--> |SSE| C["External MCP Server"]
style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px
style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px
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.
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.
graph LR
A["LLM Client"] <-->|SSE| B["mcp-proxy"]
B <-->|stdio| C["Local MCP Server"]
style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px
style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px
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
--port
No, random available
The MCP server port to listen on
8080
--host
No, 127.0.0.1 by default
The host IP address that the MCP server will listen on
0.0.0.0
--env
No
Additional environment variables to pass to the MCP stdio server. Can be used multiple times.
FOO BAR
--cwd
No
The working directory to pass to the MCP stdio server process.
/tmp
--pass-environment
No
Pass through all environment variables when spawning the server
--no-pass-environment
--allow-origin
No
Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed.
--allow-origin "*"
--expose-header
No
Headers added to Access-Control-Expose-Headers. Can be used multiple times. Defaults to mcp-session-id.
--expose-header Custom-Header
--stateless
No
Enable stateless mode for streamable http transports. Default is False
--no-stateless
--named-server NAME COMMAND_STRING
No
Defines a named stdio server.
--named-server fetch 'uvx mcp-server-fetch'
--named-server-config FILE_PATH
No
Path to a JSON file defining named stdio servers.
--named-server-config /path/to/servers.json
--sse-port (deprecated)
No, random available
The SSE server port to listen on
8080
--sse-host (deprecated)
No, 127.0.0.1 by default
The host IP address that the SSE server will listen on
0.0.0.0
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
# Start the MCP server with CORS enabled and custom exposed headers
mcp-proxy --port=8080 --allow-origin='*' --expose-header Custom-Header uvx mcp-server-fetch
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:
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 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:
[!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.
Release images are published to GHCR and Docker Hub as multi-platform manifests for linux/amd64 and linux/arm64;
Docker selects the matching image for the host architecture automatically.
docker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.12.0 --help
docker run --rm -t sparfenyuk/mcp-proxy:v0.12.0 --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 commandwhich mcp-proxy (
macOS, Linux) or where.exe mcp-proxy (Windows). Then, use the output path as a value for 'command' attribute:
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 ["catatonit", "--", "mcp-proxy"]
Docker Compose Setup
With the custom Dockerfile, you can define a service in your Docker Compose file:
[!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}] [--verify-ssl [VALUE]]
[--no-verify-ssl] [-e KEY VALUE] [--cwd CWD]
[--client-id CLIENT_ID] [--client-secret CLIENT_SECRET] [--token-url TOKEN_URL]
[--pass-environment | --no-pass-environment]
[--log-level LEVEL] [--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 ...]]
[--expose-header HEADER]
[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.
--verify-ssl [VALUE] Control SSL verification when acting as a client. Use without a value to force verification, pass 'false' to disable, or provide a path to a PEM bundle.
--no-verify-ssl Disable SSL verification (alias for --verify-ssl false).
--client-id CLIENT_ID
OAuth2 client ID for authentication
--client-secret CLIENT_SECRET
OAuth2 client secret for authentication
--token-url TOKEN_URL
OAuth2 token URL for authentication
--username USERNAME Username for authentication
--password PASSWORD Password for authentication
--digest Use digest authentication
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.
--log-level LEVEL Set the log level. Default is INFO.
--debug, --no-debug Enable debug mode with detailed logging output. Equivalent to --log-level DEBUG. If both --debug and --log-level are provided, --debug takes precedence.
--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.
--expose-header HEADER
Headers to expose via Access-Control-Expose-Headers. Defaults to 'Mcp-Session-Id'. Can be used multiple times.
Examples:
mcp-proxy http://localhost:8080/sse
mcp-proxy --no-verify-ssl https://server.local/sse
mcp-proxy --transport streamablehttp http://localhost:8080/mcp
mcp-proxy --transport streamablehttp --username user --password pass https://server.local/mcp
mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
mcp-proxy --client-id CLIENT_ID --client-secret CLIENT_SECRET --token-url https://auth.example.com/token http://localhost:8080/sse
mcp-proxy --port 8080 -- your-command --arg1 value1 --arg2 value2
mcp-proxy --named-server fetch 'uvx mcp-server-fetch' --port 8080
mcp-proxy your-command --port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE
mcp-proxy your-command --port 8080 --allow-origin='*'
mcp-proxy your-command --port 8080 --allow-origin='*' --expose-header Custom-Header
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
