{"id":8307,"library":"mcp-proxy","title":"MCP Proxy","description":"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.","status":"active","version":"0.11.0","language":"en","source_language":"en","source_url":"https://github.com/sparfenyuk/mcp-proxy","tags":["proxy","mcp","model context protocol","sse","http","stdio","cli"],"install":[{"cmd":"pip install mcp-proxy","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core Model Context Protocol library used for handling MCP requests.","package":"mcp","optional":false},{"reason":"ASGI server for running the HTTP/SSE proxy.","package":"uvicorn","optional":false}],"imports":[],"quickstart":{"code":"import os\n\n# Example 1: Proxy a local stdio MCP server to expose it via SSE/HTTP\n# This command starts mcp-proxy listening on port 8080 and proxies\n# an 'mcp-server-fetch' stdio server, also enabling a named server 'my_server'.\n# Note: 'uvx' should be installed and in PATH, or specify full path.\nprint(\"Starting mcp-proxy to expose a local stdio server via SSE/HTTP...\")\nos.system(\"mcp-proxy --port 8080 --named-server my_server 'uvx mcp-server-fetch'\")\n\n# Example 2: Proxy an external SSE/HTTP MCP server to stdio\n# This command connects mcp-proxy to a remote SSE server at http://example.io/sse\n# and exposes it as a local stdio server (for clients like Claude Desktop).\n# Use a dummy token for demonstration; in real use, use os.environ.get('API_ACCESS_TOKEN', '')\n# to load from environment or a secure secret management system.\nprint(\"\\nStarting mcp-proxy to proxy a remote SSE server to stdio...\")\napi_token = os.environ.get('API_ACCESS_TOKEN', 'YOUR_DUMMY_TOKEN_HERE')\nprint(f\"Using API_ACCESS_TOKEN: {api_token[:5]}...\")\nos.system(f\"mcp-proxy http://example.io/sse --api-access-token {api_token}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update client configurations to provide the `API_ACCESS_TOKEN` or other required client credentials as specified by your `mcp-proxy` setup.","message":"Version 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.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Replace `--sse-port <value>` with `--port <value>` and `--sse-host <value>` with `--host <value>`.","message":"The 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.","severity":"deprecated","affected_versions":"Likely prior to v0.8.1, definitely by v0.11.0. Older versions (<0.5.0) may not support the new syntax."},{"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`.","message":"When `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=0.8.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add the `--pass-environment` argument to your `mcp-proxy` command: `mcp-proxy --pass-environment <other_args> <command_for_stdio_server>`.","cause":"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.","error":"No interpreter found in managed installations or search path"},{"fix":"Replace `--sse-port` with `--port` and `--sse-host` with `--host`.","cause":"You are using the deprecated `--sse-port` argument (or `--sse-host`). These arguments were replaced with a more generic naming convention.","error":"mcp-proxy: error: unrecognized arguments: --sse-port"},{"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.","cause":"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`.","error":"401 Unauthorized"},{"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.","cause":"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.","error":"Connection refused when client tries to connect to mcp-proxy"}]}