Overview
What is mcp-proxy?
mcp-proxy is a tool that lets you switch between MCP server transports, supporting two modes: stdio to SSE and SSE to stdio. It is intended for developers using MCP clients like Claude Desktop who need to connect to remote SSE servers or expose local stdio servers over SSE.
How to use mcp-proxy?
Install via PyPI (uv tool install mcp-proxy or pipx install mcp-proxy) or as a Docker container. To run in stdio-to-SSE mode, pass the SSE endpoint URL and optional headers. For SSE-to-stdio mode, use the --sse-port flag and the command for the local stdio server. Configuration is done in the MCP client’s settings (e.g., Claude Desktop’s mcpServers JSON).
Key features of mcp-proxy
- Converts stdio transport to SSE transport
- Converts SSE transport to stdio transport
- Supports custom HTTP headers for SSE connections
- Allows passing environment variables to spawned servers
- Supports CORS configuration for SSE server
- Available as a Python package and Docker image
Use cases of mcp-proxy
- Connect Claude Desktop to a remote MCP server over SSE
- Expose a local stdio-based MCP server to remote clients via SSE
- Test MCP servers with the inspector tool using a proxy
- Run MCP servers behind a proxy with custom ports and hosts
FAQ from mcp-proxy
What is the difference between the two modes?
- stdio to SSE: The proxy acts as a stdio client that connects to a remote SSE server, allowing clients like Claude Desktop to communicate over SSE.
- SSE to stdio: The proxy exposes an SSE server that spawns and connects to a local stdio server, enabling remote connections to local servers.
What are the runtime requirements?
mcp-proxy requires Python 3.x. It can be installed via pip or pipx, and is also available as a Docker image.
How do I pass authentication headers to the SSE server?
Use the --headers argument (e.g., --headers Authorization 'Bearer YOUR_TOKEN') or set the API_ACCESS_TOKEN environment variable.
Can I run mcp-proxy in a Docker container?
Yes, starting from version 0.3.2. Pull the image from ghcr.io/sparfenyuk/mcp-proxy and extend it as needed.
What is the default host and port for the SSE server?
The SSE server listens on 127.0.0.1 by default and uses a random available port unless --sse-host and --sse-port are specified.
