Model Context Gateway (MCG)

      

---

Model Context Gateway (MCG) is a high-performance C# ASP.NET Core gateway, OAuth 2.0 provider, and semantic proxy for the Model Context Protocol (MCP).

It aggregates hundreds of tools from isolated backend servers (Docker, Home Assistant, Plex, Actual Budget, Excel, custom APIs, STDIO subprocesses) and proxies them to AI clients (Claude Desktop, Cursor, Cline, Windsurf, Antigravity) via a single unified connection.

---

⚡ Core Architecture Highlights

flowchart LR
    subgraph Clients["AI Clients & IDEs"]
        Claude["Claude Desktop"]
        Cursor["Cursor / Windsurf"]
        Agents["Autonomous Agents"]
    end

    subgraph Gateway["Model Context Gateway (MCG)"]
        Auth["OAuth / Reverse Proxy Auth / AppKey"]
        MetaMode["Meta-Mode Router\n(search_tools / execute_tool)"]
        Vector["Semantic Vector Search\n(Local ONNX / OpenAI)"]
        AdminMCP["Admin MCP Server\n(/admin, /mcg-admin)"]
        Secrets["Secret Providers\n(Vault / DPAPI / AES)"]
    end

    subgraph Backends["Downstream MCP Servers"]
        DockerSrv["Docker Containers\n(Auto-Discovery)"]
        SSESrv["Remote SSE / HTTP Servers"]
        StdioSrv["Subprocess STDIO\n(Node / Python / uv / bun)"]
    end

    Clients -->|Bearer / SSE| Auth
    Auth --> MetaMode
    Auth --> AdminMCP
    MetaMode <--> Vector
    MetaMode --> Secrets
    Secrets --> DockerSrv
    Secrets --> SSESrv
    Secrets --> StdioSrv

• 🧠 Meta-Mode Dynamic Tool Filtering: Exposes only search_tools and execute_tool on /sse by default, eliminating context window bloat in LLMs while dynamically discovering and routing across hundreds of backend tools on demand.
• 🛡️ Multi-Tenant Auth & Zero-Config Standalone: Native Active Directory LDAP / Kerberos, OIDC reverse proxy headers (Remote-User, Remote-Groups from Authentik, Authelia, Keycloak), scoped AppKeys (mcp-adm-, mcp-usr-, mcp-srv-), and trusted local loopback for personal home-labs.
• 🤖 In-Process Admin MCP Control Plane (/admin, /mcg-admin): Autonomous AI agents can manage providers, servers, RBAC policies, group mappings, vector search, and personal AppKeys via standard MCP tool calls without manual UI operations.
• 🔍 Dual-Provider Semantic Vector Search: Local in-process CPU vector embeddings (all-MiniLM-L6-v2 via Microsoft.ML.Tokenizers) or remote OpenAI-compatible API providers stored securely in SQLCipher/AES encrypted databases.
• 🔐 Enterprise Secrets & Key Lifecycle: Just-in-time secret retrieval from HashiCorp Vault (KV v2), Windows Registry (DPAPI), or Environment Variables with AES-256-GCM envelope encryption and dynamic master key rotation.
• 🐳 Docker Label Auto-Discovery: Mounts /var/run/docker.sock to dynamically discover and register containers with mcp.enabled=true labels with zero manual registration.
• 🗄️ Multi-Database Support: First-class stored procedure suites across SQLite, Microsoft SQL Server, and MySQL via Dapper.

---

🧭 Documentation Portal Navigation

• Deployment & Getting Started

  ---

  Blank-slate Docker, Docker Compose, Windows IIS setup, environment variables, master encryption keys, and zero-config deployment.

• Authentication & Identity Architecture

  ---

  Active Directory SIDs, OIDC reverse proxy SSO, standalone loopback trust, AppKey scopes, and token exchange flows.

• Enterprise Administration Guide

  ---

  Operational administration, provider configuration, group mappings, master key rotation, and system management.

• Admin MCP Automation Guide

  ---

  Autonomous agent administration via the mcg-admin skill, control plane tools, and programmatic provisioning.

• Official User Guide Suite

  ---

  Interactive dashboard walkthrough, server registration, RBAC management, client configuration, and test bench usage.

• MCP Server Auth Cookbook

  ---

  Scenario-driven integration recipes for Bearer auth, Custom Headers, Vault, BYOK, Pass-Through, and Identity-Forwarding.

• Comprehensive Architecture

  ---

  Complete enterprise architecture specification, sequence diagrams, component models, and AES-256-GCM encryption pipelines.

• Database Providers & Data Model

  ---

  Canonical 12-table ERD, dialect specifications for SQLite, MSSQL, and MySQL, stored procedures, and migration guide.

• AppKey Scopes & Authorization

  ---

  Scope grammar (*, server:*, category:*, tool:*), evaluation pipeline, least-privilege personas, and token hashing.

• Secret Providers & Key Management

  ---

  HashiCorp Vault KV v2 JIT renewal, Windows DPAPI, Master Key lifecycle, and secure credential storage.

• Downstream Transports Guide

  ---

  SSE, HTTP/streamable, subprocess STDIO security policies, environment secret injection, and process tree isolation.

• SRS & Test Catalog

  ---

  Living Software Requirements Specification, requirement taxonomy (AUTH, MCP, SEC, GUARD), and test verification matrix.

---

⚡ Quickstart: Zero-Config Startup

Run the gateway container with zero required configuration. On first boot, the gateway automatically generates a 256-bit AES Master Key in ./data/.master.key and initializes a secure SQLite database:

Docker CLIDocker Compose

docker run -d \
  --name mcg \
  --restart unless-stopped \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/spelech/model-context-gateway:latest

services:
  mcg:
    image: ghcr.io/spelech/model-context-gateway:latest
    container_name: mcg
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - DB_PROVIDER=sqlite
      - MCG_ADMIN_KEY=mcp-adm-prod-bootstrap-token-99

Live Endpoints

• Web UI Dashboard: http://localhost:8080/
• Health Check: http://localhost:8080/health → {"status":"healthy","service":"ModelContextGateway","version":"5.0.0"}
• Meta-Mode Gateway: http://localhost:8080/sse
• Admin MCP Server: http://localhost:8080/admin/sse (or POST /admin / GET /mcg-admin/sse)
• Direct Backend Proxy: http://localhost:8080/{targetServerId}

---

🤖 Connecting AI Clients

1. Claude Desktop (claude_desktop_config.json)

Meta-Mode Gateway (/sse)Admin Control Plane (/admin)

{
  "mcpServers": {
    "mcg": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/client-sse", "http://localhost:8080/sse"]
    }
  }
}

{
  "mcpServers": {
    "mcg-admin": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/client-sse", "http://localhost:8080/admin"]
    }
  }
}

2. Cursor / Windsurf / Cline (mcp.json / cline_mcp_settings.json)

{
  "mcpServers": {
    "mcg": {
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer mcp-usr-my-developer-token-123"
      }
    }
  }
}

---

🛠️ Verification & Quality Assurance

All features, security guardrails, and authentication flows are enforced by automated test suites:

• xUnit Backend Suite: 670+ integration & unit tests (ModelContextGateway.Tests)
• Vitest Frontend Suite: Component and state store test coverage (frontend/src/test)
• Playwright E2E Suite: End-to-end browser automation (frontend/e2e)
• Living Requirements Matrix: Zero-drift catalog generation via dotnet run --project scripts/CatalogGenerator -- --verify-only (SRS Catalog)