8d3ffef920
MCP Nexus is a self-hosted control plane for MCP servers — "Kubernetes for
MCP." Agents connect to one endpoint; Nexus discovers services, installs the
right MCP servers, aggregates them behind a namespaced router, secures access
with auth/RBAC, and heals/updates them via a reconcile loop.
This first commit is design-phase only (no runnable code yet):
- README.md project front door + module map
- docs/ARCHITECTURE.md target design: tenets, two-plane split, reconcile
loop, domain types, storage, security, deployment
- docs/ROADMAP.md phased delivery (foundations -> walking skeleton ->
discover+install -> secure -> operate -> extend/scale)
- docs/modules/01-20 one design doc per module, all cross-linked
Backend stack decision: Go (single static binary, embedded SQLite + embedded
React dashboard). Repo initialized in /root with a whitelist .gitignore so
only project files are tracked.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5.1 KiB
MCP Nexus
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 for the delivery plan and Architecture 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.
Design tenets
- One endpoint, unlimited agents.
- Reconcile, don't script.
- Everything is a plugin.
- Single static binary first (Go); Postgres/K8s optional for scale-out.
- Secure by default — sandboxed, least-privilege, audited, secrets never leak to agents.
- 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/:
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.
Contributing
Design-phase feedback is the most valuable contribution right now — open an issue on the design docs. Coding conventions and a CONTRIBUTING.md will land with Phase 0.
License
TBD (intended to be a permissive open-source license — see roadmap).