Server facts
mcp-proxy
Project
- Author
- sparfenyuk
- Repository
- github.com/sparfenyuk/mcp-proxy
- License
- MIT
- Category
- MCP Gateways & Proxies
Tech
- Runtime / language
- pythonPython
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 2,791
- Last commit
- Data as of
Tags
- Proxy
- Sse
- Stdio
- Streamable Http
- Transport Bridge
Overview
mcp-proxy handles transport compatibility rather than supplying a new application-specific tool collection. In one mode, a client starts it over stdio and the proxy connects to a remote MCP service using SSE or Streamable HTTP. That remote connection can carry custom headers, a bearer token from the environment, or OAuth2 client credentials. Streamable HTTP must be selected explicitly when the upstream service uses it. In the other direction, the proxy starts a local stdio server and exposes network access, allowing clients to reach a server that otherwise expects process-based communication.
Multiple local servers can be assigned names and routed under separate URL paths, using command-line definitions or a JSON configuration file. A supplied file takes precedence over command-line named-server entries, and standard timeout and transportType fields are ignored when loading those definitions. Additional controls cover host binding, ports, child-process environments, working directories, CORS, and exposed headers. The package can be installed with uv or pipx, and container images are also documented. Users wrapping a local server still need that server's executable and dependencies; the default container, for example, does not include uv. The README also marks older SSE-specific host and port flags as deprecated in favor of general options. Its value lies in reusing existing MCP services across connection styles, not replacing the underlying services or their tools.
Install & configure
Requirements
- mcp-proxy installed using uv or pipx
- uvx and the mcp-server-fetch package for this documented example
- An MCP-compatible client
mcp-proxy --port=8080 uvx mcp-server-fetchThis README example exposes a local fetch stdio server through the proxy. Install mcp-proxy with uv tool install mcp-proxy or pipx install mcp-proxy first. The opposite mode takes an upstream URL; choose --transport=streamablehttp for a Streamable HTTP upstream.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
A supported configuration example is not available for this client and transport. Check the client documentation for its connection flow; do not substitute an undocumented JSON format.
Read the Claude Desktop setup guideConfig file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-proxy": {
"url": "http://127.0.0.1:8080/sse"
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
A supported configuration example is not available for this client and transport. Check the client documentation for its connection flow; do not substitute an undocumented JSON format.
Read the VS Code setup guideConfig file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-proxy": {
"serverUrl": "http://127.0.0.1:8080/sse"
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-proxy": {
"type": "sse",
"url": "http://127.0.0.1:8080/sse"
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
No individual tool names were confirmed in the source material. Check the repository for its current tool list.
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Connect a stdio-only client to a remote MCP endpoint.
- Expose a local stdio server for network clients.
- Route multiple named local servers behind separate URL paths.
- Pass authentication headers or OAuth2 credentials to an upstream service.
Strengths
- Supports both remote-client bridging and local-server exposure.
- Offers named-server routing through CLI or JSON configuration.
- Includes authentication, environment, and CORS configuration options.
Limitations
- Wrapped server executables and dependencies must be available separately.
- The default container image does not include uv.
- Named-server timeout and transportType fields are ignored.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.