mcp-ha-proxy

A lightweight proxy server that forwards MCP stdio protocol to streamable HTTP MCP servers with automatic reconnection support.

Features

• 🔄 Auto-reconnection: Automatically reconnects to upstream MCP server on connection failure
• 📡 Protocol Bridge: Converts stdio MCP to streamable HTTP MCP
• 🪶 Lightweight: Minimal dependencies, single purpose
• 🚀 Easy to Use: Run with npx, no installation needed
• 📝 Optional Logging: Enable detailed logs when needed

Installation

No installation required! Use with npx:

npx mcp-ha-proxy --url http://localhost:3000

Or install globally:

npm install -g mcp-ha-proxy
mcp-ha-proxy --url http://localhost:3000

Usage

Basic Usage

npx mcp-ha-proxy --url http://localhost:3000

With Custom Timeout

npx mcp-ha-proxy --url http://localhost:3000 --timeout 60000

With Logging

npx mcp-ha-proxy --url http://localhost:3000 --log-path ./logs/mcp.log

Command Line Options

| Option | Description | Required | Default | |--------|-------------|----------|---------| | --url <url> | Upstream MCP server URL | Yes | - | | --timeout <ms> | Request timeout in milliseconds | No | 120000 (2 minutes) | | --log-path <path> | Log file path (logging disabled if not set) | No | - | | --help, -h | Show help message | No | - |

Use Cases

As a Cursor MCP Configuration

Add to your Cursor MCP configuration (~/.cursor/mcp.json or workspace config):

{
  "mcpServers": {
    "my-remote-mcp": {
      "command": "npx",
      "args": [
        "mcp-ha-proxy",
        "--url",
        "http://localhost:3000"
      ]
    }
  }
}

Proxy Remote MCP Server

npx mcp-ha-proxy --url https://my-mcp-server.example.com

Development with Logging

npx mcp-ha-proxy \
  --url http://localhost:3000 \
  --timeout 30000 \
  --log-path ./logs/debug.log

How It Works

┌─────────────┐         ┌──────────────┐         ┌─────────────────┐
│   Cursor    │ stdio   │ mcp-ha-proxy │  HTTP   │  Upstream MCP   │
│     or      │◄───────►│   (stdio)    │◄───────►│     Server      │
│  MCP Client │         │              │         │  (streamable)   │
└─────────────┘         └──────────────┘         └─────────────────┘

1. Accepts MCP protocol via stdio (standard input/output)
2. Forwards all requests to upstream HTTP MCP server
3. Handles connection failures with automatic reconnection
4. Returns responses back through stdio

Requirements

• Node.js >= 18.0.0

License

MIT

Contributing

Issues and pull requests are welcome!

Related

• Model Context Protocol
• MCP TypeScript SDK