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 Admin Automation Skill (mcp-router-admin): Specialized AgentSkills.io skill enabling AI agents to programmatically provision Auth providers (Authentik, Keycloak, Entra ID, Active Directory LDAPS), Secret stores (Vault KV v2, AES-256-GCM Master Key, DPAPI), RBAC policies, group mappings, embeddings, backend servers, and client keys from a blank slate with zero UI clicking (see docs/admin-mcp-automation-guide.md).
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.
Enterprise Identity Delegation:
- X-Forwarded-User Propagation (Trusted Gateway Pattern): Automatically injects the inbound authenticated user's identity into downstream HTTP/SSE backend requests for seamless Row-Level Security (RLS) enforcement.
- Kerberos / NTLM Impersonation: For native Windows IIS deployments, the router utilizes S4U2Proxy to assume the inbound caller's Active Directory identity when communicating with downstream enterprise endpoints.
- OAuth2 / OIDC On-Behalf-Of: Acts as a Confidential Client to dynamically mint/exchange tokens with identity providers (Azure AD, Okta, Authentik) on behalf of the user.
- Dynamic Auth Pass-Through: Issues dynamic_auth prompts directly to the client (IDE/LLM) when downstream services require interactive challenges.
Batteries-Included Docker: ghcr.io/org/mcp-router:latest-full tag provides pre-installed Node.js, Python 3, uv, and bun environments for natively executing stdio sub-process servers without sidecar networking complexity.
Built-in Web Dashboard: A responsive, dark-mode, glassmorphic UI to monitor connected clients, stats, and backend health status.

⚡ Quickstart: Zero-Config Blank-Slate Deployment

You can spin up CSharp-MCP-Router with zero required environment variables. On first launch, the router automatically generates a 256-bit master key saved to ./data/.master.key and initializes safe defaults:

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

(Alternatively, mount a Docker/Kubernetes file secret with -e ROUTER_MASTER_KEY_FILE=/run/secrets/my_key or pass -e ROUTER_MASTER_KEY="<key>").

Out-of-the-Box Safe Defaults

Auto-Generated Master Key: Automatically created and stored in ./data/.master.key (with chmod 0600) so credentials remain encrypted at rest with zero plaintext env vars.
SQLite Database: Automatically created and migrated at ./data/mcp_router.db.
Standalone Security: Local loopback (127.0.0.1, ::1) is trusted as Administrator for the Web Dashboard (http://localhost:8080).
Pre-Seeded Admin Key: Seeds mcp-global-admin-default-cli-key-99 for remote AI agents and DevOps scripts to automate configuration via the Admin MCP Server (/admin/sse or POST /admin).
Instant Automation: Use the mcp-router-admin skill (.agents/skills/mcp-router-admin/SKILL.md) to autonomously configure Authentik, Keycloak, Entra ID, Active Directory, Vault, embeddings, and backend servers. See docs/deployment-guide.md.

🎯 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:

📖 Official User Guide & Manual

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

Official User Guide Suite

💻 Developer & Operations Guides

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

🚀 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:

📡 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:

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").
Namespaced Execution: After search_tools returns matching namespaced tools (e.g. docker__restart_container), the agent must invoke it via execute_tool(name, arguments).
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

Note: For a detailed breakdown of end-to-end credential passing, Kerberos limitations, and Pass-Through routing constraints, see the Authentication End-to-End Support Matrix.

The router features a hybrid administrative authorization engine supporting both isolated bare-metal developers and massive enterprise Active Directory forests.:

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.34.0`	2026-08-23	feat(skills): introduce universal `mcp-router-admin` automation skill, blank-slate safe defaults documentation, provider scaffolding templates (Authentik, Keycloak, Entra ID, Active Directory LDAPS, Cloudflare, Vault, Embeddings), and comprehensive DevOps automation guide
`v4.33.0`	2026-08-22	feat(testing): integrate playwright-layout-inspector for spatial layout auditing, eliminate background DOM collisions, enhance interactive touch targets and focus rings
`v4.32.0`	2026-08-22	feat(ui): dynamic multi-brand logo resolution (favicons, manifests, meta icons) and centered page layout containerization across all dashboard tabs
`v4.31.0`	2026-08-22	feat(frontend): implement dynamic multi-target client connection guide
`v4.30.0`	2026-08-22	feat(ui): comprehensive aesthetic UI overhaul implementing stark monochrome mode, vibrant neon green/orange dark mode accents, cyan/blue light mode accents, and mobile responsive flex refactoring for toolbar dropdowns and stat grids

🧪 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:

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 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
```

FilesExpand file tree

README.md

Latest commit

History