Model Context Gateway (MCG)

An enterprise C# ASP.NET Core gateway, OAuth 2.0 provider, and routing proxy for the Model Context Protocol (MCP).

Model Context Gateway (MCG) connects your AI assistants (Claude Desktop, Cursor, Cline, Windsurf, Antigravity) to all your tools and data sources through a single secure connection.

📖 Documentation Portal: https://spelech.github.io/model-context-gateway/

---

What is Model Context Gateway?

The Model Context Protocol (MCP) lets AI assistants use external tools and data sources.

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

• Memory Waste: Loading hundreds of tool schemas fills the AI context memory before your conversation begins.
• Higher Costs and Latency: Large prompts increase inference costs and response times.
• Security Risks: API keys and database passwords sit in plain text across local config files.
• Configuration Overhead: You must configure each tool separately in every AI application.

Model Context Gateway (MCG) solves these problems:

• One Connection Endpoint (/sse): Connect your AI assistant to a single gateway URL. MCG routes requests to the correct tool.
• Context Optimization (Meta-Mode): By default, the gateway exposes only two tools: search_tools and execute_tool. The AI searches for tools when needed and executes them on demand. This saves context memory and reduces token costs.
• Central Security: MCG keeps credentials secure on the server with AES-256 encryption. The gateway checks user permissions before tools run.
• Universal Tool Support: Route requests across Docker containers, remote HTTP/SSE services, and local scripts (Node.js, Python) without reconfiguring clients.

---

Key Capabilities

• Admin MCP Control Plane (/admin, /mcg-admin): Control the gateway programmatically through standard MCP tools (manage_servers, manage_appkeys, manage_clients, manage_policies, manage_group_mappings, manage_providers, manage_settings, manage_custom_files, manage_system, test_tool_call). See Admin Guide.
• Autonomous Setup & Administration: Built-in agent skills (mcg-setup and mcg-admin) let AI agents configure servers, secret stores, and access policies automatically. See User Guide.
• Meta-Mode Context Saving: Hides tool schemas during startup to prevent context memory exhaustion and model hallucinations.
• Modern Slash Tool Routing: Use modern slash format ({namespace}/{tool_name}) with backwards-compatible format ({serverId}__{toolName}) and collision checks.
• Dynamic Docker Discovery: Automatically discovers containers labeled mcp.enabled=true through /var/run/docker.sock. See Features Guide.
• Identity and Single Sign-On: Authenticate users through Active Directory (Windows SIDs) or OIDC / Reverse Proxy Headers (Authentik, Keycloak, Authelia). See Authentication Architecture.
• Enterprise Secret Storage: Resolve credentials at runtime from HashiCorp Vault (KV v2), Windows Registry (DPAPI), Environment Variables, RFC 8693 Token Exchange, or Per-User Secret Stores (Database / Vault). See Secret Providers Guide.
• Multi-Database Support: Run on SQLite (WAL), Microsoft SQL Server, or MySQL. See Database Providers Guide and Data Model & ERD.
• PII Sanitization & Audit Logs: Redact tokens and passwords automatically while writing complete audit logs.
• Pre-Configured Docker Image: The ghcr.io/spelech/model-context-gateway:latest-full image includes Node.js, Python 3, uv, and bun pre-installed for local scripts. See Transports Guide.
• Web UI Dashboard: Modern dark-mode web interface with real-time metrics, server health cards, logs, and an interactive test bench.

---

Quickstart: Run in 2 Minutes

Run Model Context Gateway with Docker. The gateway starts with safe default settings:

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

What Happens on First Start

• Master Key: Generates a 256-bit AES key at ./data/.master.key with restricted permissions (chmod 0600).
• Database: Creates and migrates the SQLite database at ./data/mcg.db.
• Local Trust: Grants admin access to local connections (127.0.0.1, ::1) on the Web Dashboard (http://localhost:8080).
• Admin Key: Generates a compact admin key (mcp-adm-...) saved to ./data/.admin.key for remote AI agents.
• Docker Discovery: Automatically connects to any containers labeled mcp.enabled=true.

For homelab instructions, see the Single-User & Home-Lab Setup Guide.

---

Client Integration

1. General Tool Access (Meta-Mode Gateway)

Connect your AI assistant to /sse:

1. Search Tools: The AI calls search_tools with a plain text query (for example: "restart container").
2. Execute Tool: The AI runs the returned tool (for example: docker/restart_container) with execute_tool(name, arguments).

2. Connect Your AI Application

Claude Desktop (claude_desktop_config.json)

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

Cursor (~/.cursor/mcp.json) / Windsurf / Cline (cline_mcp_settings.json)

{
  "mcpServers": {
    "mcg": {
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer mcp-adm-Xk9L2mPq-7vN3wZ8aB1cE4fG9"
      }
    }
  }
}

