MCP Router Gateway & Semantic Proxy

A C# ASP.NET Core gateway router, OAuth 2.0 provider, and semantic proxy for the Model Context Protocol (MCP).

mcp-router aggregates backend MCP servers (Docker, Plex, Home Assistant, Actual Budget, Excel) and proxies them to clients via a single unified connection.

---

🌟 Key Features

• Admin MCP Server & Control Plane (/admin, /router-admin): In-process virtual MCP server providing 10 consolidated entity management tools (manage_servers, manage_appkeys, manage_clients, manage_policies, manage_group_mappings, manage_providers, manage_settings, manage_custom_files, manage_system, test_tool_call) allowing autonomous AI agents (Claude Desktop, Cursor, Cline, Windsurf) to manage router configuration directly via MCP protocol with hybrid standalone network auth and audit logging.
• Universal Setup Skill (mcp-router-setup): Self-contained AgentSkills.io-compliant skill enabling any AI assistant to bootstrap and configure the router across Docker Compose and Windows IIS with zero source code cloning.
• MCP 2026-07-28 Spec Support: Spec-compliant header annotation; routing is body/path based (Mcp-Method & Mcp-Name) via McpDualSpecMiddleware with legacy JSON body fallback.
• Dynamic Docker Auto-Discovery: Mounts /var/run/docker.sock to automatically discover and register backend MCP containers labeled with mcp.enabled=true, mcp.id, mcp.port, and mcp.categories (see docs/features-guide.md).
• Pluggable Identity Providers: Dual authentication support for Active Directory (Kerberos/NTLM Windows SIDs) and OIDC / Reverse Proxy Headers (Remote-User, Remote-Groups headers from Authentik, Authelia, PocketID, Keycloak, etc.).
• Pluggable Secret Retrievers: Fetch downstream server API keys and tokens dynamically from HashiCorp Vault (KV v2), Windows Registry (DPAPI), or Environment Variables per server (SecretProvider column).
• Windows Enterprise Hosting & Automation: First-class support for IIS In-Process (AspNetCoreModuleV2) with unbuffered SSE streaming (responseBufferLimit="0"), Managed Windows Services with SCM crash auto-recovery, Windows DPAPI registry secrets, and automated PowerShell deployment toolkits. See docs/windows-deployment-and-validation-guide.md.
• Multi-Database & Stored Procedure Engine: Complete stored procedure suites for MS SQL Server (Microsoft.Data.SqlClient), MySQL (MySqlConnector), and SQLite (Microsoft.Data.Sqlite) using Dapper. See docs/database-providers.md.
• Observability & PII Audit Logging: Automatic payload redaction of Bearer tokens, API keys, and passwords (PiiSanitizer) paired with stored procedure audit logging (sp_InsertAuditLog).
• Consolidated Tools Gateway: Merges 300+ tools from dozens of isolated backend servers into a single endpoint.
• Meta-Mode Dynamic Tool Filtering:
  • Defaults to Meta-Mode on the main /sse connection path to prevent context window bloat and tool confusion.
  • Instantly returns only two bootstrap tools: search_tools and execute_tool.
  • Asynchronously warms backend caches in the background using a thread-safe, single-execution initialization lock.
  • Performs semantic scoring and ranking of backend tools on-demand when search_tools is called.
• Dual-Provider Semantic Search:
  • Local ONNX (In-Process): CPU-friendly vector embeddings using a local all-MiniLM-L6-v2 model and Microsoft.ML.Tokenizers (no external APIs). Automatically downloads model/vocab files into persistent volumes.
  • API Provider: OpenAI-compatible embedding calls (LiteLLM, Open WebUI, OpenAI, etc.).
  • Secure DB Storage: Embedding configurations and API keys are stored securely inside the SQLCipher-encrypted SQLite database.
• Developer Test Bench & Dashboard:
  • Interactive UI: Form builder renders interactive input controls directly from tools' JSON schema specs.
  • Logs Console: Styled real-time terminal rendering thread-safe in-memory gateway logs.
  • Search Simulator: Real-time evaluation panel for intent ranking.
  • Provider Management Controls: Interactive UI cards in Settings to toggle and configure Auth and Secret providers.
