drjones/mcp-gateway-nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: initial architecture and design for MCP Nexus

Browse Source 
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>
This commit is contained in:
drjones
2026-07-07 04:38:27 +00:00
commit 8d3ffef920
24 changed files with 3000 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
README.md Normal file
View File

@@ -0,0 +1,100 @@
<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).