3. Universal Agent Setup Skill

Install the setup skill in your workspace to let your AI assistant configure the gateway automatically:

mkdir -p .agents/skills/mcg-setup && curl -fsSL https://raw.githubusercontent.com/spelech/model-context-gateway/main/skills/mcg-setup/SKILL.md -o .agents/skills/mcg-setup/SKILL.md

Then tell your agent: "Set up Model Context Gateway for my environment".

---

Authentication Modes

For complete credential flow diagrams, see the Authentication Support Matrix.

1. Standalone Mode (Zero-Config / Personal Network)

• Active: Runs automatically when no external identity provider (Active Directory or OIDC) is configured.
• Local Loopback (127.0.0.1, ::1): Local connections receive administrator access automatically.
• Local Subnets: Configure ADMIN__STANDALONE_ALLOWED_NETWORKS__0="192.168.1.0/24" to trust your home or office network.
• Remote Clients: Requests from outside trusted networks require an AppKey (mcp-adm-... or mcp-usr-...).

2. Enterprise Mode (Active Directory & Single Sign-On)

• Active Directory: Users matching Admin:GroupSid (default: S-1-5-32-544 / Administrators) receive admin rights.
• OIDC & Reverse Proxy: Proxies passing Remote-User and Remote-Groups headers grant access according to group rules.
• Group Mappings: Map external group names to internal roles in the Web Dashboard or database.
• Admin AppKeys: AI agents with admin, all, or * scopes receive full administrative access.

---

Documentation Directory

Guide	Description
Single-User & Home-Lab Setup Guide	Fast setup for personal use, home labs, and local AI clients.
Official User Guide	Web dashboard, server management, AppKeys, and test bench.
Administrator Guide	Server management, 10 Admin MCP tools, RBAC policies, and providers.
Admin MCP Automation Guide	AI agent automation with mcg-admin and configuration playbooks.
Architecture Specification	System components, request flow diagrams, and encryption pipelines.
Container Deployment Guide	Production Docker, Docker Compose, and environment settings.
Operations Runbook	Health checks, database backups, key rotation, and disaster recovery.
Windows & IIS Deployment Guide	Windows Server IIS hosting, Windows services, and DPAPI keys.
MCP Server Auth Cookbook	Setup recipes for Bearer auth, custom headers, Vault, and BYOK.
Canonical Data Model & Database ERD	Complete 12-table entity-relationship diagram and schema details.
Database Providers Guide	SQLite, Microsoft SQL Server, and MySQL database setup.
AppKey Scopes & Authorization Guide	Scope rules (*, category:*, server:*, tool:*) and role checks.
Secret Providers Guide	HashiCorp Vault, Windows DPAPI, and AES master key lifecycle.
Downstream Transports Guide	SSE, HTTP, and STDIO local subprocess security and isolation.
Product Evaluation Guide	Context window reduction, token cost savings, and comparisons.
Troubleshooting & RCA Guide	Solutions for session timeouts, cache sync, and backend errors.
Enterprise AD, Vault & Auth Architecture	Enterprise AD, Vault topology, and downstream auth matrix architecture.
Active Directory & RBAC Guide	Inbound AD Kerberos/LDAPS, tokenGroups recursive resolution, and multi-level RBAC.
OIDC & SSO Reverse Proxy Guide	External JWT validation, header SSO, and downstream token exchange.
Downstream Auth & Delegation Guide	Six credential delegation patterns, RLS identity forwarding, and mixing guardrails.

---

Release Changelog

For complete release history and version logs, see CHANGELOG.md.

