# 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

```bash
npm install
npm run build
```

### 2. Configure agents

Edit `agents.config.json` in the project root:

```json
{
  "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`):

```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):
```json
{
  "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):
```json
{
  "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:
```json
{
  "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](https://ai.google.dev/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](https://openai.com/policies/services-agreement/)): Prohibits using outputs to develop competing AI models, transferring API keys, and circumventing usage limits.
- **Anthropic** ([Consumer Terms](https://www.anthropic.com/legal/consumer-terms), [Commercial Terms](https://www.anthropic.com/legal/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