AgentNexus

The coordination layer for heterogeneous LLM code agents. Let a backend agent, a frontend agent, and an infra agent — running on different IDEs and different models — stay in sync automatically, with zero hand-written glue.

An MCP server that coordinates AI code agents across service boundaries. (Not affiliated with the MIT Lincoln Laboratory project of the same name.)

[ demo GIF goes here — see TODO above ]

---

The problem

Your product isn't one codebase. It's a backend, a frontend, some infra, a test suite — each with its own repo, stack, and agent. When the backend changes its API, the frontend has to adapt. Today that coordination is done by humans copy-pasting specs into chat, or by hand-written CLAUDE.md / AGENTS.md files that go stale the moment the service changes.

Role-playing multi-agent frameworks (ChatDev, MetaGPT) don't help here: they assume all agents live in one simulated org, one codebase. Real systems are a mesh of independently-owned parts.

What AgentNexus does

AgentNexus coordinates agents at the service boundary — the unit real systems are actually built from. Each boundary registers as a sub-project, publishes versioned Markdown documents (requirements, design, API specs, config), and subscribes to the documents it depends on. When a document changes, subscribers get a diff-aware notification — the exact change plus the full latest content — so an agent can make a targeted edit without a human in the loop.

Backend Agent              AgentNexus               Frontend Agent
  (Claude Code)                                        (Cursor)
      │                        │                          │
      │── POST /api/documents ▶│                          │
      │   (api spec, v5)       │── notification ─────────▶│
      │                        │                          │── get_my_updates_with_context()
      │                        │── diff + full content ──▶│
      │                        │                          │── applies targeted code change
      │                        │◀──────── ack_update() ───│

Two ideas make this practical, and they're the parts worth stealing even if you never run the server:

1. Content travels out-of-band → zero token cost

Coordination signals (what changed, who must react) are small and belong in the model's context. Document bodies are large and don't need to be reasoned about the moment they're written — they need to be stored and fetched on demand. So AgentNexus splits the two:

• Control plane (MCP): notifications, subscriptions, queries — a notification carries a version number and a unified diff, enough to decide if and how to react.
• Data plane (plain HTTP POST /api/documents): full document body, never passed as an MCP tool argument.

A document of any size costs zero model tokens on the write path. You pay tokens for coordination, not for content.

2. SDAOP — the service onboards the agent, not the other way around

AGENTS.md, CLAUDE.md, Cursor rules, Kiro steering — they all share one model: a human writes a static file, commits it, and the IDE loads it at startup. It goes stale, it drifts, and it's per-human busywork.

Service-Driven Agent Onboarding Protocol (SDAOP) flips this. The service generates and delivers client-specific onboarding at connection time. A new agent only needs the endpoint:

generate_instruction_file(project_name="my-service", project_space_id="<space_id>", client_type="kiro")

• Emits the right artifact for the client — .kiro/steering/, CLAUDE.md, AGENTS.md, or .cursor/rules/ — plus a push-tool script with the server URL baked in.
• Each artifact is content-hash versioned. Change a convention on the server, or move the server to a new URL, and the version bumps — connected workspaces detect the drift and re-onboard. No stale files, no manual notification.
• The service is the single source of truth; the client-side file is a derived artifact that regenerates as the service evolves.

Supported clients: kiro, claude, codex, cursor.

Quick Start

# Install
pip install -e ".[dev]"

# Configure environment (copy example and fill in values)
cp .env.example .env

# Initialize database
python -m alembic upgrade head

# Start server (default: http://0.0.0.0:10086/mcp)
python src/main.py

Connect from Kiro / any MCP client:

{
  "mcpServers": {
    "agent-nexus": {
      "url": "http://localhost:10086/mcp"
    }
  }
}

First steps:

# Create a project space
create_space(name="my-project")

# Register two boundaries
register_project(name="backend-api", type="development", project_space_id="<space_id>")
register_project(name="frontend",    type="development", project_space_id="<space_id>")

# Push a document via HTTP POST (content stays out of LLM context)
# curl -X POST http://localhost:10086/api/documents -H 'Content-Type: application/json' \
#   -d '{"project_id":"<backend_id>","doc_id":"<backend_id>/api","content":"# API Spec..."}'

# Subscribe the frontend to the backend's API docs
add_subscription(subscriber_project_id="<frontend_id>", project_space_id="<space_id>", target_doc_id="<backend_id>/api")

