72020b1901
Implements the walking skeleton from the roadmap: agents connect to one HTTP
endpoint and Nexus aggregates upstream MCP servers behind it with namespaced
tools. Written in Go (single static binary), no external services required.
What works end-to-end (verified live + hermetic e2e tests):
- MCP protocol layer: JSON-RPC 2.0 + initialize/tools.list/tools.call
(internal/mcp), with stdio (subprocess) and Streamable HTTP client
transports, and a reusable stream transport for in-process wiring.
- Router + Dynamic Tool Registry: connects/initializes upstreams in parallel,
loads tools, namespaces them as {namespace}.{tool}, dispatches tools/call to
the owning upstream; refreshes on list_changed. A failed upstream stays
not-ready without taking down the gateway (data plane stays up).
- Gateway: single MCP endpoint (POST /mcp) that is an MCP server to agents,
plus /healthz and a minimal /metrics exposition.
- CLI (cmd/nexus): `serve`, `connect` (stdio<->HTTP bridge for local agents),
`demo-mcp` (built-in zero-dep demo server: echo/add/now), `version`.
- Config: declarative YAML with env expansion + validation.
- Store: persistence interfaces + in-memory impl (SQLite lands later).
Foundations for later phases: domain types (ARCHITECTURE §7), two-plane
split, event-driven refresh seam.
Tooling: Makefile (build/test/vet/fmt with version ldflags), config.example
.yaml. GOPATH moved to /go so it doesn't collide with the module root at /root;
.gitignore whitelist extended to track Go sources while ignoring build output.
Tests: unit (registry/namespacing) + full e2e (client -> demo server over
pipes -> router -> HTTP gateway: initialize, aggregated tools/list, tool-call
routing, unknown-tool error). go vet + gofmt clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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).