MCP Http Proxy

🚀 MCP Proxy Usage Documentation

This MCP proxy script offers a unified interface for users to interact with the MCP (Miner Control Protocol). It provides multiple HTTP endpoints, supporting both GET and POST requests to send commands and receive real - time responses.

✨ Features

1. Sub - process Launch: Automatically starts a sub - process to run the MCP service after the proxy is launched.
2. Multiple Endpoint Support: Offers multiple HTTP endpoints to handle different types of requests.
3. Parameter Validation: Conducts strict security checks on all user inputs to prevent potential attacks.
4. Error Handling: Gracefully handles issues and returns user - friendly error messages.

🚀 Quick Start

Starting the Proxy

# Run the proxy script in the terminal
node mcp - proxy.js

Sending Commands

Method 1: Using POST /rpc/raw/command (Suitable for Programmatic Calls)

Send the complete JSON - RPC request in the request body.

Example curl request (Linux/macOS):

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

Example curl request (Windows Command Prompt):

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

PowerShell Example:

$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

Method 2: Using GET /tool/:toolName (Suitable for Simple GET Requests)

Pass parameters through the query parameters of the URL.

Example curl request:

# Assume there is a tool named 'worker_get' that accepts the 'name' parameter
curl "http://localhost:3005/tool/worker_get?name=my - worker"

Real - time Event Push

SSE Stream

Establish a Server - Sent Events stream through the GET /sse endpoint to receive real - time messages pushed by the server.

Example curl request:

curl http://localhost:3005/sse

Debug Interface

Access http://localhost:3005/debug to view more comprehensive debug information, including:

• The number of currently active SSE connections.
• The latest proxy logs.
• Request history.
• Raw message exchange records.

🔧 Error Handling

When an error occurs, the proxy tries to handle it gracefully and provides friendly feedback:

1. HTTP Errors: Returns standard HTTP status codes (e.g., 404 for unknown tools or endpoints, 400 for invalid parameters).
2. Parameter Validation: The /tool/:toolName endpoint conducts strict pattern - matching checks on query parameters. Any format errors will be intercepted, and detailed error messages will be returned.
3. MCP Errors: If the underlying MCP process returns an error (e.g., tool execution failure), the proxy captures these error messages and returns them to the client via an HTTP response, and pushes event notifications in the SSE stream.

Stopping the Proxy

To stop the proxy, press Ctrl + C or send a SIGINT signal. Before exiting, the proxy performs the following cleanup operations:

1. Terminate the Sub - process: Call MCPWorker.mcpProcess.kill() to end the running MCP service.
2. Close Connections: Disconnect all active SSE client connections to ensure proper resource release.

📚 Additional Features

MCP Management Endpoints (Optional)

If mcp - manager.js is enabled, the proxy also provides some additional management endpoints:

• /mcp/install: Install a new MCP instance.
• /mcp/start: Start a specified MCP service.
• /mcp/stop: Stop a running MCP service.
• /mcp/list: List all available MCP instances.

These features allow users to dynamically manage multiple MCP services, enhancing the system's flexibility and scalability.

📄 Security Considerations

1. Input Validation: The proxy conducts strict validation on all user inputs to prevent injection attacks.
2. Access Control: By default, all endpoints are public. It is recommended to configure basic authentication or use more advanced authentication mechanisms to protect sensitive functions in a production environment.
3. Logging: It is recommended to enable detailed logging for auditing and troubleshooting.

Logging and Monitoring

The proxy provides a built - in logging system that supports recording all requests, responses, and internal state changes. By analyzing the logs, the system's running status can be effectively monitored, and potential problems can be detected in a timely manner.

Summary

The MCP proxy provides a powerful and flexible interface that simplifies the interaction with the MCP service. Whether it's simple command execution or complex task scheduling, the proxy can well meet the requirements. Through reasonable configuration and use of its various features, users can efficiently manage and control their miner resources.