# Frontend checks for updates (returns diff + full content)
get_my_updates_with_context(project_id="<frontend_id>")

Web Dashboard

Once the server is running, open http://localhost:10086/ in your browser to browse spaces, sub-projects, and documents, run full-text search, and use the built-in AI Chat for conversational document Q&A and service planning.

LLM configuration: AI Chat requires PLANNER_LLM_API_KEY. Set PLANNER_LLM_PROVIDER (openai or anthropic), PLANNER_LLM_MODEL, and optionally PLANNER_LLM_BASE_URL (Azure / Ollama / compatible APIs). Leave the key unset to disable AI features while keeping all browse/search functionality.

Key Features

• Versioned document store — SHA-256 dedup, full version history, per-boundary namespacing
• Publish-subscribe notifications — subscribe by exact doc ID or doc type
• Diff-aware updates — get_my_updates_with_context returns unified diff + full content in one call
• Control/data plane split — coordination over MCP, content over out-of-band HTTP (zero LLM token cost)
• SDAOP — services auto-generate versioned, client-specific onboarding files for any connecting agent
• Planner — a read-only, boundary-spanning observer (planner_chat, planner_plan, planner_overview) that answers cross-boundary questions no single agent can
• MCP HTTP server — streamable-HTTP transport, multiple agents connect simultaneously
• FTS5 full-text search — search_documents with BM25 ranking, phrase/prefix/boolean queries
• Web Dashboard + AI Chat — browser UI over spaces, projects, and documents
• 337 tests — unit + property-based (Hypothesis)

Out-of-Band Write Endpoint

The primary document write path. Content travels via HTTP body — never entering LLM context — so it's practical for documents of any size. Supports optional base_version for optimistic concurrency control (fast-forward check).

curl -X POST http://localhost:10086/api/documents \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project_id>",
    "doc_id": "<project_id>/requirement",
    "content": "# Requirements\n\nContent here..."
  }'

MCP Tools

Tool	Description
create_space	Create a Project Space
register_project	Register a sub-project (boundary)
list_projects	List all sub-projects in a space
list_documents	List all documents in a sub-project
get_document	Retrieve a document (latest or specific version)
get_my_updates_with_context	Get unread notifications with diff + full content
ack_update	Mark a notification as read
get_my_tasks	Get pending tasks for a project
get_config	Get config document for a stage
add_subscription	Add a subscription rule
publish_draft	Confirm a draft document
generate_instruction_file	Generate client-specific onboarding file (SDAOP)
get_project_id_by_name	Look up project_id by name
search_documents	Full-text search across documents in a space
planner_chat	Conversational Q&A with LLM over project documents (streaming)
planner_plan	Generate service-split proposal from a description
planner_overview	Get a high-level overview of a project space

Configuration

Environment Variable	Default	Description
AGENT_NEXUS_DB_URL	sqlite:///agent_nexus.db	Database URL
AGENT_NEXUS_DOCS_ROOT	./workspace	Workspace root (docs live under {root}/{space_id}/docs/)
AGENT_NEXUS_HOST	0.0.0.0	Server bind host
AGENT_NEXUS_PORT	10086	Server port
AGENT_NEXUS_PUBLIC_URL	(derived from host/port)	Outward-facing URL baked into onboarding files; changing it bumps the SDAOP version
AGENT_NEXUS_DEFAULT_SPACE_ID	default	Default space ID for bootstrap imports
PLANNER_LLM_PROVIDER	openai	LLM provider for Planner AI (openai | anthropic)
PLANNER_LLM_MODEL	(provider default)	LLM model name
PLANNER_LLM_API_KEY	(none)	API key; leave empty to disable AI features
PLANNER_LLM_BASE_URL	(none)	Custom API endpoint for OpenAI-compatible APIs (Azure, Ollama, proxies)

Running Tests

python -m pytest tests/ -q

Paper

The accompanying research papers are in the paper/ directory:

• paper/agentnexus-v4.md — v4 (current): generalizes the coordination unit from service to ownership boundary, adds the control/data plane split and the Planner (中文版)
• paper/agentnexus-v3.md — v3: introduces SDAOP
• paper/agentnexus.md — v2

dugubuyan. AgentNexus: A Boundary-Aware Coordination Architecture for Heterogeneous LLM Code Agents (v4). Zenodo, 2026. https://doi.org/10.5281/zenodo.21257426

License

MIT