The control plane for MCP. One endpoint. Every tool. Zero manual config.
Kubernetes for MCP — discovery, install, routing, auth, and healing for every MCP server on your network.
--- > **Status: design phase.** This repository currently contains the architecture and design docs. > No runnable code yet. See the [Roadmap](./docs/ROADMAP.md) for the delivery plan and > [Architecture](./docs/ARCHITECTURE.md) for the full design. ## The problem Every AI agent (Claude, Cursor, VSCode, Goose, OpenWebUI, Aider, …) has to be told about every MCP server individually — install it, configure it, hold its secrets, keep it updated, wire it into each agent's config. Multiply that by every agent × every service on a homelab or in an enterprise and it collapses under its own weight. ## The idea Run **one** thing. Agents connect to a single endpoint: ``` https://mcp.company.lan ``` Behind that endpoint, **MCP Nexus**: - **Discovers** the services on your network (Home Assistant, Proxmox, Postgres, Ollama, GitHub, UniFi, …). - **Looks up** the right MCP server for each in a package registry. - **Installs** it as a sandboxed container and **configures** it automatically. - **Aggregates** every MCP server behind one endpoint with **namespaced** tools (`homeassistant.turn_on`, `postgres.query`, `github.create_issue`). - **Secures** access with auth + RBAC, so each agent sees only the tools it's allowed to. - **Heals** unhealthy servers and **updates** them, with rollback. > Think of it like plugging a USB device into a modern OS: it's detected, the right driver is installed, and it just works — but for every AI tool and service across your infrastructure. ## How it works (30-second version) MCP Nexus is a **reconciler** — like Kubernetes, but for MCP servers. It continuously drives *what's actually running* toward *what should be running* given the services it discovers and the recipes/policies you set. ``` Discovery ─▶ Registry/Recipes ─▶ Installer ─▶ Runtime ─▶ Inventory │ Agents ─▶ Gateway ─▶ Auth/RBAC ─▶ Router ─▶ upstream MCP servers ─▶ your services ``` Full picture: **[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)**. ## Design tenets 1. One endpoint, unlimited agents. 2. Reconcile, don't script. 3. Everything is a plugin. 4. Single static binary first (Go); Postgres/K8s optional for scale-out. 5. Secure by default — sandboxed, least-privilege, audited, secrets never leak to agents. 6. Discovery is probabilistic — every result carries a confidence score. ## Tech stack - **Backend / control plane:** Go (single static binary, embedded SQLite, embedded dashboard). - **Protocol:** MCP over JSON-RPC 2.0 (Streamable HTTP + stdio bridge). - **Runtime:** Docker first; containerd / Kubernetes adapters planned. - **Dashboard:** React, embedded in the binary. - **Observability:** Prometheus metrics + shipped Grafana dashboards. ## Modules The system is 20 modules, each with its own design doc in [`docs/modules/`](./docs/modules/): | Control plane | Data plane | Cross-cutting | |---|---|---| | [Discovery Engine](./docs/modules/01-discovery-engine.md) | [Gateway](./docs/modules/04-gateway.md) | [Secrets Manager](./docs/modules/07-secrets-manager.md) | | [Package Registry](./docs/modules/02-package-registry.md) | [Dynamic Tool Registry](./docs/modules/05-dynamic-tool-registry.md) | [Plugin System](./docs/modules/11-plugin-system.md) | | [Auto Installer](./docs/modules/03-auto-installer.md) | [Authentication](./docs/modules/06-authentication.md) | [Notifications](./docs/modules/13-notifications.md) | | [Health Monitoring](./docs/modules/09-health-monitoring.md) | [RBAC](./docs/modules/08-rbac.md) | [Service Graph](./docs/modules/17-service-graph.md) | | [Update Manager](./docs/modules/10-update-manager.md) | [Web Dashboard](./docs/modules/12-web-dashboard.md) | [Metrics](./docs/modules/18-metrics.md) | | [Smart Recipes](./docs/modules/15-smart-recipes.md) | [AI Agent Profiles](./docs/modules/14-agent-profiles.md) | [Security](./docs/modules/19-security.md) | | [Infrastructure Discovery](./docs/modules/16-infrastructure-discovery.md) | | [Future Vision](./docs/modules/20-future-vision.md) | ## Roadmap at a glance | Phase | Goal | |---|---| | **0 — Foundations** | Repo, domain types, storage, config, event bus. | | **1 — Walking skeleton** | Gateway aggregates a manually-registered MCP server behind one endpoint. | | **2 — Discover → install** | Discovery + registry + recipes + installer close the reconcile loop. | | **3 — Secure** | Auth, RBAC, secrets, per-agent tool scoping. | | **4 — Operate** | Health, updates, metrics, notifications, dashboard. | | **5 — Extend & scale** | Plugin system, service graph, K8s runtime, HA. | Details: **[docs/ROADMAP.md](./docs/ROADMAP.md)**. ## Contributing Design-phase feedback is the most valuable contribution right now — open an issue on the [design docs](./docs/). Coding conventions and a `CONTRIBUTING.md` will land with Phase 0. ## License TBD (intended to be a permissive open-source license — see roadmap).