Skip to content

features-guide.md

Latest commit

 

History

History
361 lines (289 loc) · 19 KB

features-guide.md

File metadata and controls

361 lines (289 loc) · 19 KB
Raw

MCP Router Features Guide

This guide details the features of the MCP Router.

🖥️ 1. Dynamic Server Management

The MCP Router supports four methods to manage backend Model Context Protocol (MCP) servers:

Method A: Web UI Dashboard (Recommended)

Manage servers dynamically without restarting the gateway:

  1. Open the router dashboard in a browser.
  2. Click + Add Server (top right).
  3. Complete the Add MCP Server modal:
    • Display Name: User-friendly label (e.g., Home Assistant).
    • URL: Backend SSE endpoint or HTTP server (e.g., http://ha-mcp:8086/mcp).
    • Transport Type: Select sse (stateful) or http (stateless).
    • Category: Classify the server (e.g., homecontrol, infrastructure, development).
    • API Token/Key: Downstream credentials.
    • Secret Provider: Secret retrieval method (None, Vault, WindowsRegistry, or Environment). See Pluggable Secret Retrievers.
  4. Click Save Server. The router registers the server and initializes connections.

Add MCP Server Modal

Method B: Static JSON Seeding (custom_servers.json)

For declarative configurations:

  1. Create custom_servers.json in the /app/data/ directory.
  2. Use this structure: 
    [
  {
    "id": "my-mcp-server",
    "displayName": "My Custom Server",
    "url": "http://10.0.0.15:3000/sse",
    "type": "sse",
    "category": "infrastructure",
    "enabled": true,
    "hidden": false,
    "apiKey": "optional-bearer-or-api-key",
    "headersJson": "{\"Custom-Header-Name\": \"Header-Value\"}"
  }
]
  3. The gateway processes matching entries in the database during startup.

Method C: Environment Seed Migration

The gateway auto-seeds common services on first run if environment variables exist (e.g., HOMEASSISTANT_TOKEN, PLEX_TOKEN, SEERR_API_KEY). Refer to Program.cs.

Method D: Dynamic Docker Label Auto-Discovery (mcp.* labels)

If the router accesses the Docker daemon (/var/run/docker.sock), it dynamically registers backend containers labeled mcp.enabled=true.

services:
  my-service-mcp:
    image: ghcr.io/org/my-service-mcp:latest
    container_name: my-service-mcp
    restart: unless-stopped
    networks:
      - net_mcp
    labels:
      - mcp.enabled=true
      - mcp.id=myservice
      - mcp.displayName=My Custom Service
      - mcp.port=8080
      - mcp.type=sse
      - mcp.path=/sse
      - mcp.categories=infrastructure,custom

Supported Docker Labels

Label Required Default Description
mcp.enabled Yes false Enables router auto-discovery. Must be "true".
mcp.id Yes — Unique server identifier (e.g., /myservice).
mcp.port Yes — Internal container port (e.g., 8080, 3000).
mcp.displayName No Value of mcp.id Friendly name for dashboard and tools.
mcp.type No sse Transport type (sse, http, or stdio).
mcp.path No /sse (or /mcp) Message dispatch path.
mcp.categories No general Comma-separated categories for RBAC.
mcp.authType No none Authentication header format (bearer, x-api-key, custom-header).
mcp.secretProvider No none Secret retriever backend (vault, env, none).
mcp.secretKey No — Vault path or environment variable for the API key.

📡 2. Routing Modes

Connect clients via these SSE endpoints:

Route Path Mode Description
/sse or /sse?meta=true Meta-Mode (Default) Hides backend tools during bootstrap; exposes only search_tools and execute_tool. Conserves context window.
/sse?meta=false Full-List Mode Exposes all underlying tools from all connected servers.
/{targetServerId} Target-Specific Proxying Proxies connections directly to the specified target server (e.g., /docker or /ha).
/admin or /router-admin Admin MCP Server Virtual in-process control plane providing 10 consolidated entity tools for autonomous agents to manage router state.

For transport protocol comparisons (sse, http, stdio), concurrency, security policies, and error recovery, see Transport Capability & Configuration Guide.

Gateway Client Setup Examples (/sse)

Claude Desktop Configuration (config.json)

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

Antigravity CLI Configuration (.gemini/settings.json)

{
  "mcpServers": {
    "mcp-router": {
      "url": "http://localhost:8026/sse",
      "type": "sse",
      "trust": true,
      "serverUrl": "http://localhost:8026/sse"
    }
  }
}

🤖 3. Admin MCP Server & Autonomous Agent Administration

The Admin MCP Server (/admin, /admin/sse, /router-admin) is an in-process virtual MCP server exposing 10 consolidated tools enabling autonomous AI agents (Claude Desktop, Cursor, Cline, Windsurf, Antigravity) to configure and administer the entire gateway programmatically.

Consolidated Admin Tools Reference

Tool Name Actions Description Key Parameters
manage_servers list, get, create, update, delete, toggle, reconnect, reconnect_all Manage backend MCP server registrations, URLs, transports, categories, and secret providers. action, id, name, url, type, category, enabled, secret_provider, secret_key
manage_appkeys list, get_limits, create, revoke Issue and revoke API AppKeys, enforce key quotas, expiration, and configure capability scopes. action, name, scopes, expires_in_days, prefix
manage_clients list, register, delete Manage dynamic OAuth 2.0 client registrations. action, client_id, client_name, redirect_uris, grant_types, scopes
manage_policies list, save, delete Manage role-based access control (RBAC) authorization policies across servers and categories. action, policy_id, role_name, server_id, category, allowed, priority
manage_group_mappings list, save, delete Map external Active Directory SIDs or OIDC SSO groups to internal security roles. action, id, source_type, external_identifier, role_name, priority
manage_providers list, save_secret, test_vault, save_auth, test_ldap Configure and verify HashiCorp Vault, Windows Registry DPAPI, Env, Active Directory LDAP, and OIDC providers. action, provider_type, vault_address, vault_token, ldap_server, bind_dn
manage_settings get, update Update dashboard UI branding (title, icon, accents) and semantic vector embedding providers/models. action, dashboard_title, dashboard_icon, embedding_provider, embedding_model
manage_custom_files list, get, save, delete Manage declarative prompt templates and resource files in persistent storage (/app/data/). action, file_type (prompts or resources), filename, content
manage_system diagnostics, get_logs, clear_logs, query_audit Retrieve server diagnostics, inspect/clear in-memory gateway logs, and query persistent audit log entries. action, limit, level, category, source_user, start_date, end_date
test_tool_call execute Execute and test capabilities against downstream MCP servers via the testbench engine. action, server_id, tool_name, arguments

Admin MCP Server Client Setup Examples

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"
      }
    }
  }
}