• Target-Specific Proxying: Exposes separate endpoints (/{targetServerId}) to route directly to specific backends (e.g., /plex, /docker).
• OAuth 2.0 Security & CORS Config: Integrates a lightweight OAuth 2.0 authorization server for secure API access. Leverages strict, configurable CORS protection with CORS_ALLOWED_ORIGINS to prevent cross-origin request hijacking / forgery vulnerabilities.
• Built-in Web Dashboard: A responsive, dark-mode, glassmorphic UI to monitor connected clients, stats, and backend health status.

---

🎯 Evaluation & Product Overview Guide

For details on context window management, STDIO secret security, authorization, and reverse proxy comparisons, see:

• Evaluation & Product Overview Guide

---

🏛️ Comprehensive Architecture & Specification Guide

For architectural specifications, Mermaid sequence diagrams, component models, ERDs, authorization flows, transport lifecycles, and AES-256-GCM encryption pipelines, see:

• Comprehensive Enterprise Architecture Guide
• Executive Architecture Overview

---

📖 Official User Guide & Manual

For UI guides, server registration, secret provider configuration, RBAC, client setup, and test bench operations, see:

• Official User Guide Suite
  • 01. Dashboard & Navigation Interface
  • 02. Server Management & Secret Providers
  • 03. RBAC, Security & Approvals
  • 04. Client Setup & App Key Management
  • 05. Interactive Test Bench
  • 06. System Settings & Vector Embeddings

---

💻 Developer & Operations Guides

For setup, testing, production deployment, database management, observability, and disaster recovery:

• Developer Guide & Local Setup
• Windows Deployment & Validation Guide
• Software Requirements Specification (SRS) & Test Catalog
• Test Catalog & Annotation Developer Guide
• Operations & Production Runbook
• Contributing Guide

---

🚀 Transport Capability & Configuration Guide

For an in-depth breakdown of downstream transports (sse, http/streamable, stdio, target proxying /{targetServerId}), subprocess STDIO security policies, environment variable secret injection, process tree lifecycle management, SSE concurrency/ID isolation, configuration examples, and troubleshooting procedures, see docs/transports.md.

---

🔑 AppKey Scopes & Authorization Guide

For complete scope syntax grammar (*, server:*, category:*, tool:*, prompt:*, resource:*), multi-stage pipeline evaluation rules, the capability authorization matrix, cryptographic token hashing, and least-privilege persona recipes, see the canonical AppKey Scopes & Authorization Guide.

---

🔐 Enterprise Secret Providers & Key Management Guide

For detailed documentation on supported secret providers (HashiCorp Vault KV v2 with JIT renewal, Windows Registry DPAPI, Environment Variables), AES-256-GCM encryption at rest, dynamic runtime reloading, audit safety, and Docker Compose setup snippets, see docs/secret-providers.md.

---

🗄️ Database Provider Support, Data Model & ERD

For complete dialect specifications across SQLite, Microsoft SQL Server, and MySQL, the complete 12-table Canonical Data Model & Database ERD, stored procedure suites (sp_*), AES-256-GCM envelope encryption, and Docker Compose deployment recipes, see:

• Canonical Data Model & Database ERD
• Database Provider Support & Deployment Matrix

---

📡 Features & Usage Guide

For deep technical walkthroughs, setup configuration examples, connection guidelines, secret retrievers, and usage instructions for the Web UI/Test Bench, see docs/features-guide.md.

---

🤖 Client Agent Integration Guidelines

1. General Tool Access (Meta-Mode Gateway)

When using agentic coding assistants connected to the main /sse gateway:

1. Bootstrap Search (Meta-Mode): By default, the gateway hides all underlying tools to prevent context bloat. The agent must first query search_tools with a natural language query describing the desired action (e.g., "restart actual budget container").
2. Namespaced Execution: After search_tools returns matching namespaced tools (e.g. docker__restart_container), the agent must invoke it via execute_tool(name, arguments).
3. Semantic Knowledge Retrieval (notes-rag): AI agents MUST query the notes-rag service first (using the search_notes tool) for system architecture or setup questions before attempting to grep the filesystem.

2. Autonomous Router Administration (Admin MCP Server)

Autonomous agents (Claude Desktop, Cursor, Cline, Windsurf, Antigravity) can directly manage router configuration by connecting to /admin or /router-admin:

Claude Desktop (claude_desktop_config.json)

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

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

