agent-nexus

Purpose

AgentNexus is an MCP server that coordinates heterogeneous LLM coding agents. The real-world scenario it targets is this: the product is not a single codebase, but is composed of multiple independent repositories, tech stacks, and agents, such as the backend, frontend, infrastructure, and test suites. When the backend changes its API, the frontend must adapt; the traditional approach either relies on a person copying the spec into chat, or maintaining hand-written CLAUDE.md / AGENTS.md files, which become outdated as soon as the service changes.

This project emphasizes that coordination happens at the "service boundary," the construction unit of a real system, rather than assuming all agents are in the same simulated organization and the same codebase, as in role-playing-style multi-agent frameworks.

Main Capabilities

• Versioned document storage: SHA-256 deduplication, complete version history, and namespace isolation by boundary.
• Publish-subscribe notifications: subscribe by exact document ID or document type.
• Diff-aware updates: get_my_updates_with_context returns the unified diff and the full latest content in a single call, making it easy for agents to make targeted modifications without human intervention.
• Control plane / data plane separation: coordination signals (what changed, who should respond) are transmitted via MCP; document bodies are transmitted out of band via ordinary HTTP POST /api/documents, and bodies are never passed as MCP tool parameters, so documents of any size have zero model token cost on the write path—tokens are spent only on coordination, not on content.
• SDAOP (Service-Driven Agent Onboarding Protocol): the service generates and delivers a client-specific onboarding file at connection time, rather than having a person maintain a static file. It generates the corresponding artifact by client type—.kiro/steering/, CLAUDE.md, AGENTS.md, or .cursor/rules/—along with a push tool script that already has the server URL written into it. Each artifact is versioned by content hash; when the server conventions change or the server migrates to a new URL, the version increments, and connected workspaces detect drift and re-onboard. Supported clients: kiro, claude, codex, cursor.
• Planner: a read-only, cross-boundary observer that provides planner_chat, planner_plan, planner_overview, answering cross-boundary questions that no single agent can answer.
• MCP HTTP server: streamable-HTTP transport, allowing multiple agents to connect simultaneously.
• FTS5 full-text search: search_documents supports BM25 ranking, phrase / prefix / boolean queries.
• Web dashboard + AI Chat: browse spaces, subprojects, and documents in the browser, run full-text search, and use the built-in AI Chat for conversational document Q&A and service planning.
• 337 tests: unit tests + property-based tests (Hypothesis).

How to Use

After starting, open http://localhost:10086/ You can browse spaces, subprojects, and documents, run full-text search, and use the built-in AI Chat. Getting started requires no separate database migration or .env: everything has sensible defaults; only copy .env.example to .env when you need to change the port, point to Postgres, or enable the Planner LLM.

The primary path for document writes is the out-of-band write endpoint: content is transmitted via the HTTP body and never enters the LLM context. An optional base_version is supported for optimistic concurrency control (fast-forward check).

Connect from Kiro or any MCP client. The repository also provides a Docker run method; to preserve documents and the database after a restart, volumes must be mounted (see the repository documentation for the specific commands and configuration; not covered here).

LLM configuration: AI Chat requires PLANNER_LLM_API_KEY. You can set PLANNER_LLM_PROVIDER (openai or anthropic), PLANNER_LLM_MODEL, and optionally PLANNER_LLM_BASE_URL (Azure / Ollama / compatible API). When this key is not set, AI features are disabled, while browsing / search features remain available.

Applicable Scenarios

• Multiple independent repositories / services are maintained separately by different agents (backend, frontend, infrastructure, etc.), and cross-service interface dependencies exist.
• Agents running in different IDEs and on different models need to stay in sync automatically, avoiding hand-written glue code.
• You want to replace easily outdated static integration files with versioned documents, structured diffs, and a subscription mechanism.
• You need cross-boundary Q&A and planning (e.g., "which subprojects will be affected by a change to a certain interface").

Limitations and Notes

• Not affiliated with the project of the same name at MIT Lincoln Laboratory.
• The assumptions of role-playing multi-agent frameworks (ChatDev, MetaGPT) (the same simulated organization, the same codebase) do not apply to the real distributed system scenarios targeted by this tool.
• The specific ports (e.g., 10086) and default values given in the documentation are subject to the actual repository contents; the specific commands and volume mounting methods for running Docker are not fully covered in the original text and are not fabricated here.
• AI Chat depends on an external LLM API key; when not configured, the related AI features are unavailable.
• The project's accompanying research papers are located in the paper/ directory, including agentnexus-v4.md (current version, which generalizes the coordination unit from services to ownership boundaries and introduces control/data plane separation and the Planner), agentnexus-v3.md (introduces SDAOP), and agentnexus.md (v2). Citation: dugubuyan. AgentNexus: A Boundary-Aware Coordination Architecture for Heterogeneous LLM Code Agents (v4). Zenodo, 2026. https://doi.org/10.5281/zenodo.21257426