multi-agent-orchestrator

An MCP server that orchestrates multiple AI agents (LLMs, CLI tools) in parallel to get diverse perspectives on a single topic. Agents run side-by-side — debating, reviewing, or answering questions — and results are synthesized or returned raw.

Built for use inside Claude Code (or any MCP-compatible client).

What it does

You configure two or more AI agents (e.g. Gemini via MCP, Codex CLI, any LLM with a CLI or MCP interface). The orchestrator fans out your prompt to all agents in parallel, collects their responses, and optionally synthesizes the results.

Three orchestration modes:

Mode	Rounds	Synthesis	Cross-talk	Use case
debate	Multi (default 2)	Yes	Yes — agents see previous rounds	Get balanced analysis with opposing viewpoints
review	1+	Yes	No — independent reviews	Code/config/architecture review from multiple angles
quick	1 (forced)	No	No	Fast multi-perspective answers, lowest latency

Setup

1. Install dependencies and build

npm install
npm run build

2. Configure agents

Edit agents.config.json in the project root:

{
  "agents": [
    {
      "id": "gemini",
      "name": "Gemini",
      "type": "mcp",
      "command": "npx",
      "args": ["-y", "gemini-mcp-tool"],
      "mcpTool": "ask-gemini",
      "mcpPromptField": "prompt",
      "timeout": 120000
    },
    {
      "id": "codex",
      "name": "Codex CLI",
      "type": "cli",
      "cliCommand": "codex",
      "cliArgs": ["exec"],
      "cliInputMode": "arg",
      "timeout": 120000
    }
  ]
}

Agent types:

• mcp — Connects to another MCP server as a client. Specify command/args to launch it, mcpTool for which tool to call, and mcpPromptField for the parameter name that receives the prompt.
• cli — Runs a CLI command. The prompt is passed as a trailing argument (cliInputMode: "arg") or via stdin (cliInputMode: "stdin").

3. Register as MCP server

Add to your Claude Code config (~/.claude.json or project-level .mcp.json):

{
  "mcpServers": {
    "multi-agent": {
      "command": "node",
      "args": ["/absolute/path/to/multi-agent/dist/index.js"]
    }
  }
}

Restart Claude Code. The tools list_agents, orchestrate, and orchestrate_respond should appear.

Usage

List agents

list_agents

Shows all configured agents and their connection status.

Quick mode — fast parallel answers

orchestrate(mode="quick", topic="What's the best way to handle secrets in Docker Compose?")

All agents answer in parallel. No synthesis, no rounds. You get side-by-side responses immediately.

Review mode — independent parallel reviews

orchestrate(
  mode="review",
  topic="Review this Dockerfile for security issues",
  context="FROM ubuntu:latest\nRUN apt-get update\nCOPY . /app\nRUN chmod 777 /app\nEXPOSE 22\nCMD [\"python\", \"app.py\"]"
)

Each agent reviews independently (no cross-talk). Results are synthesized into a consolidated report with deduplicated findings ranked by severity.

Interactive review (Claude participates between rounds):

orchestrate(
  mode="review",
  topic="Review this Terraform module",
  context="...",
  participate=true,
  rounds=2
)

After round 1, Claude can steer round 2 by providing feedback via orchestrate_respond. Agents receive Claude's feedback and dig deeper into flagged areas.

Debate mode — structured multi-round discussion

orchestrate(
  mode="debate",
  topic="Should infrastructure teams use Pulumi over Terraform?",
  rounds=2
)

Agents see each other's previous responses and build on, challenge, or refine arguments. Final synthesis highlights agreements, disagreements, and a balanced conclusion.

Interactive debate (default — Claude participates):

orchestrate(
  mode="debate",
  topic="Microservices vs monolith for a 5-person startup",
  participate=true,
  rounds=3
)

After each round, Claude adds perspective via orchestrate_respond(session_id, response). Agents see Claude's input in the next round.

Parameters

Parameter	Type	Default	Description
mode	"debate" | "review" | "quick"	required	Orchestration mode
topic	string	required	The question or task
context	string	—	Code, config, or other content to analyze
agents	string[]	all	Agent IDs to use (subset of configured agents)
rounds	number (1-10)	2	Number of rounds (forced to 1 for quick)
participate	boolean	true	Claude participates between rounds (forced to false for quick)
systemPrompt	string	—	Custom system prompt prepended to agent prompts

Use cases

• Code review: Get independent security/quality reviews from multiple LLMs, then a consolidated report
• Architecture decisions: Debate trade-offs (e.g. Pulumi vs Terraform) with agents arguing different sides
• Dockerfile/IaC audits: Review mode catches issues each model is best at, synthesis deduplicates
• Quick Q&A: Fan out a question to multiple models, compare answers side-by-side
• Second opinions: When one LLM's answer feels off, get parallel perspectives fast
• Compliance checks: Independent reviews against best practices, merged into actionable findings

