mcp-multi-agent

An MCP server that gives your AI editor a small team: a BA, a developer, a reviewer and a refactor agent. You give it a ticket number; it works out which agent is needed, pulls the context from Jira, GitHub and SonarQube in parallel, and hands the model in your editor a short, precise plan. The project's own rules files decide how the agents behave.

What a run looks like, summarised:

you   ›  do PROJ-142

router   no open PR · ticket has acceptance criteria → developer
jira     PROJ-142 "Discount codes at checkout" · 3 acceptance criteria
sandbox  git worktree ../sandbox-PROJ-142 on feature/PROJ-142
rules    AGENTS.md (from .mcp-agent.json) + 4 learned rules
context  3 files distilled to a skeleton for the model
plan     .mcp-plan-PROJ-142.md → your editor implements it, you approve the edits

It is not a model. It is the orchestration around one: what to read, where to work, which rules apply and what must never happen.

Why

AI coding sessions tend to go like this: paste the ticket, paste some files, repeat the team's rules for the hundredth time, and hope the agent doesn't touch something it shouldn't. This server makes the routine parts automatic and the dangerous parts impossible:

• One command per ticket. do PROJ-142 picks the agent from the state of the work.

• The team's rules, from the team's files. AGENTS.md, CLAUDE.md, .cursorrules, .clinerules, Copilot instructions: the agents read the files you choose, fresh on every run.

• A sandbox per ticket. Each ticket gets its own git worktree and branch; your working copy is never touched.

• Guardrails that are code, not prompts. Commands are checked against an allowlist before they run.

• Less context, same meaning. Large files reach the model as a skeleton of types and signatures.

Related MCP server: aico

The agents

Every decision can be forced with a flag (ba, refactor, squad).

Rules files

The agents follow the rules your project already keeps for AI tools. Which files, in order:

1. rulesFiles passed to the tool

2. rulesFiles in .mcp-agent.json at the project root (commit it, so the whole team gets the same rules)

3. rulesFiles saved by the setup script, for that project

4. every known rules file found in the project: .clinerules, AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules/, .windsurfrules, .github/copilot-instructions.md, GEMINI.md

// .mcp-agent.json
{ "rulesFiles": ["AGENTS.md", "docs/frontend-guidelines.md"] }

On top of that, learned rules: when you reject something ("don't use any"), capture_behavior_feedback stores it as a rule for that project. Learned rules are one line each, at most 300 characters and 50 per project (the least used go first), and you can list and remove them. show_rules tells you exactly what the agents will follow and why.

Safety

• Sandbox: a git worktree per ticket at ../sandbox-<ticket>, on feature/<ticket>.

• The server itself only runs git, without a shell, with arguments as an array, an allowlist of subcommands, and every absolute path scoped to the project.

• check_command lets the editor ask before running anything. Known programs only (git, npm, node, tsc, eslint, test runners, read-only file tools); blocked: deleting files, force pushes, pushing to main, reset --hard, publishing packages, npx of arbitrary packages, piping into a shell, command substitution, and any path outside the sandbox.

• Ticket text is input, not instructions: file paths taken from a ticket cannot leave the sandbox, and learned rules are sanitized to a single line before they reach a prompt.

• Reviews are previews by default. Nothing is posted on a PR unless you ask.

• Secrets stay local: tokens live in your editor's MCP config; logs redact anything that looks like a credential.

• Auditable: every step, command and downstream call is logged; parse_audit_log and generate_task_metrics_report show what happened and roughly how much context it sent.

Quick start

Running the server requires a licence from the author (see Licence). These steps are for licensed users.

Requirements: Node 18+, git, an editor with MCP support (Cline, Cursor, Claude Desktop, Claude Code, Codex CLI), and tokens for the services you use.

git clone <this repo> mcp-multi-agent
cd mcp-multi-agent
npm install
npm run setup

npm run setup builds the server and asks: which project, which of its rules files the agents should follow (or creates an AGENTS.md starter), which editor, which services, and the tokens. It registers the server in your editor and saves defaults so do PROJ-123 needs nothing else. Restart the editor and ask it to run do with a ticket id.

Manual setup and every option: docs/setup.md.

Tools

How it works

editor (Cline · Cursor · Claude · Codex)
   │  stdio
   ▼
mcp-multi-agent ── router ── BA · developer · reviewer · refactor
   │                    │
   │                    ├─ rules      rules files + learned rules → prompt
   │                    ├─ sandbox    git worktree, command allowlist
   │                    ├─ distiller  TypeScript-compiler skeletons
   │                    └─ logger     audit log, redaction, session report
   ▼  stdio, spawned on demand and pooled
GitHub MCP · Jira MCP · SonarQube MCP · Confluence MCP · Chrome DevTools MCP

More in docs/architecture.md.

Development

npm install
npm run build
npm test        # node:test, no extra test framework

Tests cover the router, the BA analysis, the sandbox (including real worktrees and the command policy), the distiller, rules loading and learned rules, and log redaction. CI runs them on Node 18, 20 and 22.

Limitations

• The BA analysis is deterministic text analysis, not a model. It finds what is missing; it does not invent requirements.

• Token figures are estimates (about 4 characters per token): the model runs in your editor, so the server never sees real counts.

• check_command only protects you if the editor calls it. Keep the editor's own command approval on.

• The Jira integration uses the REST passthrough of @aashari/mcp-server-atlassian-jira (Jira Cloud, API v3).

• The npm builds of the GitHub and SonarQube MCP servers are deprecated upstream. They are pinned to their last versions here; moving to GitHub's and SonarSource's official servers is next on the list.

Licence

© 2026 Alex Cenusa. All rights reserved. The code is public so it can be read; using, copying, modifying or distributing it requires my written permission. See LICENSE.