Ensemble MCP Server

An MCP server for orchestrating multiple AI agent backends (Claude Code, Codex, Ollama).

Features

• Multi-backend support: Spawn agents using Claude Code, Codex, or Ollama
• Configurable backends: Enable/disable backends, customize commands
• Circuit breaker: Safety limits to prevent runaway processes
• Activity sensing: Monitor agent working/idle status
• Multi-turn conversations: Send follow-up prompts to running agents
• Pagination: Handle large outputs efficiently

Quick Start

# Run with bunx
bunx ensemble-mcp

# Or with npx
npx ensemble-mcp

# Quiet mode (suppress banner)
bunx ensemble-mcp --quiet

# With model and limits
bunx ensemble-mcp --quiet --model sonnet --max-agents 10

CLI Options

| Option | Default | Description | |--------|---------|-------------| | --quiet, -q | false | Suppress startup banner | | --model <model> | - | Default model for all backends | | --claude-model <model> | - | Model for Claude (e.g., sonnet, claude-haiku-4-5) | | --codex-model <model> | - | Model for Codex (e.g., o3, gpt-5.1-codex) | | --max-agents <n> | 5 | Max concurrent active agents | | --max-total <n> | 20 | Max total agents (including completed) | | --timeout <n> | 30 | Max runtime per agent in minutes | | --idle-timeout <n> | 10 | Auto-terminate idle agents after N minutes |

Note: Spawned Claude agents automatically bypass user hooks via --settings flag.

MCP Tools

| Tool | Description | |------|-------------| | spawn_agent | Spawn a new agent using a configured backend | | list_agents | List all running and completed agents | | get_agent_output | Get paginated output from an agent | | get_agent_status | Get activity status (WORKING/IDLE) | | send_prompt_to_agent | Send follow-up prompt to running agent | | release_agent | Terminate a specific agent | | list_backends | List available backends | | configure_backend | Enable/disable a backend | | configure_circuit_breaker | Configure safety limits | | terminate_all_agents | Emergency killswitch |

Supported Backends

Claude Code (claude)

Spawns headless Claude Code instances using stream-JSON mode for multi-turn conversations.

spawn_agent backend="claude" prompt="Write a function to parse JSON"
spawn_agent backend="claude" prompt="Review this code" working_directory="/path/to/project"

Multi-turn support: Claude agents stay alive for follow-up prompts via send_prompt_to_agent.

Codex (codex)

Uses OpenAI Codex via bunx @openai/codex.

spawn_agent backend="codex" prompt="Generate a REST API"

Ollama (ollama)

Local LLM instances (disabled by default). Configure model in baseArgs.

# First enable the backend
configure_backend backend="ollama" enabled=true

# Then spawn agents
spawn_agent backend="ollama" prompt="Explain recursion"

Circuit Breaker

The circuit breaker prevents runaway processes:

| Setting | Default | Description | |---------|---------|-------------| | max_active_agents | 5 | Maximum concurrent running agents | | max_total_agents | 20 | Maximum total agents (including completed) | | max_runtime_minutes | 30 | Maximum runtime per agent | | max_output_size_kb | 1024 | Maximum output size per agent | | max_prompts_per_agent | 10 | Maximum follow-up prompts | | auto_terminate_idle_minutes | 10 | Auto-terminate idle agents |

Configure via:

configure_circuit_breaker max_active_agents=10 max_runtime_minutes=60

MCP Configuration

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "ensemble": {
      "command": "bunx",
      "args": ["ensemble-mcp", "--quiet"]
    }
  }
}

Or if using npx:

{
  "mcpServers": {
    "ensemble": {
      "command": "npx",
      "args": ["ensemble-mcp", "--quiet"]
    }
  }
}

Examples

Parallel Research

# Spawn multiple agents for parallel research
spawn_agent backend="claude" prompt="Research the history of neural networks"
spawn_agent backend="claude" prompt="Analyze current trends in AI safety"
spawn_agent backend="claude" prompt="Compare different LLM architectures"

# Check status
get_agent_status

# Retrieve results when idle
get_agent_output agent_id="<id>" full_output=true

Multi-Turn Conversation

# Start a Claude agent with context
spawn_agent backend="claude" prompt="Remember: the project uses TypeScript and React"
# Returns agent ID like "abc12345"

# Send follow-up prompts (agent retains context)
send_prompt_to_agent agent_id="abc12345" prompt="Write a Button component"
send_prompt_to_agent agent_id="abc12345" prompt="Now add hover states"

# Get accumulated output
get_agent_output agent_id="abc12345" full_output=true

# Release when done
release_agent agent_id="abc12345"

Development

# Clone and install
git clone https://github.com/y0usaf/ensemble
cd ensemble
bun install

# Build
bun run build

# Watch mode
bun run watch

# Test with MCP inspector
bun run inspector

License

GPL-3.0