Registry / llm-agents / mcp-proxy

mcp-proxy

JSON →
library0.11.0pypypiunverified

A Python-based MCP proxy server (Model Context Protocol) that facilitates communication between MCP clients and various backend MCP servers (stdio, SSE, or streamable HTTP). It supports two primary modes: proxying a local stdio server to SSE/StreamableHTTP, or proxying an external SSE/StreamableHTTP server to stdio. The library is actively maintained, with version 0.11.0 released in January 2026, and typically sees frequent updates.

pip install mcp-proxy
INSTALL
IMPORT
SIG · MCP-PROXY
M
mcp-proxy
llm-agentspythonv0.11.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

The `mcp-proxy` library is primarily a command-line tool. These examples demonstrate how to run `mcp-proxy` to expose a local STDIO MCP server over SSE/HTTP, or to proxy a remote SSE/HTTP MCP server to STDIO, including the use of named servers. Ensure `uvx` (part of the `uv` toolchain) is available if you're using it to run local MCP servers.

import os # Example 1: Proxy a local stdio MCP server to expose it via SSE/HTTP # This command starts mcp-proxy listening on port 8080 and proxies # an 'mcp-server-fetch' stdio server, also enabling a named server 'my_server'. # Note: 'uvx' should be installed and in PATH, or specify full path. print("Starting mcp-proxy to expose a local stdio server via SSE/HTTP...") os.system("mcp-proxy --port 8080 --named-server my_server 'uvx mcp-server-fetch'") # Example 2: Proxy an external SSE/HTTP MCP server to stdio # This command connects mcp-proxy to a remote SSE server at http://example.io/sse # and exposes it as a local stdio server (for clients like Claude Desktop). # Use a dummy token for demonstration; in real use, use os.environ.get('API_ACCESS_TOKEN', '') # to load from environment or a secure secret management system. print("\nStarting mcp-proxy to proxy a remote SSE server to stdio...") api_token = os.environ.get('API_ACCESS_TOKEN', 'YOUR_DUMMY_TOKEN_HERE') print(f"Using API_ACCESS_TOKEN: {api_token[:5]}...") os.system(f"mcp-proxy http://example.io/sse --api-access-token {api_token}")
mcp-proxy --version
Debug
Known issues
breakingVersion 0.11.0 introduced client credentials authentication for SSE and streamable HTTP connections. Existing unauthenticated or differently authenticated clients may break and require updates to provide the necessary credentials.
fix
Update client configurations to provide the `API_ACCESS_TOKEN` or other required client credentials as specified by your `mcp-proxy` setup.
affects: >=0.11.0
deprecatedThe command-line arguments `--sse-port` and `--sse-host` are deprecated. They have been replaced by the more generic `--port` and `--host` arguments for specifying the listening address.
fix
Replace `--sse-port <value>` with `--port <value>` and `--sse-host <value>` with `--host <value>`.
affects: Likely prior to v0.8.1, definitely by v0.11.0. Older versions (<0.5.0) may not support the new syntax.
gotchaWhen `mcp-proxy` starts a local STDIO server (e.g., via `uvx` or `npx`), the environment variables of the `mcp-proxy` process are not automatically passed to the child process. This can lead to 'No interpreter found' or similar errors if the child process relies on specific environment settings.
fix
Use the `--pass-environment` argument when running `mcp-proxy` to forward all current environment variables to the spawned STDIO server. Example: `mcp-proxy --pass-environment --port 8080 uvx mcp-server-fetch`.
affects: All versions
breakingVersion 0.8.0 introduced a significant feature for 'Named servers', allowing a single `mcp-proxy` instance to manage multiple STDIO servers. This changed the configuration paradigm for handling multiple backend servers, potentially breaking existing deployments that might have relied on workarounds or different configurations for such scenarios.
fix
Review the documentation for 'Named servers' and update your `mcp-proxy` command-line arguments or `servers.json` configuration file to align with the new approach for managing multiple backend servers.
affects: >=0.8.0
Errors
Common errors & fixes
No interpreter found in managed installations or search path
When `mcp-proxy` executes a command like `uvx` or `npx` for a local STDIO server, the child process does not inherit the necessary environment variables (e.g., PATH, Python interpreter location) by default.
fix
Add the `--pass-environment` argument to your `mcp-proxy` command: `mcp-proxy --pass-environment <other_args> <command_for_stdio_server>`.
mcp-proxy: error: unrecognized arguments: --sse-port
You are using the deprecated `--sse-port` argument (or `--sse-host`). These arguments were replaced with a more generic naming convention.
fix
Replace `--sse-port` with `--port` and `--sse-host` with `--host`.
401 Unauthorized
The `mcp-proxy` is configured to require authentication (e.g., an API key or client credentials), but the incoming client request is missing the required `Authorization` header or `API_ACCESS_TOKEN`.
fix
Ensure the client making requests to `mcp-proxy` provides the correct authentication credentials, typically via an `Authorization: Bearer <token>` header or `X-API-Key: <key>`, or by setting the `API_ACCESS_TOKEN` environment variable if configured this way. Alternatively, review `mcp-proxy` configuration to disable authentication if it's not needed for your environment.
Connection refused when client tries to connect to mcp-proxy
The `mcp-proxy` server is either not running, listening on a different IP address or port than the client expects, or a firewall is blocking the connection to the specified host and port.
fix
Verify that `mcp-proxy` is running (`ps aux | grep mcp-proxy`), check the `--host` and `--port` arguments used when starting the proxy, and confirm that no firewall rules (e.g., `ufw`, `iptables`, security groups) are preventing inbound connections to the `mcp-proxy`'s listening address and port.
Upgrade
Version history
0.11.0latest on PyPI · released Jan 15, 2026
Audit
Dependencies
mcprequiredCore Model Context Protocol library used for handling MCP requests.
uvicornrequiredASGI server for running the HTTP/SSE proxy.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
mcp-proxy — pip install mcp-proxy · libregistry