mcp-http-proxy

An HTTP/SSE proxy server for Model Context Protocol (MCP) applications using stdio. Supports raw JSON-RPC commands via HTTP and implements direct stdio communication without an MCP SDK.

MCP RPC Proxy Worker

Overview

This Node.js script (`rpc-proxy-worker.js`) acts as an intermediary proxy server between HTTP clients and an underlying MCP (Model Context Protocol) server process. It simplifies interaction with an MCP server by:

1. Managing the MCP Process: It spawns and manages the lifecycle of a configured MCP server running as a child process.

2. Providing HTTP Endpoints: It exposes HTTP endpoints that allow clients to interact with the MCP server's tools and resources without needing to handle the MCP protocol's stdio communication directly.

3. Offering Real-time Events: It provides a Server-Sent Events (SSE) endpoint for clients to receive asynchronous notifications and responses from the MCP server.

4. Providing a Web Interface: It includes a basic web dashboard for viewing available tools and simple interfaces for debugging and sending commands.

Benefits

This `mcp-http-proxy` provides several advantages:

• Standard Web Protocol Access: Exposes an `stdio`-based MCP server over standard HTTP (GET/POST) and Server-Sent Events (SSE), making it accessible to web applications and diverse HTTP clients (`curl`, Python `requests`, JavaScript `fetch`, etc.).
• Decoupling and Centralization: Acts as a stable intermediary, allowing multiple clients to interact with a single managed MCP process instance without needing to handle process management themselves.
• Flexible Client Interaction: Supports multiple interaction methods:
• Real-time Communication: Enables the server to push asynchronous responses, logs, and events to connected clients via the `/sse` endpoint, ideal for long-running tasks and responsive UIs.
• Simplified Client Dependencies: Clients interact via standard HTTP, eliminating the need for them to install or use specific MCP SDKs or handle `stdio` communication.
• Built-in Introspection and Debugging: Includes basic web interfaces (`/`, `/rpc/command`, `/debug`, etc.) for tool discovery, manual testing, and observing the raw communication flow.
• Direct Proxy Control: By implementing the `stdio` communication directly within the proxy (without relying on the MCP SDK *in the proxy*), it offers fine-grained control over the proxy-to-MCP interaction and minimizes internal dependencies.

How it Works

The system operates with two main processes:

1. The Proxy Worker (This Script):

2. The MCP Server (Child Process):

Launching the Server

1. Prerequisites: Ensure you have Node.js installed.

2. Navigate: Open your terminal and change the directory to where `rpc-proxy-worker.js` is located.

3. Run: Execute the command:

node rpc-proxy-worker.js

4. Output: You should see output indicating the server is running, typically including:

Web interface running on http://localhost:3005
    SSE endpoint available at http://localhost:3005/sse

The server listens on port 3005 by default.

Communication Mechanisms

1. Stdio (Proxy MCP Process) - *Internal*

This is the internal communication channel between the proxy worker script and the child MCP server process it manages.

• Proxy -> MCP: The proxy sends validated JSON-RPC command strings to the MCP process's `stdin`.
• MCP -> Proxy:
• User Interaction: Users do not directly interact with the *proxy's* stdio to send commands. All interaction happens via the HTTP endpoints.

2. Server-Sent Events (SSE) (Proxy -> Clients) - *External*

This is an external, primarily unidirectional communication channel allowing the proxy to push events to connected HTTP clients in real-time.

• Connection: Clients establish an SSE connection by making an HTTP `GET` request to the `/sse` endpoint. The proxy keeps this connection open.
• Pushing Events: When the proxy receives data from the MCP process's `stdout` (responses) or `stderr` (logs/errors), it formats this data according to the SSE protocol (`data: \n\n`) and pushes it down the open connection to *all* currently connected SSE clients.
• Sending Commands: Clients cannot send commands *back* to the proxy over the same SSE connection. To execute a command, an SSE client must make a separate standard HTTP request (e.g., `POST` to `/rpc/raw/command` or `GET` to `/tool/:toolName`). The result of that command will then typically be pushed back to the client via the `/sse` stream it's listening on.

Interacting with the Proxy (HTTP Endpoints)

The proxy exposes several HTTP endpoints:

• `GET /`

• `GET /tools`

• `GET /tool/:toolName`

• `POST /rpc/raw/command`

• `GET /sse`

• `GET /sse-client`

• `GET /help`

• Debugging Endpoints:

• (Optional) MCP Management Endpoints: (`/mcp/*`)

Sending Commands (Examples)

Using `POST /rpc/raw/command` (Recommended for programmatic use)

Send the complete JSON-RPC request in the body.

curl (Bash/zsh/WSL):

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  http://localhost:3005/rpc/raw/command

curl (Windows cmd - careful with quoting):

curl -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}" http://localhost:3005/rpc/raw/command

PowerShell:

$rpcBody = @{
    jsonrpc = "2.0"
    method = "tools/call"
    id = 2
    params = @{
        name = "your_tool_name"
        arguments = @{
            param1 = "value1"
            count = 10
        }
    }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri http://localhost:3005/rpc/raw/command -Method Post -ContentType 'application/json' -Body $rpcBody

Using `GET /tool/:toolName` (Convenient for simple GET requests)

Provide parameters in the URL query string.

curl:

# Assuming a tool 'worker_get' exists that takes a 'name' parameter
curl "http://localhost:3005/tool/worker_get?name=my-worker"

Error Handling

The proxy attempts to handle errors gracefully:

• HTTP Errors: Returns standard HTTP status codes (e.g., 404 for unknown tools/endpoints, 400 for invalid parameters on `/tool/:toolName`).
• Parameter Validation: The `/tool/:toolName` endpoint validates query parameters against the tool's schema before sending the command. Errors are returned in the HTML response. The `/rpc/raw/command` endpoint performs basic JSON-RPC structure validation.
• MCP Errors: Errors returned by the underlying MCP process (e.g., tool execution failures) are captured from its `stdout` (as JSON-RPC error responses) or `stderr` and are relayed back to the client either in the direct HTTP response (for `/rpc/raw/command`) or within the HTML page (for `/tool/:toolName`), and potentially pushed via SSE.

Cleanup

The script registers handlers for `exit` and `SIGINT` (Ctrl+C). On exit, it attempts to:

1. Kill the child MCP process (`MCPWorker.mcpProcess.kill()`).

2. Close all active SSE client connections.