Antigravity CLI (.gemini/settings.json)

{
  "mcpServers": {
    "mcp-router-admin": {
      "url": "http://localhost:8026/admin",
      "type": "sse",
      "trust": true,
      "serverUrl": "http://localhost:8026/admin"
    }
  }
}

🔍 4. Semantic Search

In Meta-Mode, clients must semantically search for tools before execution.

Search Flow:

  1. Tool Inquiry: Client calls search_tools(query: "restart actual budget container").
  2. Hybrid Scoring Engine:
    • Computes semantic similarity of tools using a Local ONNX model (all-MiniLM-L6-v2) or LiteLLM/OpenAI APIs.
    • Applies Keyword Boosting (exact phrase match: +2.0 weight; individual words: +1.0/+0.5 weight).
  3. Execution Routing: Client executes returned namespaced tools (e.g., docker__restart_container) via execute_tool.

Embeddings Configuration:

Configure via the Settings panel:

  • Local ONNX (In-Process): Offline execution via Microsoft.ML.OnnxRuntime. Downloads weights on first run to /app/data/.
  • OpenAI API / LiteLLM Provider: Uses remote models. Credentials are encrypted in the database via SQLite SQLCipher.

🔐 5. Authentication, Group Mapping & Unified MCP Capability Authorization

The MCP Router implements a Unified Authorization Pipeline across MCP capabilities:

  • Tools: tools/list, tools/call
  • Prompts: prompts/list, prompts/get
  • Resources: resources/list, resources/read, resources/templates/list
  • Completions: completion/complete

