mcp-http-proxy

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:
  • Simplified URL Parameters (/tool/:toolName): Easy for clients needing simple GET requests; the proxy handles JSON-RPC translation.
  • Raw JSON-RPC (/rpc/raw/command): Provides full control for clients constructing their own JSON-RPC commands via HTTP POST.
• 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):

   • Runs as a Node.js process.
   • Starts an HTTP server (using Express) to listen for client requests.
   • Spawns the actual MCP server as a child process based on the configuration (MCP_CONFIG).
   • Communicates with the child MCP process using its standard input (stdin), standard output (stdout), and standard error (stderr).
   • Handles translating some HTTP requests (like URL parameters) into JSON-RPC commands for the MCP process.
   • Forwards raw JSON-RPC commands received via specific HTTP endpoints to the MCP process.
   • Reads responses and events from the MCP process's stdout/stderr.
   • Sends responses back to HTTP clients.
   • Pushes events and asynchronous responses to connected SSE clients.

2. The MCP Server (Child Process):

   • Launched by the proxy worker.
   • Listens for JSON-RPC commands on its stdin.
   • Executes MCP operations (like listing/calling tools).
   • Writes JSON-RPC responses and protocol messages to its stdout.
   • Writes logs or errors to its stderr.

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:
  • The MCP process sends JSON-RPC response strings (results, errors, protocol messages) to its stdout.
  • The MCP process sends log messages or fatal errors to its stderr.
• 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: <json_string>\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 /

  • Displays the main HTML dashboard, listing available MCP tools discovered from the child process. Provides forms to execute tools via the /tool/:toolName endpoint.

• GET /tools

  • Returns a JSON array listing all available tools provided by the MCP server, including their names, descriptions, and input schemas.

• GET /tool/:toolName

  • Executes a specific tool.
  • Parameters for the tool are provided as URL query parameters (e.g., /tool/my_tool?param1=valueA&param2=123).
  • The proxy translates these URL parameters into a valid JSON-RPC tools/call request object, validating them against the tool's schema.
  • Sends the command to the MCP process via stdio.
  • Returns an HTML page displaying the RPC command sent and the response received from the MCP process.

• POST /rpc/raw/command

  • Executes a raw JSON-RPC command.
  • Expects the full JSON-RPC 2.0 request object in the POST request body with Content-Type: application/json.
  • The proxy validates the structure of the incoming request body against the basic RPC schema.
  • It forwards the validated, raw command directly to the MCP process's stdin.
  • Returns the raw JSON-RPC response received from the MCP process's stdout directly in the HTTP response body as JSON. This is the primary endpoint for programmatic interaction where you construct the full RPC call yourself.

• GET /sse

  • Establishes a Server-Sent Events stream. Clients connect here to receive real-time events (MCP responses, logs) pushed from the server.

• GET /sse-client

  • Provides a simple HTML page that connects to the /sse endpoint and displays the received events. Useful for debugging the SSE stream.

• GET /help

  • Displays an HTML page providing documentation for the available tools and how to use the /tool/:toolName endpoint.

• Debugging Endpoints:

  • GET /rpc/command: Displays an HTML interface for manually constructing and sending RPC commands via a web form (uses /rpc/raw/command internally).
  • GET /rpc/raw: Shows a JSON history of raw messages exchanged between the proxy and the MCP process.
  • POST /rpc/raw/clear: Clears the raw message history.
  • GET /debug: Displays a more comprehensive HTML debug interface showing RPC, process, and SSE events.
  • GET /debug/logs: Returns the current debug logs as JSON.
  • GET /debug/sse: SSE stream specifically for debug log events.

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

  • Endpoints like /mcp/install, /mcp/start, /mcp/stop, /mcp/list are present for dynamically managing different MCP server installations if the mcp-manager.js is used.

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.