🚀 Universal MCP Proxy

The easiest way to make any MCP-capable client talk to remote HTTP / SSE / WebSocket endpoints.

✨ Why?

The Model-Context-Protocol (MCP) ecosystem is still young. Desktop clients such as Cursor or Claude Desktop currently speak local stdin/stdout MCP only. They cannot reach your shiny remote HTTP / SSE / WebSocket MCP servers directly.

Existing community proxies live in Python scripts or heavy Docker images – great for demos, awkward for daily use.

Universal MCP Proxy is a single‐file Node.js implementation you can run instantaneously via npx, globally via npm i -g, or embed as a library. Zero config, zero pain. 🥳

🛠️ Features

• 🔌 Transport-agnostic – auto-detects HTTP, SSE, or WebSocket endpoints
• 🪄 One-liner install – npx universal-mcp-proxy boots in seconds
• 🔒 Token cache & multi-environment management (~/.universal_mcp_proxy/tokens.json)
• 🔁 Smart reconnection with exponential back-off
• 🌐 OAuth helper – auto-opens browser & polls until authenticated
• 🔍 Pretty & JSON logging – choose your flavour
• 👾 Cross-platform – macOS, Linux, Windows
• 🤝 Pluggable design – add custom transports or auth flows easily

⚡️ Quick Start

# Forward local Cursor to a remote HTTP MCP endpoint
npx universal-mcp-proxy --endpoint https://mcp.example.com/mcp --transport auto

Need WebSocket? Just point to a wss://... URL – the proxy figures it out.

🔍 CLI Usage

universal-mcp-proxy [options]

Options
  -e, --endpoint <url>        MCP endpoint URL
  -t, --transport <type>      auto | websocket | sse | http   (default: auto)
      --token <jwt>           Authentication token (overrides cache)
  -l, --log-level <level>     debug | info | warn | error     (default: info)
      --log-format <fmt>      pretty | json                   (default: pretty)
      --no-reconnect          Disable automatic reconnection
      --max-reconnect-attempts <n>  Max reconnect attempts    (default: 5)
      --no-auto-open          Don’t open browser for OAuth

Sub-commands
  status                      Show live status / token info
  tokens list|clear           Token cache management

Tip: every flag is also available via environment variables – perfect for .env files.

🔧 Environment Variables

All configuration options can be set via environment variables for easy automation and .env file support:

Core Configuration

• UMCP_ENDPOINT - MCP endpoint URL (e.g., https://mcp.example.com/mcp)

• UMCP_TOKEN - Authentication token (overrides cache)
• MCP_TRANSPORT - Transport type: auto, websocket, sse, or http (default: auto)

Logging Configuration

• UMCP_LOG_LEVEL - Log level: debug, info, warn, or error (default: info)

• UMCP_LOG_FORMAT - Log format: pretty or json (default: pretty)

Reconnection Settings

• MCP_NO_RECONNECT - Set to "true" to disable automatic reconnection

• MCP_MAX_RECONNECT_ATTEMPTS - Maximum reconnect attempts (default: 5)

Browser & OAuth

• MCP_NO_AUTO_OPEN - Set to "true" to prevent browser from opening for OAuth

Cache & Storage

• MCP_CACHE_DIR - Custom cache directory for token storage

Example .env file

UMCP_ENDPOINT=https://mcp.example.com/mcp
UMCP_TOKEN=your_jwt_token_here
UMCP_LOG_LEVEL=debug
UMCP_LOG_FORMAT=json
MCP_TRANSPORT=auto
MCP_MAX_RECONNECT_ATTEMPTS=10

🔗 Example Workflows

1️⃣ Cursor ➡️ Remote HTTP MCP

export UMCP_ENDPOINT=https://mcp.mycorp.ai/mcp
npx universal-mcp-proxy | cursor

2️⃣ Claude Desktop ➡️ Remote WebSocket MCP

npx universal-mcp-proxy --endpoint wss://mcp.acme.dev/ws --transport websocket | claude-desktop

3️⃣ Dockerised

docker run --rm -it node:20 npx universal-mcp-proxy -e https://mcp.example.com/mcp

🗺️ Architecture (ASCII Art)

        JSON-RPC                          HTTP / SSE / WS
┌─────────────────┐                 ┌────────────────────┐
│  Local Client   │  ───────────▶   │   Remote MCP       │
│  (Cursor etc.)  │                 │     Server         │
└─────────────────┘                 └────────────────────┘
          ▲                                   ▲
          │ StdIO                             │
          │                                   │
          │         Token Cache (~/.universal_mcp_proxy)
          │                  ▲
          │                  │
          ▼                  │
    ┌─────────────────────────────────────────┐
    │     🚀  Universal MCP Proxy (Node)      │
    └─────────────────────────────────────────┘

🤝 Contributing

We ❤️ pull requests!

1. Fork ➡️ hack ➡️ submit PR
2. npm test must be green
3. Follow CONTRIBUTING.md for commit conventions & coding style

Roadmap highlights 🗓️

• Modular auth providers (Azure AD, Auth0)
• Native binary builds via pkg
• GUI tray app (auto-launch)

📜 License

Released under the MIT License – see LICENSE for full text.

Universal MCP Proxy is an NGO-driven initiative to grow the open MCP ecosystem. Your stars, issues, and PRs keep us moving! 🙌