All requests undergo this pipeline:

  1. AppKey Scope Validation: Validates scopes (*, all, server:{id}, tool:{id}, prompt:{id}, resource:{id}, resource_template:{id}, completion:{id}).
  2. Admin SID Bypass: Checks caller SIDs against Admin:GroupSid (e.g., S-1-5-32-544).
  3. Database Access Policies: Evaluates allows and denies in AccessPolicies and sp_EvaluateUserAccess against mapped groups/SIDs.
  4. Discovery Filtering: Automatically omits unauthorized items from list endpoints.
  5. Fail-Closed Default: Unknown capabilities or targets return audited 403 errors without data leakage.

Identity Providers

  • Active Directory (Kerberos/NTLM): Resolves caller identities via AD SIDs (WindowsIdentity).
  • OIDC Header Proxy: Extracts SSO headers (e.g., Remote-User, Remote-Groups) from reverse proxies.

Group & SID Mapping Policy

External groups map to internal groups via the GroupMappings table (Settings -> Identity & Auth):

  1. Create Mapping: Map an AD SID or OIDC group to an internal security group (admin, operator, readonly).
  2. Evaluate Access: Capability invocation triggers access evaluation against the user's mapped groups.

Standalone Network & Hybrid Authorization (AdminPolicy)

The router supports a hybrid administrative security model:

  1. Enterprise Mode (with Active Directory / OIDC):
    • Evaluates caller groups against Admin:GroupSid (e.g. S-1-5-32-544), Admin:Groups (e.g. ["full_admin", "Administrator"]), or dynamic GroupMappings.
    • Admin AppKeys with all or admin scopes owned by an administrator are authorized as Administrator.
  2. Standalone Mode (No External IDP Configured):
    • When no external IDP is active, administrative endpoints (/admin, /api/servers, etc.) permit requests originating from configured networks (Admin:StandaloneAllowedNetworks).
    • Default allowed networks: Loopback (127.0.0.1, ::1).
    • Configurable in appsettings.json or environment variables for LAN subnets (e.g., 10.0.0.0/8, 192.168.1.0/24) or 0.0.0.0/0 for centralized self-hosted setups: 
      {
  "Admin": {
    "StandaloneAllowedNetworks": [
      "127.0.0.1",
      "::1",
      "192.168.1.0/24"
    ]
  }
}
      Or environment variables: ADMIN__STANDALONE_ALLOWED_NETWORKS__0="127.0.0.1" ADMIN__STANDALONE_ALLOWED_NETWORKS__1="192.168.1.0/24"
    • Callers from non-whitelisted remote networks must present an AppKey with administrative credentials.

AppKey Credentials & Category-Scoped Authorization

The router issues fine-grained AppKeys and Client credentials:

  • Scope Granularity:
    • all / * / mcp_client: Full access to all backend servers.
    • server:<serverId> / <serverId>: Full access to a specific backend.
    • category:<name> / group:<name>: Dynamic access to capabilities of all servers in the specified category.
    • tool:<name>, prompt:<name>, resource:<uri>: Pinpoint access to specific capabilities.
  • Dynamic Membership: Category scopes evaluate server memberships in real time. Changes to server categories apply instantly.
  • Creation Validation: Category scopes are validated against registered categories during credential creation. Unknown categories yield a 400 Bad Request unless admin-provisioned.

For detailed rules and pipelines, see the AppKey Scopes & Authorization Guide.

CORS & Cross-Origin Security Configuration