Version	Release Date	Summary of Key Changes
v5.20.1	2026-09-30	refactor(testbench): Remove Pre-fill Example Button and Streamline Dynamic Argument Handling. Removed the legacy Pre-fill Example button and unused bulk argument modification plumbing from the Test Bench tool tester card, eliminating brittle and unhelpful parameter mocks while preserving interactive form validation and tool execution coverage.
v5.20.0	2026-09-30	feat(auth,ui,docs,ci): AppKey & OAuth Client Last-Used Tracking, Safe Secret Rotation Workflow, Multi-Client Config Generator, VitePress Documentation Architecture Overhaul, and 30-Day Dependabot Stability Cooldown. Implemented LastUsedAt audit tracking for AppKeys and OAuth clients across SQLite, MySQL, and MSSQL with an in-memory 60-second sliding debounce ActivityTracker; added atomic credential rotation endpoints (POST /api/appkeys/{id}/rotate, POST /api/clients/{id}/rotate-secret) returning plaintext keys once with SHA-256 hashing at rest; built two-stage AppKeyRotateModal with backdrop click-away protection and multi-client configuration generator (Claude Desktop, Cursor, Windsurf, generic JSON); overhauled VitePress documentation architecture with Diátaxis decomposition, path-scoped multi-sidebars, purged legacy ASCII art to responsive Mermaid diagrams, modernized typography rhythm, and link integrity CI quality gates; updated GitHub Actions to v7/v5; and configured a 30-day stability cooldown across all Dependabot ecosystems (AUTH-118 through AUTH-123, UI-135 through UI-137).
v5.19.1	2026-09-29	docs(slack): Purge Deprecated Wrapper References, Renumber Documentation Sections, and Refresh Wiki. Streamlined documentation for Slack Native Direct MCP (https://mcp.slack.com/mcp) and the Hybrid Egress Delegation Model; eliminated legacy self-hosted Node.js wrapper references across repository and wiki; updated release assets; and pinned container image tags.
v5.19.0	2026-09-29	feat(slack,oauth,ui): Slack Direct Native MCP Server Integration, 3LO OAuth Egress UI, and Hybrid Token Delegation Model. Added native integration with Slack's cloud MCP server (https://mcp.slack.com/mcp) over streamable HTTP; implemented Hybrid Egress fallback enabling autonomous background daemons (e.g. OpenClaw) to authenticate via static User OAuth tokens (xoxp-...) while allowing interactive users to authorize individually via 3-legged OAuth (3LO); relocated injected trace telemetry into params._meta to satisfy TypeScript SDK Zod strict() schema validation; added 3LO user delegation toggle and configuration fields to ServerModal UI; exposed OAuth properties in Admin MCP manage_servers tooling; added Slack OAuth callback handling for user_scope and non-expiring credentials; and resolved ESLint prefer-const rules.
v5.18.0	2026-09-27	feat(core,ui,e2e): Comprehensive E2E Real Wiring Overhaul, Cold-Start Dynamic Delimiter Routing, Full data-testid UI Instrumentation, and Deterministic E2E Test Suite. Added on-demand delimiter-tolerant (/, :, __) routing across PromptRoutingManager and ResourceRoutingManager allowing connected agents to retrieve prompts and read un-virtualized mcp:// resources without prior list handshakes; safely returned 404 for missing/disabled servers in CapabilityEndpoints testbench APIs; resolved runtime crashes in AccessControlTab with defensive array handling; instrumented all frontend components with standard data-testid attributes; created in-memory stateful mockApi.ts fixture eliminating 502 proxy errors during isolated E2E testing; eliminated all conditional skips and brittle locators in Playwright test suites (64/64 tests passing 100% across all 20 spec files); upgraded mock-mcp-server in docker-compose.test.yml to full Model Context Protocol parity; and achieved 1,209 total passing automated tests with zero requirements catalog drift (MCP-36, MCP-37, MCP-38, MCP-39, UI-133, UI-134, TRANS-01, TRANS-02, SEC-01, AUTH-05).

---

Code Coverage & Quality Gates

Our core modules maintain high code coverage and automated CI quality gates on pull requests and pushes to main. For the complete breakdown and documentation, see:

• Software Requirements Specification & Test Verification Catalog
• Test Catalog Developer & Annotation Guide
• CI Quality Gates & Security Scanning Guide
• Detailed Code Coverage Report

Module	Line Coverage	Branch Coverage	Status
Core Session	92.4%	88.1%	Passing
Routing Engine	89.7%	85.3%	Passing
Controllers	94.2%	91.0%	Passing
Security & Providers	98.5%	95.8%	Passing
CI Quality Gates	100%	100%	Passing

---

Contributor & Developer Guide

For complete developer onboarding, environment setup, testing protocols, and release verification, see Developer Guide.

Quick Quality & Release Verification

Run the unified verification engine locally before creating pull requests:

./scripts/verify-release.sh

C# Backend (Roslyn & .NET Analyzers)

• EditorConfig: Supported globally across C#, TSX, JSON, and YAML. Indentation is 4 spaces for C# and 2 spaces for web files.
• Analysis Policy: Rules are configured via Directory.Build.props at the workspace root, applying implicit usings, nullable context, deterministic builds, and latest-recommended Roslyn analyzers.
• Verification Command:

  dotnet format ModelContextGateway.slnx --verify-no-changes

TypeScript / React Frontend (ESLint Flat Config)

• ESLint v10: Managed via flat configuration (frontend/eslint.config.js) supporting React 19, TypeScript-ESLint, and React Hooks/Refresh checks.
• Verification Command:

  cd frontend
  npm run lint