mcp-remote-py

You can use this minimal MCP proxy to bridge between a local MCP client over STDIO and a remote MCP server delivering JSON-RPC via SSE. It keeps MCP protocol handling separate from log output and lets you add simple HTTP headers if needed. This makes it easy to test and forward MCP actions between a local toolchain and a remote MCP service.

How to use

Run the proxy by pointing it at the remote MCP SSE endpoint. The local side communicates MCP over STDIO, while the remote side receives JSON-RPC via SSE. The proxy forwards messages in both directions and can send custom headers if your server requires authentication.

Basic usage to connect to a remote SSE endpoint: start the proxy with the remote URL you were given, and it will bridge to your local MCP client.

If your remote service requires an Authorization header, you can pass it as a one-line header option.

How to install

Prerequisites: you need Python installed (Python 3.8+ is typical). Ensure you have the ability to create virtual environments if you choose the development path.

Option A — Global install with uv (recommended) — installs a user-scoped executable.

chmod +x ./*.sh
./install-global-uv.sh

# Windows (CMD)
install-global-uv.cmd

# Uninstall
./uninstall-global-uv.sh

# Windows (CMD)
uninstall-global-uv.cmd

# If your shell can’t find the command, ensure ~/.local/bin is on your PATH.

Option B — Dev install (editable) — useful if you want to run from a local checkout.

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

# To deactivate later
deactivate

Additional configuration and examples

Configure your MCP clients to point to the proxy URL you supply, typically using an http URL. If you need to pass custom headers, include them in the run command as shown in the examples.

Examples of client configurations are provided for common MCP clients to help you integrate smoothly.

MCP client configs (copy/paste)

Codex (~/.codex/config.toml) expects TOML like this:

[[mcp_servers]]
name = "ida-remote"
command = "/Users/<you>/.local/bin/mcp-remote-py"
args = ["http://127.0.0.1:8080/mcp/sse"]

Claude Desktop (claude_desktop_config.json):

{
	"mcpServers": {
		"ida-remote": {
			"command": "mcp-remote-py",
			"args": ["http://127.0.0.1:8080/mcp/sse"]
		}
	}
}

Cursor (~/.cursor/mcp.json):

{
	"mcpServers": {
		"ida-remote": {
			"command": "mcp-remote-py",
			"args": ["http://127.0.0.1:8080/mcp/sse"]
		}
	}
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
	"mcpServers": {
		"ida-remote": {
			"command": "mcp-remote-py",
			"args": ["http://127.0.0.1:8080/mcp/sse"]
		}
	}
}

Troubleshooting

If you encounter issues, verify the remote SSE server emits JSON-RPC only on the default message event and that no unrelated events are being passed through.

If the command doesn’t appear in your system path, ensure the local bin directory is on PATH.

Logs are written to stderr by design; stdout remains free for MCP traffic.

Available tools

Bidirectional MCP proxy

Maintains a two-way channel by forwarding MCP JSON-RPC messages between the local STDIO client and the remote SSE endpoint.

Custom header support

Allows adding HTTP headers to HTTP POST requests sent to the remote endpoint.

Transport strategy control

Supports default http-first transport and a strict sse-only mode when the remote server lacks HTTP transport.