mcp-http-proxy

What is mcp-http-proxy?

mcp-http-proxy is an HTTP/SSE intermediary proxy server that manages a stdio-based MCP (Model Context Protocol) server process and exposes its tools and resources over standard HTTP and Server-Sent Events. It is designed for developers and applications that need to interact with MCP processes without handling stdio directly.

How to use mcp-http-proxy?

Run the script rpc-proxy-worker.js with Node.js (no additional install steps besides having Node.js). The server starts on port 3005 by default, serving a web dashboard at http://localhost:3005. Clients interact via HTTP endpoints (e.g., GET /tool/:toolName, POST /rpc/raw/command) or by connecting to the SSE endpoint at /sse.

Key features of mcp-http-proxy

• Manages the lifecycle of a child MCP server process.
• Provides HTTP endpoints for tools and raw JSON-RPC commands.
• Delivers real-time events via Server-Sent Events (SSE).
• Includes a web dashboard for tool discovery and debugging.
• Translates URL query parameters into JSON-RPC tools/call requests.
• Supports multiple client types (curl, browser, scripts).
• Handles parameter validation and error relay.
• Provides debugging endpoints for raw message history and logs.

Use cases of mcp-http-proxy

• Expose a local stdio-only MCP server to web applications via HTTP.
• Allow multiple HTTP clients to share a single managed MCP process.
• Enable programmatic interaction with MCP tools using standard REST/SSE.
• Debug and test MCP server responses without writing a custom client.

FAQ from mcp-http-proxy

What runtime does mcp-http-proxy require?

The proxy runs on Node.js. No other runtime dependencies are mentioned; the MCP server it manages is expected to be a separate process.

How do clients communicate with the MCP server through the proxy?

Clients send HTTP requests to endpoints like /rpc/raw/command (raw JSON-RPC) or /tool/:toolName (URL parameter style). The proxy forwards these as JSON-RPC commands to the child MCP process via stdin, and returns the response from stdout. Asynchronous events are pushed over SSE.

What endpoints does mcp-http-proxy provide?

The main endpoints are: GET / (dashboard), GET /tools, GET /tool/:toolName, POST /rpc/raw/command, GET /sse, GET /help, and several debugging endpoints (/rpc/command, /rpc/raw, /debug).

How does the proxy handle errors?

It returns HTTP status codes (e.g., 404 for unknown tools, 400 for invalid parameters) and validates parameters for /tool/:toolName. Errors from the MCP process are relayed back in HTTP responses or pushed via SSE.

Does mcp-http-proxy support authentication?

The README does not mention any authentication mechanism. The proxy is designed for local or trusted network use.