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>
101 lines
5.1 KiB
Markdown
101 lines
5.1 KiB
Markdown
<h1 align="center">MCP Nexus</h1>
|
||
|
||
<p align="center"><b>The control plane for MCP. One endpoint. Every tool. Zero manual config.</b></p>
|
||
|
||
<p align="center">
|
||
<i>Kubernetes for MCP — discovery, install, routing, auth, and healing for every MCP server on your network.</i>
|
||
</p>
|
||
|
||
---
|
||
|
||
> **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).
|