Universal MCP Gateway (mcp-gateway)

A high-performance, multi-tenant Model Context Protocol (MCP) reverse proxy and gateway service built on @thargy/mcp-server-core.

---

Why mcp-gateway?

Most 3rd-party MCP servers (like github-mcp-server, Brave Search, SQLite, PostgreSQL) are built primarily for local desktop execution via stdio. When exposed over HTTP or Cloudflare Zero Trust tunnels, they often lack:

1. Cloudflare SSE Stream Priming: Immediate : heartbeat\n\n comments to bypass reverse proxy buffering.
2. Modern MCP Handshake Compatibility: Support for subscriptions/listen, server/discover, and stateless JSON-RPC dispatch.
3. Session Lifecycle Management: Proper Mcp-Session-Id header tracking and token authentication.

mcp-gateway acts as a single, multi-tenant adapter sitting between remote MCP clients (like Antigravity IDE, Cloudflare Zero Trust, Cursor) and one or more upstream 3rd-party MCP backends (containers, HTTP APIs, or stdio CLI tools).

---

Architecture

graph TD
    subgraph Clients ["MCP Clients"]
        AG["Antigravity IDE / Agents"]
        CFPortal["Cloudflare Zero Trust MCP Portal"]
    end

    subgraph Ingress ["Cloudflare Tunnel (mcp.thargy.com)"]
        Tunnel["cloudflared (HA Server)"]
    end

    subgraph Gateway ["mcp-gateway Container (:3007 -> :3008)"]
        App["@thargy/mcp-server-core Router"]
        GHRoute["/gh/mcp -> HttpProxyAdapter"]
        BraveRoute["/brave/mcp -> StdioProxyAdapter"]
    end

    subgraph Backends ["3rd-Party Backends"]
        GHContainer["github-mcp-backend (:8082)"]
        BraveCLI["@modelcontextprotocol/server-brave-search"]
    end

    Clients --> Ingress
    Ingress --> Gateway
    App --> GHRoute --> GHContainer
    App --> BraveRoute --> BraveCLI

---

Configuration (config.yaml)

port: 3008

routes:
  gh:
    type: http
    name: "github-mcp-server"
    description: "GitHub Model Context Protocol Server (repositories, commits, issues, PRs)"
    targetUrl: "http://github-mcp-backend:8082"
    authHeaderEnv: "GITHUB_PERSONAL_ACCESS_TOKEN"

  # brave:
  #   type: stdio
  #   name: "brave-search"
  #   description: "Brave Search MCP Server"
  #   command: "npx"
  #   args: ["-y", "@modelcontextprotocol/server-brave-search"]
  #   env:
  #     BRAVE_API_KEY: "${BRAVE_API_KEY}"