{
  "mcpServers": {
    "mcp-router-admin": {
      "url": "http://localhost:8026/admin",
      "headers": {
        "Authorization": "Bearer mcp-admin-key-here"
      }
    }
  }
}

3. Universal Agent Setup Skill (Zero-Clone Bootstrapping)

Equip any AI assistant (Antigravity, Claude Code, Cursor, Cline, Windsurf, Copilot CLI) to install, configure, and bootstrap the router for Docker Compose or Windows Server IIS without cloning or compiling source code:

mkdir -p .agents/skills/mcp-router-setup && curl -fsSL https://raw.githubusercontent.com/spelech/csharp-mcp-router/main/skills/mcp-router-setup/SKILL.md -o .agents/skills/mcp-router-setup/SKILL.md

Once installed, simply prompt your agent: "Set up MCP router for my environment" or "Deploy MCP router on Docker/IIS". The skill automatically:

• Probes host environment capabilities (OS, Docker daemon socket, HashiCorp Vault, Active Directory domain).
• Guides deployment target selection (Docker Compose or Windows IIS).
• Clarifies trade-offs between Environment Variables (.env) vs. Web UI & Database (dynamic hot-reloading).
• Configures network topology (Standalone / Home-Lab with SQLite vs. Enterprise with AD/OIDC + MSSQL/MySQL/Vault).
• Generates cryptographically secure 256-bit ROUTER_MASTER_KEY values and production configuration files (docker-compose.yml, web.config, .env, appsettings.Production.json).
• Verifies gateway health (/health, /sse) and outputs client configuration snippets.

---

🛡️ Authentication Modes & Zero-Configuration Standalone Access

The gateway adapts seamlessly to both personal / standalone home-lab environments and enterprise deployments:

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

• When Active: Whenever no external identity provider (Active Directory LDAP or OIDC Reverse Proxy) is configured.
• Local Loopback (127.0.0.1, ::1): By default, connections originating from localhost/loopback are granted local administrative privileges automatically without requiring an SSO provider or password.
• Private LAN / Docker Subnets (Central Gateway): Configure Admin:StandaloneAllowedNetworks in appsettings.json or environment variables (e.g. ADMIN__STANDALONE_ALLOWED_NETWORKS__0="10.0.0.0/8" or "0.0.0.0/0" for open private LANs) to grant admin access to your local network.
• External Clients: Requests originating from outside the allowed subnets require an Admin AppKey (such as the default CLI key mcp-global-admin-default-cli-key-99 or custom generated keys).

2. Enterprise IDP Mode (Active Directory & OIDC Reverse Proxy)

• Active Directory (Windows Authentication / LDAP): Users whose SID matches Admin:GroupSid (default: S-1-5-32-544 / Local Administrators) or domain admin groups are granted full gateway administration.
• OIDC & Reverse Proxy SSO: Reverse proxies (Authentik, Authelia, PocketID, Keycloak, Traefik, Caddy, Nginx) transmitting Remote-User and Remote-Groups matching Admin:GroupName or Admin:Groups (e.g. full_admin, Administrator) are authorized.
• Dynamic Group Mappings: Map external IdP group names to internal roles via the GroupMappings database table or Web Dashboard.
• Admin AppKeys: Autonomous AI agents presenting an AppKey with admin, all, or * scope are granted the Administrator role across all endpoints.

---

📜 Release Changelog

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

Version	Release Date	Summary of Key Changes
v4.20.0	2026-08-20	feat(auth): User-Specific MCP Server Authentication via UserProvided secret provider and self-service portal
v4.19.1	2026-08-18	feat(skills): introduce universal mcp-router-setup agentic skill, bundled scaffold templates for Docker & IIS, and zero-clone setup workflow
v4.19.0	2026-08-18	feat(admin): implement in-process virtual Admin MCP Server (/admin, /router-admin), 10 consolidated management tools, and standalone hybrid network auth
v4.18.2	2026-08-18	refactor(reqs): normalize requirement taxonomy IDs across test suites and regenerate living SRS catalog
v4.18.1	2026-08-18	fix(ci): fix frontend test assertions, preserve provider display names, and update test catalog

---

🧪 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
v4.20.0	2026-08-20	feat(auth): User-Specific MCP Server Authentication via UserProvided secret provider and self-service portal
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 docs/developer-guide.md.

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 McpRouter.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