By default, the gateway restricts CORS to local development origins (http://localhost:3000, http://localhost:5000, https://localhost:5001).

For production, configure allowed origins via the CORS_ALLOWED_ORIGINS (or AllowedOrigins) environment variable/setting:

  • CORS_ALLOWED_ORIGINS: Delimited list of allowed URLs (e.g., https://my-mcp-dashboard.internal, https://cursor-plugin.internal).

🔑 6. Pluggable Secret Retrievers

The router dynamically fetches downstream API keys and passwords via pluggable retrievers to prevent plaintext storage in the database.

The CompositeSecretRetriever resolves secrets from:

  1. HashiCorp Vault (KV v2): Fetches secrets via path configurations (e.g., /secret/data/mcp/plex) with AppRole/Token auth and JIT token renewal.
  2. Windows Registry (DPAPI): Retrieves DPAPI-secured strings from registry hives (HKLM).
  3. Environment Variables: Resolves secrets bound as container environment variables (env:MY_SECRET).

Tip

For configuration recipes, AppRole policies, and AES-256-GCM encryption architecture, see docs/secret-providers.md.

Configuration

  1. Register the secret in your store (e.g., environment variable DOCKER_API_KEY=my-secret).
  2. In the Add/Edit Server modal, select Environment for Secret Provider and enter DOCKER_API_KEY under SecretItemKey.
  3. The gateway fetches, decrypts, and caches the token (IMemoryCache with rolling TTL) at execution time.

🧪 7. Developer Test Bench & Diagnostics

The Web Dashboard includes a developer environment to debug and verify setups:

  1. Interactive Form Builder: Generates forms matching the JSON schemas of registered backend tools.
  2. Logs Console: Thread-safe, real-time console displaying JSON-RPC traffic, request IDs, and security classifications.
  3. Search Simulator: Evaluation panel to test queries against the semantic search engine and inspect scores.
  4. Manual Approval Modal: Pauses dangerous tool executions pending administrator approval via the UI.

Test Bench View

🗄️ 8. Database Engine Support & Deployment

For SQLite, MS SQL Server, and MySQL dialect specifications, the 12-table Entity-Relationship Diagram (ERD), stored procedure catalogs, AES-256-GCM envelope encryption, and Docker Compose configurations, see the Database Provider Support & Deployment Matrix.

📋 9. Software Requirements Specification & Automated Test Catalog

For requirements traceability, feature proofs, guardrails, and verified invariants across test suites, reference:

⚡ 10. Universal Setup Skill (mcp-router-setup)

The mcp-router-setup skill adheres to the AgentSkills.io open standard, enabling any AI coding or operations assistant (Antigravity, Claude Code, Cursor, Cline, Windsurf, Copilot CLI) to guide administrators through installing, configuring, and bootstrapping CSharp-MCP-Router in any workspace without cloning or compiling the repository source code.

Zero-Clone Installation

To install the skill into any project or workspace directory:

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

Guided 6-Phase Deployment Workflow

When invoked (e.g. "Set up MCP router for my environment"), the skill executes a structured 6-phase workflow:

  1. Automated Environment Probing: Probes the host OS, Docker daemon socket (/var/run/docker.sock), HashiCorp Vault (VAULT_ADDR), and Active Directory domain context (USERDNSDOMAIN) before asking the user for configuration details.
  2. Hosting Platform Selection: Guides deployment to Docker Container / Docker Compose (Linux, macOS, WSL2, Home-Lab) or Windows Server IIS / Windows Service (with in-process ANCM and DPAPI).
  3. Configuration Paradigm: Explains and helps choose between Environment Variables (immutable, 12-factor .env) and Web UI & Database (dynamic zero-downtime hot reloading & Admin MCP server).
  4. Identity & Network Topology:
    • Standalone / Home-Lab Mode: Configures SQLite database (data/mcp_router.db) and loopback/LAN CIDR subnet authorization (Admin:StandaloneAllowedNetworks).
    • Enterprise Mode: Configures Active Directory LDAP or OIDC forward-auth reverse proxies (Authentik, PocketID, Authelia, Keycloak) with MSSQL, MySQL, or Vault KV v2.
  5. Artifact Generation & Secret Scaffolding:
    • Generates cryptographically secure 256-bit ROUTER_MASTER_KEY (openssl rand -base64 32 or PowerShell crypto RNG).
    • Generates production docker-compose.yml, web.config with unbuffered SSE (responseBufferLimit="0"), .env, and appsettings.Production.json.
  6. Health Verification & Client Integration:
    • Verifies gateway reachability (GET /health and GET /sse).
    • Outputs ready-to-copy client JSON configurations for Claude Desktop, Cursor, Cline, and Windsurf for both the Meta-Mode Gateway (/sse) and Admin MCP Server (/admin).

Bundled Scaffold Templates

The skill includes pre-tested scaffold templates under skills/mcp-router-setup/templates/:

  • docker-compose.yml: Production container deployment with SQLite volume mount and Docker socket pass-through.
  • web.config: IIS ASP.NET Core In-Process module configuration with unbuffered SSE streaming.
  • .env.example: Standardized environment variable template with master key, provider, and network settings.
  • appsettings.Production.json.example: Production ASP.NET Core configuration snippet.