Agent Nexus

What dugubuyan/agent-nexus MCP server does

dugubuyan/agent-nexus MCP server organizes coordination around service boundaries rather than a single shared codebase. A project space contains registered sub-projects, and each sub-project can own documents such as requirements, API specifications, design notes, or configuration. Documents have versions and are namespaced by their owning boundary.

Other projects can subscribe to a document by exact document ID or document type. When the document changes, subscribers can retrieve an unread notification containing a unified diff and the latest document content. This gives a receiving agent enough information to determine whether a targeted code change is needed, then acknowledge the notification after handling it.

The repository is MIT-licensed and includes a browser dashboard for browsing spaces, projects, and documents. The dashboard also exposes full-text search and optional AI Chat functionality.

How it works

The server separates coordination metadata from document content. MCP handles registration, subscriptions, notifications, queries, and acknowledgements. Full document writes use the HTTP endpoint at /api/documents, so large Markdown bodies are sent in the HTTP request rather than as MCP tool arguments. The write path supports an optional base version for optimistic concurrency checks.

A typical setup creates a space, registers service projects, pushes a document for one project, and subscribes another project to that document. The receiving project calls get_my_updates_with_context to obtain pending changes and then calls ack_update when the notification has been processed. get_document can return the latest version or a specified historical version, while search_documents searches documents across a space using FTS5.

The planner tools provide a read-only view across boundaries. planner_chat supports streaming questions over project documents, planner_plan creates a proposed service split from a description, and planner_overview returns a high-level space overview.

Setup and configuration

The documented local setup requires Python 3.11 or newer. From a checkout, install the project with pip install -e ., then start it with python -m agent_nexus.main. The default MCP endpoint is http://0.0.0.0:10086/mcp, and the web dashboard is served at the root URL on the same port. The server creates its database on first startup and does not require a separate migration or .env file for the default configuration.

A Docker image can also be built from the repository and run with port 10086 published. Mounting workspace and data directories allows documents and the database to persist across container restarts. The database URL can be changed with AGENT_NEXUS_DB_URL.

The planner's AI features are optional. Enabling them requires PLANNER_LLM_API_KEY, plus PLANNER_LLM_PROVIDER set to openai or anthropic and a model in PLANNER_LLM_MODEL. PLANNER_LLM_BASE_URL can point to Azure, Ollama, or a compatible API. Without the key, browsing and search remain available while AI features are disabled.

Tools and capabilities

dugubuyan/agent-nexus MCP server exposes tools for:

• Creating spaces and registering, listing, and identifying sub-projects.
• Listing documents and retrieving current or historical versions.
• Managing subscriptions, pending tasks, unread updates, and acknowledgements.
• Reading stage configuration and confirming draft documents.
• Generating onboarding files for Kiro, Claude, Codex, and Cursor clients.
• Searching documents with phrase, prefix, and Boolean queries.
• Asking planner questions, generating service-split proposals, and viewing project overviews.

Generated onboarding artifacts can include client-specific files such as CLAUDE.md, AGENTS.md, Cursor rules, or Kiro steering files. These artifacts are content-hash versioned so connected workspaces can detect changes and regenerate them.

Limitations and notes

The core document and coordination features do not require an LLM API key, but planner AI functionality does. The README describes the server as an MCP HTTP server using streamable HTTP, so clients must support connecting to the configured MCP URL or use an appropriate MCP-compatible setup. Full document content is written through the HTTP API rather than the MCP tool interface. The provided material does not specify built-in authentication or authorization for the server.