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.

When the proxy is a Streamable HTTP client, it bounds the final MCP session-termination DELETE request, including reading its response body, to five seconds. After cancellation or timeout, closing a received response gets a shielded, cooperative grace of up to one second; cleanup code that ignores cancellation can take longer. Graceful CLI teardown after SIGINT requires Python 3.11+; on Python 3.10, SIGINT may interrupt the event loop before the final DELETE is sent (asyncio runner documentation). This limit applies only to that termination operation; normal GET streams and POST tool calls retain their usual HTTP timeouts. It is specific to reverse-client mode and does not change the stateful/stateless behavior of proxied HTTP servers.

In reverse Streamable HTTP mode, an HTTP 404 on a POST for an established upstream session marks that session lost. The operation that received the 404 is never retried; its failure follows the existing proxy handling, and the server may already have applied it. A later explicit request may use a replacement session only when its complete initialization handshake matches the original. The proxy does not restore subscriptions, logging levels, or other upstream session-local state; after stateful resource or logging operations, or when the handshake changes, it refuses later requests and the MCP client must restart. Progress notifications are sent only to the current healthy session and are not buffered or replayed.

Arguments

| Name | Required | Description | Example

... View full README on GitHub