# 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`).

```mermaid
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
```

---

## 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`**](file:///Users/craigdean/Repos/mcp-gateway/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`**](file:///Users/craigdean/Repos/mcp-gateway/docs/PLUGINS.md).

---

## 3. Configuration (`config.yaml`)

```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

* 📘 [**Management API Reference (`docs/MANAGEMENT_API.md`)**](file:///Users/craigdean/Repos/mcp-gateway/docs/MANAGEMENT_API.md): Comprehensive schema and documentation for Port 4000 management tools (`provision_mcp`, `update_mcp`, `deprovision_mcp`, `list_mcps`, `get_mcp_diagnostics`).
* 🧩 [**Plugin Developer Guide (`docs/PLUGINS.md`)**](file:///Users/craigdean/Repos/mcp-gateway/docs/PLUGINS.md): Architectural guide to the 3-stage onion lifecycle, directory conventions, and parameterized secret generators (`crypto`, `password`, `uuid`).
* 🏛️ [**Domain Model & Terminology (`CONTEXT.md`)**](file:///Users/craigdean/Repos/mcp-gateway/CONTEXT.md): Ubiquitous language, bounded contexts, and system invariants.
* 🌐 [**Infrastructure Overview (`universal-skills/docs/infrastructure/OVERVIEW.md`)**](file:///Users/craigdean/Repos/universal-skills/docs/infrastructure/OVERVIEW.md): Live-verified hardware topology, port allocation tables, and network maps.