Do's and Don'ts

Do

• Use quick for simple questions where you just want diverse answers fast
• Use review for auditing artifacts (code, Dockerfiles, Terraform, configs) — independent reviews catch more than a single model
• Use debate for subjective/strategic decisions where trade-offs matter
• Provide context when reviewing code or configs — agents need the actual content
• Use participate=true to steer multi-round sessions — Claude's feedback between rounds focuses agents on gaps
• Start with fewer rounds (1-2) and increase if you need deeper analysis
• Use agents parameter to pick specific agents when not all are relevant

Don't

• Don't use debate for factual questions — debating facts produces noise, not insight. Use quick instead
• Don't skip context in review mode — without content to review, agents can only give generic advice
• Don't set high round counts blindly — each round multiplies latency and cost. 2-3 rounds covers most cases
• Don't expect agents to remember across sessions — each orchestration is stateless. Sessions expire after 10 minutes
• Don't use this for simple single-model tasks — orchestration overhead isn't worth it when one model is enough
• Don't put secrets in context — prompts are sent to external LLM APIs

Adding agents

Any tool that accepts a text prompt and returns text can be an agent:

MCP agent (any MCP server with a tool that takes a prompt):

{
  "id": "my-agent",
  "name": "My Agent",
  "type": "mcp",
  "command": "node",
  "args": ["path/to/mcp-server.js"],
  "mcpTool": "ask",
  "mcpPromptField": "prompt",
  "timeout": 120000
}

CLI agent (any CLI that accepts a prompt as argument or stdin):

{
  "id": "my-cli",
  "name": "My CLI Tool",
  "type": "cli",
  "cliCommand": "my-tool",
  "cliArgs": ["--format", "markdown"],
  "cliInputMode": "arg",
  "timeout": 60000
}

Environment variables can be passed per agent via the env field:

{
  "id": "openai",
  "name": "GPT",
  "type": "cli",
  "cliCommand": "openai-cli",
  "cliArgs": ["chat"],
  "cliInputMode": "stdin",
  "env": { "OPENAI_API_KEY": "sk-..." },
  "timeout": 120000
}

Terms of Service & Compliance

This tool orchestrates third-party AI models. You are responsible for complying with each provider's terms. The orchestrator itself is a local dev tool — it doesn't proxy, resell, or redistribute API access.

Authentication requirements

Agents must authenticate through commercial/API tiers, not consumer accounts:

Provider	Compliant auth	Non-compliant auth
Google Gemini	API key (GOOGLE_API_KEY), Google Workspace Enterprise, Vertex AI	Free-tier Google account OAuth
OpenAI	API key, Teams/Enterprise plan	ChatGPT consumer account scraping
Anthropic	Claude Code with MCP (built-in), API key via Console	Subscription OAuth tokens in third-party tools

Using gemini-mcp-tool with Google OAuth on a free personal account is a gray area — Google's free tier allows automated API usage but may use your inputs for training. Prefer setting GOOGLE_API_KEY or authenticating through a Workspace subscription.

What this tool does NOT do

• Does not use model outputs to train competing AI models
• Does not resell, sublicense, or proxy API access to third parties
• Does not bypass rate limits, safety filters, or usage caps
• Does not extract or scrape consumer web interfaces

Key TOS clauses to be aware of

• Google (Gemini API Terms): Prohibits using the service to develop competing models or reverse-engineer underlying data. Free-tier inputs may be used for training.
• OpenAI (Services Agreement): Prohibits using outputs to develop competing AI models, transferring API keys, and circumventing usage limits.
• Anthropic (Consumer Terms, Commercial Terms): MCP servers within Claude Code are explicitly supported. Subscription OAuth tokens must not be used outside Claude Code/Claude.ai. Prohibits building competing products from service outputs.

Recommendations for public/shared deployments

1. Always use commercial API tiers (Google Workspace, OpenAI Teams/Enterprise, Anthropic API)
2. Don't commit API keys — use environment variables or a secrets manager
3. Don't expose the orchestrator as a public API — it's designed as a local dev tool
4. Review provider terms periodically — AI service terms change frequently

Disclaimer: This is not legal advice. Review each provider's current terms before use. Terms linked above were last verified in February 2026.

Architecture

Claude Code (MCP client)
    |
    v
multi-agent-orchestrator (MCP server)
    |
    +---> Agent 1 (MCP client -> child MCP server)
    +---> Agent 2 (CLI subprocess)
    +---> Agent N (...)

The orchestrator is both an MCP server (exposing tools to Claude) and an MCP client (connecting to agent MCP servers). CLI agents are spawned as subprocesses.

License

MIT