Server profile

mcp-proxy

mcp-proxy bridges MCP transport mismatches between clients and servers. It can connect a stdio client to a remote SSE or Streamable HTTP server, or expose local stdio servers through network endpoints.

Server facts

mcp-proxy

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
Documented launch / install command
mcp-proxy --port=8080 uvx mcp-server-fetch

This 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.

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 guide

Config 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.

Cursor configuration
{
  "mcpServers": {
    "mcp-proxy": {
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

Read the Cursor setup guide

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 guide

Config 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.

Windsurf configuration
{
  "mcpServers": {
    "mcp-proxy": {
      "serverUrl": "http://127.0.0.1:8080/sse"
    }
  }
}

Read the Windsurf setup guide

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.

Claude Code configuration
{
  "mcpServers": {
    "mcp-proxy": {
      "type": "sse",
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

Read the Claude Code setup guide

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

The supplied README describes transport bridging. Actual application tools come from the connected MCP servers.

Yes. Set --transport=streamablehttp when connecting to an upstream that uses that transport.

Yes. Named servers can be configured on the command line or through a JSON file and receive separate URL paths.

No. The README explicitly says uv is not included by default and shows how to extend the image.

Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.

Related MCP servers

Supergateway

MCP Gateways & Proxies

Supergateway bridges MCP transports so stdio servers can reach network clients and remote services can appear locally over stdio. It supports SSE, WebSockets, and Streamable HTTP modes through command-line configuration.

Unla MCP Gateway

MCP Gateways & Proxies

Unla is a Go gateway that exposes existing APIs and MCP servers through MCP endpoints using configuration. It includes a management interface, recoverable sessions, multi-tenant support, and deployment options for containers or Kubernetes.

mcpo

MCP Gateways & Proxies

mcpo makes MCP tools available through an OpenAPI-compatible HTTP server. It is for agents and applications that consume OpenAPI endpoints rather than communicating with MCP servers directly.

MCPHub

MCP Gateways & Proxies

Organize multiple MCP servers behind shared HTTP or SSE endpoints. MCPHub adds a management dashboard, group-level visibility controls, semantic routing, authentication, and a terminal interface.

ContextForge

MCP Gateways & Proxies

ContextForge registers and proxies tools, agents, and APIs behind a unified gateway. It targets teams that need discovery, authentication, observability, and policy controls across MCP, A2A, REST, and gRPC services.

MCP Proxy Server

MCP Gateways & Proxies

MCP Proxy Server combines multiple MCP backends behind one HTTP entrypoint. It aggregates tools, prompts, and resources while connecting to stdio, SSE, or streamable HTTP servers.

MCP Hub

MCP Gateways & Proxies

MCP Hub coordinates multiple MCP servers behind one client endpoint. It provides a REST management API and web UI, with server lifecycle controls, authentication handling, and live capability updates.

MCP Link

MCP Gateways & Proxies

MCP Link converts OpenAPI V3 descriptions into MCP interfaces for existing REST APIs. Developers can expose API operations to agents without changing the original implementation and filter which routes are included.