mcp-proxy

Converts MCP servers using stdio (standard input/output) transport into HTTP-based Server-Sent Events (SSE) endpoints. The proxy spawns a child process running the stdio-based MCP server, captures its stdout/stderr streams, parses the JSONRPC message protocol, and re-exposes it as an SSE HTTP server. This enables stdio-native MCP servers (which expect bidirectional pipe communication) to be accessed over HTTP without modifying the original server implementation.

Manages the spawning, monitoring, and cleanup of stdio-based MCP server child processes. The proxy handles process creation with proper environment setup, monitors process health and exit codes, captures and logs stderr output, and implements graceful shutdown with signal handling. This ensures the underlying MCP server process remains stable and recovers from transient failures or is properly terminated when the proxy shuts down.

Parses JSONRPC 2.0 messages from the raw byte stream of a child process's stdout, handling message boundaries, incomplete frames, and protocol errors. The proxy buffers incoming data, detects complete JSON objects (via brace matching or length prefixes if used by the server), validates JSONRPC structure (id, method, params, result, error fields), and queues messages for processing. This enables reliable bidirectional communication with stdio servers that send multiple messages in rapid succession or split messages across multiple write() calls.

Exposes the bridged MCP server as an HTTP endpoint that clients can connect to via Server-Sent Events (SSE). The proxy creates an HTTP server (using Node.js http or Express), implements an SSE endpoint (typically /sse or /stream) that accepts client connections, and streams JSONRPC responses back to connected clients as SSE events. Clients send requests via HTTP POST to a separate endpoint (e.g., /request) or embed them in the SSE connection, and the proxy routes responses back via the SSE stream. This enables web browsers and HTTP-only clients to interact with stdio MCP servers.

Maintains mapping between JSONRPC request IDs sent by HTTP clients and responses streamed back via SSE, ensuring each client receives only its own responses even when multiple clients are connected simultaneously. The proxy tracks pending requests in a map keyed by JSONRPC id, routes incoming responses from the stdio server back to the correct SSE client connection, and cleans up stale entries on client disconnect. This enables multiplexing of multiple concurrent MCP clients over a single stdio server connection.

Handles the MCP initialization handshake between the proxy and the underlying stdio server, exchanging protocol version information, client/server capabilities, and implementation details. The proxy sends an initialize request with client capabilities (supported tools, resources, etc.), receives the server's capabilities response, and caches this metadata for subsequent client requests. This ensures the proxy correctly advertises what the MCP server can do and validates that the server supports required protocol features.

Routes tool invocation requests from HTTP clients through the stdio server and streams results back via SSE. When a client sends a call_tool request, the proxy forwards it to the stdio server via stdin, waits for the tool_result response, and streams the result back to the client via SSE. The proxy handles tool execution errors, timeout scenarios, and large result payloads that may span multiple SSE events. This enables web clients to invoke MCP tools without understanding the underlying stdio protocol.

Exposes MCP resources (files, documents, etc.) as HTTP endpoints that clients can fetch via read_resource requests. The proxy implements a /resource or /read endpoint that accepts resource URIs, forwards read_resource requests to the stdio server, and returns the resource content as HTTP responses. This enables web clients to browse and retrieve MCP resources without understanding the MCP resource protocol or stdio transport.

Exposes MCP prompt templates as HTTP endpoints that clients can discover and invoke. The proxy implements a /prompts endpoint that lists available prompts (with descriptions and argument schemas), and a /invoke-prompt endpoint that executes prompts with client-provided arguments. When a client invokes a prompt, the proxy forwards the get_prompt request to the stdio server, receives the rendered prompt text, and returns it via HTTP. This enables web clients to use MCP prompts without understanding the MCP prompt protocol.

Detects and handles protocol violations, malformed messages, and server errors, returning appropriate JSONRPC error responses to clients. The proxy validates JSONRPC message structure, catches JSON parsing errors, detects missing required fields, and propagates server-side errors (JSONRPC error responses) back to clients. When the stdio server sends invalid data or crashes, the proxy attempts to recover or gracefully close client connections. This ensures clients receive meaningful error information instead of silent failures or connection hangs.