mcp-proxy

mcp-proxy is a versatile bridge that enables MCP clients and servers to communicate over different transports. It supports two modes: stdio to SSE/StreamableHTTP and SSE to stdio. In stdio-to-SSE mode, the proxy connects to a remote MCP server over an SSE endpoint and exposes a streamable HTTP interface to clients like Claude Desktop. In SSE-to-stdio mode, the proxy exposes an SSE endpoint and spawns a local stdio-based MCP server, allowing remote clients to talk to a local MCP implementation. The configuration requires specifying the MCP server endpoint as the first argument and can include optional headers, transport type, and OAuth2 credentials. The example configuration demonstrates starting the proxy with a remote SSE URL and an API access token for authentication.

To use the two modes effectively, you typically choose based on your deployment needs: use stdio-to-SSE to connect to a remote MCP endpoint from clients that only support SSE, or use SSE-to-stdio to expose a local MCP server to remote clients via SSE. The configuration supports OAuth2 tokens and headers for secured endpoints, making it suitable for authenticated MCP services.

Prerequisites:

• Python 3.8+ and pip installed on your system
• Access to install Python packages from PyPI (or build from source as needed)

Option 1: Install via PyPI (recommended)

1. Upgrade pip pip install --upgrade pip
2. Install mcp-proxy from PyPI pip install mcp-proxy
3. Verify installation mcp-proxy --help

Option 2: Install from GitHub (latest code)

1. Ensure git is installed
2. Clone the repository git clone https://github.com/sparfenyuk/mcp-proxy.git
3. Change into the project directory cd mcp-proxy
4. Install local dependencies pip install -e .
5. Run the proxy mcp-proxy --help

Option 3: Run via container (Docker)

1. Pull the latest image (if provided by the project) docker pull sparfenyuk/mcp-proxy
2. Run with your configuration (example) docker run -it --rm -e API_ACCESS_TOKEN=your-token sparfenyuk/mcp-proxy http://example.io/sse

Note: The project README mentions installation via PyPI, GitHub (latest), and container deployment. Adjust commands if your environment uses a different entrypoint or if the binary is named differently in your setup.

Tips and common issues:

• Ensure the API_ACCESS_TOKEN (or headers) matches the authentication requirements of the remote SSE endpoint.
• When using stdio-to-SSE, verify that the --transport is set appropriately if the remote server requires streamable HTTP.
• For SSE-to-stdio, you can pass additional environment variables to the local stdio server via the --env option in the configuration.
• If you encounter connection errors, check CORS settings and ensure the SSE endpoint is reachable from your deployment environment.
• The example configuration uses a placeholder URL (http://example.io/sse) and a placeholder token; replace these with your actual endpoint and credentials.