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

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.

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' | | --transport | No | Decides which transport protocol to use when connecting to an MCP server. Can be either 'sse' or 'streamablehttp' | streamablehttp | | --client-id | No | OAuth2 client ID for authentication | your_client_id | | --client-secret| No | OAuth2 client secret for authentication | your_client_secret | | --token-url | No | OAuth2 token endpoint URL for authentication | https://auth.example.com/oauth/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 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:

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