mcp-proxy

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

About

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

1. stdio to SSE
2. 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.

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 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 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 |
| --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 | Pass through all environment variables when spawning the 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:

```bash