mcp-proxy

mcp-proxy

Connect to MCP servers that run on SSE transport, or expose stdio servers as an SSE server.

2,027
Stars
202
Forks
16
Releases

Overview

The mcp-proxy is a versatile proxy that lets MCP clients and servers communicate across different transport layers. It supports two modes: stdio to SSE/StreamableHTTP, where it runs as a proxy from a local stdio-based MCP server to a remote SSE endpoint, enabling clients (for example Claude Desktop) to talk to servers that are not natively SSE-enabled; and SSE to stdio, where it opens an SSE endpoint locally and spawns a stdio MCP server to handle requests from remote clients. Client mode accepts the MCP server SSE endpoint as the first argument and supports headers and OAuth2-based authentication (client id/secret and token URL) or a token supplied via API_ACCESS_TOKEN. The transport can be forced to streamable HTTP with --transport. The SSE-server mode exposes a port/host, passes environment variables to the local stdio server, and supports CORS configuration via --allow-origin; a --stateless option is available for streamable transports. Named servers can be defined via CLI or a JSON config file and are exposed under /servers/<name>/, with a global /status endpoint. A complete example config and usage patterns are provided in the README.

Details

Owner
sparfenyuk
Language
Python
License
MIT License
Updated
2025-12-07

Features

Two transport modes (stdio ↔ SSE)

Supports bridging MCP requests in both directions: stdio to SSE/StreamableHTTP and SSE to stdio.

Remote MCP SSE client mode with configurable transport

Connect to a remote SSE endpoint from stdio, choosing transport via --transport and authenticating with headers or OAuth credentials.

Expose local stdio server as an SSE server

Opens an SSE endpoint on a configurable host/port and spawns a local stdio MCP server to handle requests.

Named servers support

Define named stdio servers via CLI (--named-server) or a JSON config and access them under /servers/NAME/.

Status endpoint

Provides a global health/status endpoint at /status to monitor the proxy ecosystem.

Named-server JSON configuration format

JSON format for named servers (mcpServers) with command, args, timeout and transportType, plus notes about ignored fields and defaults.

Stateless mode for streamable HTTP

Option --stateless enables stateless mode for streamable http transports.

Environment and authentication options

Support for headers (--headers) and OAuth2 credentials (--client-id, --client-secret, --token-url) or API_ACCESS_TOKEN for authentication.

Audience

DevelopersBridge MCP stdio to SSE or expose stdio servers via SSE for remote access.
MCP operatorsManage named servers and monitor global health across proxies easily.
LLM IntegratorsEnable LLM tools to reach MCP servers through SSE proxies.
Cloud teamsDeploy and manage proxies in cloud environments with centralized monitoring and SSL.

Tags

MCPmcp-proxySSEstdiostreamablehttpproxynamed-serversauthenticationOAuth2headersconfighealthstatusDockercontainer