Universal MCP Gateway

A self-hosted Model Context Protocol (MCP) gateway that aggregates all your MCP servers behind a single Streamable HTTP endpoint. Includes automatic registry discovery, on-demand Docker provisioning, and multi-device support.

Features

• Single Endpoint — All MCP servers exposed via one URL (/all for universal, /mcp for legacy)
• Registry Auto-Broker — Mirrors the official MCP Registry (19,000+ servers), provisions on demand in isolated Docker containers
• Multi-Device — Control server, laptop, and Windows PC from one gateway via SSH
• SSE Keepalive — Prevents Cloudflare/proxy idle timeouts on streaming connections
• OAuth2 PKCE — Optional OAuth2 authorization code flow with PKCE support
• Workflow Engine — Save and replay multi-step tool sequences
• Bearer Auth — Simple token-based authentication

Architecture

                    mcp.yourdomain.com (:8798)
                           │
                    ┌──────▼──────┐
                    │ MCP Router  │  Path-based routing
                    │  router.mjs │  /all → Universal, /mcp → Legacy
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
    ┌─────────▼──┐  ┌─────▼────┐  ┌──▼──────────┐
    │ Universal  │  │ Registry │  │  Child MCPs │
    │ Gateway    │  │ Autobroker│  │ (remote +   │
    │ gateway.mjs│  │ registry- │  │  stdio)     │
    └────────────┘  │ manager   │  └─────────────┘
                    └───────────┘

Quick Start

# Clone
git clone https://github.com/Samuel-Mencke/mcp-gateway.git
cd mcp-gateway

# Install dependencies
npm install

# Configure
cp .env.example .env
# Edit .env — set MCP_PUBLIC_URL and generate a token

# Generate auth token
echo -n "$(openssl rand -hex 32)" > ~/.mcp-gateway/token

# Start the gateway
node gateway.mjs    # Port 8799
# In another terminal:
node router.mjs     # Port 8798 (public-facing)

Configuration

All configuration is via environment variables. See .env.example for all options.

Key Variables

Variable	Default	Description
MCP_PORT	8799	Universal Gateway listen port
MCP_ROUTER_PORT	8798	Router listen port
MCP_PUBLIC_URL	http://localhost:8798	Your public URL (domain/tunnel)
MCP_STATE_DIR	~/.mcp-gateway	State directory (registry, tokens, etc.)
MCP_BEARER_TOKEN	(from $MCP_STATE_DIR/token)	Auth token

Multi-Device (Optional)

Set these to enable SSH-based remote control:

# Windows PC
MCP_PC_HOST=windows-host
MCP_PC_USER=username

# Linux laptop
MCP_LAPTOP_HOST=laptop-host
MCP_LAPTOP_USER=username

Default MCP Servers

The gateway ships with these servers enabled by default:

• Context7 — Current library documentation
• Exa — Web search and fetch
• MCP Docs — Official MCP documentation
• GitHub — Official GitHub MCP server (requires gh auth)
• Playwright — Browser automation
• Chrome DevTools — Debugging and performance
• Filesystem — Sandboxed file access
• Memory — Persistent knowledge graph
• Sequential Thinking — Structured planning

Additional servers can be provisioned on demand from the official MCP Registry via ensure_capability.

Registry Auto-Broker

The gateway mirrors the complete official MCP Registry and can provision any supported server on demand:

Agent: "I need PostgreSQL schema inspection"
Gateway: Searches registry → provisions postgres-mcp → probes handshake → ready

Provisioned servers run in restricted Docker containers:

• Read-only root filesystem
• No host mounts
• Dropped capabilities
• CPU/RAM/PID limits
• Blocked private/Tailscale egress

Deployment

systemd

# ~/.config/systemd/user/mcp-router.service
[Unit]
Description=MCP Router
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/mcp-gateway
Environment=MCP_ROUTER_PORT=8798
ExecStart=/usr/bin/node %h/mcp-gateway/router.mjs
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

# ~/.config/systemd/user/mcp-universal.service
[Unit]
Description=MCP Universal Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/mcp-gateway
EnvironmentFile=%h/mcp-gateway/.env
ExecStart=/usr/bin/node %h/mcp-gateway/gateway.mjs
Restart=always
RestartSec=5
TimeoutStopSec=20

[Install]
WantedBy=default.target

Cloudflare Tunnel

No port-forwarding needed — use a Cloudflare Tunnel:

# ~/.cloudflared/config.yml
ingress:
  - hostname: mcp.yourdomain.com
    service: http://127.0.0.1:8798
    originRequest:
      noTLSVerify: true
      connectTimeout: 30s
      keepAliveConnections: 100
      keepAliveTimeout: 600s

Client Configuration

The gateway works with any MCP-compatible client:

Client	Config
Claude Code	type: "url", url: "https://mcp.yourdomain.com/all"
OpenAI Codex	type: "streamable-http", url: "https://mcp.yourdomain.com/all"
Cursor	url: "https://mcp.yourdomain.com/all", transport: "streamable-http"
Hermes Agent	type: "streamable-http", url: "https://mcp.yourdomain.com/all"
OpenCode	type: "streamable-http", url: "https://mcp.yourdomain.com/all"

All clients need: headers: { Authorization: "Bearer <your-token>" }

Files

File	Description
router.mjs	Path-based router, OAuth2, SSE keepalive
gateway.mjs	Universal MCP gateway server
registry-manager.mjs	Registry sync, auto-provisioning, AGENTS.md generation
workflow-store.mjs	Durable workflow persistence
server.mjs	Legacy ChatGPT connector (admin/SSH tools)
windows-runner.py	Windows desktop automation runner

Requirements

• Node.js >= 18
• Docker (for registry auto-provisioning)
• SSH access (for multi-device support)

License

MIT