Model Context GatewayEnterprise MCP Router & Control Plane

What is Model Context Gateway? ​

The Model Context Protocol (MCP) allows AI assistants to run external tools and read data sources.

When you connect an AI assistant directly to many individual tools, you face common operational problems:

• Context Bloat: Loading hundreds of tool schemas consumes AI context memory before your session begins.
• Higher Latency and Token Costs: Massive prompts increase inference costs and response times.
• Security Hazards: API keys and passwords sit in plain text across local client configuration files.
• Multi-User Isolation: Direct connections cannot safely handle per-user authentication (such as Google Home or personal SaaS tokens).

Model Context Gateway (MCG) solves these problems:

• Single Connection Endpoint (/sse): Connect your AI assistant to a single gateway URL. MCG routes requests to the correct backend tool.
• Context Optimization (Meta-Mode): The gateway hides backend tool schemas and exposes only search_tools and execute_tool. The AI finds tools dynamically and invokes them on demand.
• Central Security & Per-User OAuth: Credentials remain secure with AES-256-GCM envelope encryption or HashiCorp Vault. Individual users authenticate safely via 3LO OAuth with automated token refresh.
• Universal Tool Support: Route across Docker containers, remote HTTP/SSE services, and local script subprocesses (Node.js, Python, uv, bun) without client reloads.

Core Architecture ​

Quickstart: Zero-Config Startup ​

Run the gateway container with zero required initial 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 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 Gateway Endpoints ​

• Web UI Dashboard: http://localhost:8080/
• Health Check: http://localhost:8080/health → {"status":"healthy","service":"ModelContextGateway","version":"5.17.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}

Documentation Directory ​

Connecting AI Clients ​

1. Claude Desktop (claude_desktop_config.json) ​

{
  "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 validated across automated test suites:

• xUnit Backend Suite: 878 integration & unit tests (ModelContextGateway.Tests)
• Vitest Frontend Suite: 253 component and state store tests (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)