Model Context Gateway

Appearance

Model Context Gateway (MCG) User Guide ​

Welcome to the Model Context Gateway (MCG) User Guide.

MCG is a high-performance, enterprise-grade Model Context Protocol (MCP) gateway, proxy, and aggregator built with C# and ASP.NET Core. It connects your AI coding assistants, IDEs, and autonomous agent workflows to all your backend tools, databases, and microservices through a single secure, unified endpoint.

What is Model Context Gateway? ​

The Model Context Protocol (MCP) enables Large Language Models (LLMs) and AI agents to interact with external systems—reading files, querying databases, running container commands, and invoking external APIs.

Connecting AI assistants directly to individual MCP servers introduces significant operational challenges:

  • Memory Waste & Context Saturation: Exposing dozens or hundreds of raw tool schemas directly to an LLM consumes massive context window bandwidth before a conversation even begins.
  • Higher Inference Cost & Latency: Injecting large JSON schemas into every prompt increases token consumption and model latency.
  • Security & Credential Sprawl: Hardcoding static API keys into developer desktop configuration files creates credential leaks and bypasses centralized enterprise auditing.
  • Inconsistent Auth & Transport: Tools run across diverse transports (SSE, HTTP, STDIO) with inconsistent authentication, headers, and access policies.

Model Context Gateway (MCG) solves these challenges by acting as a reverse proxy, semantic router, and security gateway between AI clients and backend tools.

Core System Concepts ​

1. MCP Server ​

An MCP server is an application or service providing tools, resources, or prompt templates. MCG supports backend servers running in Docker containers, as local subprocesses (STDIO), or across remote networks via SSE and HTTP.

2. Meta-Mode (/sse) ​

Meta-Mode is MCG's signature context-optimization architecture. Instead of exposing all backend tools at startup:

  • The gateway exposes only two bootstrap tools: search_tools and execute_tool.
  • When an AI client needs a capability, it calls search_tools with natural language intent (e.g. "restart broken proxy container").
  • MCG's semantic vector router ranks and returns only relevant tool schemas.
  • The AI then calls execute_tool with the targeted tool name and arguments.
  • This cuts prompt tokens by up to 95%, prevents model hallucinations, and accelerates response times.

3. AppKey ​

An AppKey is a cryptographically hashed (SHA-256) bearer token used by AI clients to authenticate to the gateway. Keys carry explicit semantic prefixes:

  • mcp-adm-: Administrative keys with full gateway permissions and access to the /admin MCP management server.
  • mcp-usr-: User keys tied to specific user principals and RBAC quotas.
  • mcp-glb-: Global keys for shared applications and system daemons.

4. Transports ​

MCG bridges heterogeneous downstream transport protocols:

  • Server-Sent Events (SSE): Long-lived streaming connection over HTTP for real-time notifications and stateful tools.
  • HTTP JSON-RPC (HTTP / Streamable): Stateless HTTP POST requests for standard microservice endpoints.
  • Local Subprocess (STDIO): Manages local CLI processes (npx, python, binaries), injecting secrets directly into child process environment variables.

5. Role-Based Access Control (RBAC) ​

MCG enforces a 4-stage authorization pipeline (Explicit Deny > Explicit Allow > AppKey Scope > Default Fallback), integrating with Active Directory SIDs, OIDC reverse proxy headers, and granular scope patterns.

6. Tool Routing Conventions ​

MCG supports slash-based tool routing ({namespace}/{tool_name}) alongside backwards-compatible double-underscore syntax ({serverId}__{toolName}). Direct target server routing is available via /{targetServerId} (e.g. /docker, /homeassistant).

7. Encryption & Persistence ​

All tokens, API keys, and provider secrets are encrypted at rest using AES-256-GCM envelope encryption. MCG supports SQLite (WAL mode), Microsoft SQL Server, and MySQL.

System Navigation & Architecture ​

Common Workflows ​

