Skip to main content
Glama
deenesjakoruzh
thargy

mcp-gateway

by thargy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Universal MCP Gateway (mcp-gateway)

A high-performance, multi-port Model Context Protocol (MCP) reverse proxy, dynamic provisioning engine, and infrastructure orchestrator built on @thargy/mcp-server-core.

1. System Overview

mcp-gateway centralizes, secures, and dynamically orchestrates local and containerized MCP servers behind a unified multi-port architecture (4000-4099).

flowchart TD
    subgraph Clients ["AI Clients & Agents"]
        Agent["Antigravity IDE / Cursor / Claude Desktop"]
    end

    subgraph Tunnel ["Cloudflare Zero Trust Ingress (mcp.thargy.com)"]
        T_Admin["https://mcp.thargy.com/gateway/mcp → Port :4000"]
        T_GH["https://mcp.thargy.com/gh/mcp → Port :4001"]
        T_CF["https://mcp.thargy.com/cf/mcp → Port :4002"]
        T_Dyn["https://mcp.thargy.com/<key>/mcp → Port :4007+"]
    end

    subgraph Host ["Docker Host @ 192.168.64.250"]
        subgraph Gateway ["mcp-gateway (Port Block 4000-4099)"]
            Admin["Port :4000: Management Plane (Bearer GATEWAY_ADMIN_TOKEN)<br/>• provision_mcp, update_mcp, deprovision_mcp<br/>• list_mcps, get_mcp_diagnostics<br/>• Plugin Tools (env, docker, cloudflare)"]
            S_GH["Port :4001: github-mcp-server (Wrapped Proxy)"]
            S_CF["Port :4002: cloudflare-mcp (Wrapped Proxy)"]
            S_Docker["Port :4003: docker-mcp (Tier-1 Passthrough)"]
            S_HA["Port :4004: homeassistant-mcp (Tier-1 Passthrough)"]
            S_Prox["Port :4005: proxmox-mcp (Tier-1 Passthrough)"]
            S_UniFi["Port :4006: unifi-mcp (Tier-1 Passthrough)"]
            S_Dyn["Port :4007+: Dynamic Provisioned Tool Listeners"]
        end
    end

    Agent --> Tunnel
    T_Admin --> Admin
    T_GH --> S_GH
    T_CF --> S_CF
    T_Dyn --> S_Dyn

Related MCP server: Shared MCP Gateway

2. Key Capabilities

A. Dedicated Multi-Port Architecture (:4000 - :4099)

  • Each MCP tool is assigned a dedicated TCP port in the 4000-4099 range.

  • Isolates tool lifecycles: restarting or updating one tool listener never disrupts any other active MCP server.

  • Pre-mapped in Docker Compose to eliminate container recomposition when new tools are provisioned.

B. 3 Proxy Architecture Tiers

  1. Tier 1 (Pure Raw Passthrough): Active when wrappers is omitted. Routes raw SSE/HTTP streams directly to the upstream backend with zero MCP protocol parsing overhead.

  2. Tier 2 (Protocol-Wrapped Open Access): Active when wrappers: { "": { ... } }. Injects Cloudflare SSE Stream Priming (: heartbeat\n\n) to bypass reverse proxy buffering.

  3. Tier 3 (Strict Authenticated Wrapped): Active when wrappers maps client tokens. Enforces $O(1)$ constant-time token lookup and returns 401 Unauthorized on missing or invalid tokens.

C. Port 4000 MCP Management Plane

  • Mounts a management MCP server on Port 4000 secured with GATEWAY_ADMIN_TOKEN.

  • Allows AI assistants and operators to dynamically provision, update, deprovision, and diagnose MCP servers over standard MCP tool calls.

  • Full API details in docs/MANAGEMENT_API.md.

D. Pure Config-Driven Plugin Engine

  • Plugins reside under ./src/management/plugins/ and are loaded dynamically based solely on configuration in config.yaml.

  • Employs an Onion Lifecycle Pipeline:

    • Forward execution for onPreProcess and onProcess ([env, docker, cloudflare]).

    • Reverse execution for onPostProcess and onTeardown ([cloudflare, docker, env]).

  • Full plugin developer guide in docs/PLUGINS.md.

3. Configuration (config.yaml)

gateway:
  adminPort: 4000
  adminToken: "${GATEWAY_ADMIN_TOKEN}"
  portRange:
    start: 4000
    end: 4099

  plugins:
    # 1. Environment & Parameterized Secret Generator Plugin
    env:
      enabled: true
      defaultGenerator: "crypto-256"
      envFile: ".env"

    # 2. Docker Container Orchestrator Plugin
    docker:
      enabled: true
      socketPath: "/var/run/docker.sock"
      defaultNetwork: "mcp-network"

    # 3. Cloudflare Zero Trust Ingress & Portal Plugin
    cloudflare:
      enabled: true
      accountId: "${CLOUDFLARE_ACCOUNT_ID}"
      apiToken: "${CLOUDFLARE_API_TOKEN}"
      tunnel:
        id: "${CLOUDFLARE_TUNNEL_ID}"
        hostname: "${CLOUDFLARE_TUNNEL_HOSTNAME}"
        originBaseUrl: "${GATEWAY_ORIGIN_BASE_URL}"
      portal:
        portalId: "${CLOUDFLARE_PORTAL_ID}"

servers:
  # Infrastructure Fleet (Centralized Ports 4001 - 4006)
  gh:
    type: http
    name: "github-mcp-server"
    port: 4001
    targetUrl: "http://github-mcp-backend:8082"
    wrappers:
      "${GH_MCP_TOKEN}":
        headers:
          Authorization: "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"

  cf:
    type: http
    name: "cloudflare-mcp"
    port: 4002
    targetUrl: "https://mcp.cloudflare.com/mcp"
    wrappers:
      "${CF_MCP_TOKEN}":
        headers:
          Authorization: "Bearer ${CLOUDFLARE_API_TOKEN}"
          X-Auth-Account-Id: "${CLOUDFLARE_ACCOUNT_ID}"

  docker:
    type: http
    name: "docker-mcp"
    port: 4003
    targetUrl: "http://docker-mcp-backend:3008"

  ha:
    type: http
    name: "homeassistant-mcp"
    port: 4004
    targetUrl: "http://homeassistant-mcp-backend:3000"

  proxmox:
    type: http
    name: "proxmox-mcp"
    port: 4005
    targetUrl: "http://proxmox-mcp-backend:3006"

  unifi:
    type: http
    name: "unifi-mcp"
    port: 4006
    targetUrl: "http://unifi-mcp-backend:3005"

4. Documentation Index

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Shared MCP Gateway

    xfn-jjw
    F
    license
    Not graded
    quality
    D
    maintenance
    Aggregates multiple shared MCP servers into a single HTTP gateway, providing a unified, observable, and reusable MCP access layer for multiple AI clients like Codex, OpenCode, and OpenClaw. It centralizes configuration management, logging, health checks, and circuit breaking to simplify multi-client MCP deployments.
    5
    -

  • mcp-uni

    iHeyTang
    A
    license
    Not graded
    quality
    C
    maintenance
    A universal MCP server that acts as a unified gateway for dynamically connecting and managing multiple MCP servers via a single HTTP endpoint.
    7 npm
    6
    MIT

  • OmniMCP Router

    Simonc44
    A
    license
    Not graded
    quality
    A
    maintenance
    A universal MCP gateway that aggregates multiple MCP servers into a single endpoint, providing features like hot-reload, auto-healing, and a hook system for request/response mutation.
    1
    MIT