Workflow 1: Connect Your First AI Assistant ​

  1. Open the Web Dashboard at http://localhost:8080.
  2. Navigate to the App Keys & Security tab.
  3. Click + Generate App Key.
  4. Set a key label (e.g., Cursor IDE - MacBook), assign scopes (* or all for full access), and choose an expiration.
  5. Copy the generated secret key (mcp-usr-... or mcp-adm-...). Store it immediately—it is displayed only once.
  6. Configure your AI client using the dedicated client guides:

Workflow 2: Register a Backend MCP Server ​

  1. On the Overview tab, click + Add Server in the top-right toolbar.
  2. Enter the server configuration:
    • Server Identifier: Unique alias (e.g. docker, homeassistant).
    • Display Name: Human-readable name (e.g. Docker Infrastructure Daemon).
    • Transport Type: Select SSE, HTTP, or STDIO.
    • Endpoint / Command: Downstream URL or CLI executable path.
    • Secret Provider: Select None, Environment, Vault, or WindowsRegistry.
  3. Click Save Server. MCG verifies connectivity and discovers all exposed tools, resources, and prompts automatically.

Workflow 3: Test a Tool in the Test Bench ​

  1. Click the Test Bench tab in the top navigation.
  2. Under Tools, select your target server and desired tool from the dropdowns.
  3. Supply required arguments using either the schema-generated form fields or the raw JSON editor.
  4. Click Execute Tool to invoke the tool directly through the gateway.
  5. Review the execution latency, HTTP response status, and JSON output.

Workflow 4: Manage User Quotas & Credentials ​

  1. Click your username badge in the top-right header to review quota allocations:
    • Global Maximum Keys: Server-wide limit.
    • User Maximum Keys: Maximum active keys per user account.
    • Your Active Keys: Count of active AppKeys owned by your account.
  2. Revoke compromised or unused keys instantly from the App Keys & Security table.

User Guide Roadmap ​

SectionTopicDocumentation Link
01. Dashboard & NavigationWeb interface, operational metrics cards, catalog filtering, sorting, and server cards.Dashboard & Navigation
02. Server Management & SecretsRegistering MCP servers (SSE, HTTP, STDIO), credential resolution (Vault, DPAPI, Env), and inspect modal.Server Management
03. RBAC, Security & Policies4-stage authorization pipeline, identity providers (OIDC, AD, AppKey), access policies, and user quotas.RBAC & Policies
04. AppKey Management & ScopesAppKey generation, prefix types (mcp-adm-, mcp-usr-, mcp-glb-), and complete scope grammar.AppKeys & Scopes
05. Client Setup & IntegrationClient connection overview, dynamic configuration card, and client recipes:Client Setup Overview
↳ Cursor IDE.cursor/mcp.json setup for Meta-Mode and target proxy endpoints.Cursor Setup
↳ Claude Desktopclaude_desktop_config.json setup with @modelcontextprotocol/client-sse.Claude Desktop Setup
↳ Cline & VS Codecline_mcp_settings.json configuration for VS Code AI extensions.Cline & VS Code Setup
↳ Antigravity CLIAutonomous agent workflows and CLI commands.Antigravity Setup
06. Interactive Test BenchComprehensive diagnostic subsystem and interactive tools:Test Bench Overview
↳ Tool Execution TesterDynamic schema-driven tool execution tester and JSON editor.Tool Tester
↳ Resources & PromptsReading virtual resources (mcp://...) and evaluating prompt templates.Resources & Prompts
↳ Semantic RouterVector cosine similarity, keyword weighting, and relevance scoring simulation.Semantic Search Simulator
↳ Console & Live LogsDirect JSON-RPC console, SSE streaming, and real-time log terminal.Console & Live Logs
07. Settings & ConfigurationVector search engines (Local ONNX vs OpenAI), secret providers, identity providers, and custom files.System Settings

Released under the Apache 2.0 License.

Copyright © 2026 Steve Pelech. Model Context Gateway (MCG).