Rutherford MCP Server

uv tool install rutherford-mcp-server

Using Claude Code? The Rutherford Claude Plugin wraps this server with one-step setup: it auto-registers the server (no manual mcp add) and adds skills, an orchestrator agent, and slash commands for setup, panels, consensus, debate, and review. Install it with /plugin marketplace add chapmanjw/rutherford-claude-plugin then /plugin install rutherford@rutherford-claude. Either path is fully supported — reach for the plugin for a batteries-included Claude Code experience, or wire up this server directly for any MCP client.

What Rutherford is

Rutherford is a Model Context Protocol server that speaks the Agent Client Protocol on the other side. Your MCP client (a coding CLI or a desktop app) calls Rutherford's tools; Rutherford spawns each target coding agent as an ACP server over stdio and drives it through a real initialize / new_session / prompt exchange.

It is the ACP client, and each coding agent is an ACP agent. That distinction matters: under ACP the protocol negotiates the answer, token usage, tool activity, and permissions as structured events, so Rutherford never scrapes an agent's stdout and never reimplements a CLI's features. It also never calls a model provider's API directly — every answer comes from an agent you already log into, in the agent's own account.

   your MCP client (Claude Code, Cursor, Codex, Claude Desktop, ...)
        |  MCP over stdio
        v
   rutherford-mcp-server          (the ACP client)
        |  ACP over stdio, one session per voice
        +--> goose acp
        +--> codex-acp                 (the Zed adapter fronting Codex)
        +--> claude-agent-acp          (the Zed adapter fronting Claude Code)
        +--> ... 17 more built-in agents, all config-driven

A voice that fails to spawn, handshake, or answer comes back as one failed result in a structured envelope, never an aborted panel.

Related MCP server: Claude Code MCP - Agent Orchestration Platform

See it work

The mode that is not just parallel answers is debate. Round one is each voice's independent take; in every later round, each voice sees the others' latest positions and is asked to rebut and revise. Each voice keeps one persistent ACP session across the rounds, so it remembers its own prior reasoning and only the delta is sent each round — the capability the old subprocess-per-call model could not offer.

prompt   "Is UUIDv7 or ULID the better primary key for a high-write event table?"
panel    claude_code, codex, kiro    rounds: 3

round 1  claude_code   UUIDv7 — the timestamp prefix gives B-tree index locality
         codex         UUIDv7 — standardized and DB-native; monotonic within a process
         kiro          UUIDv7 — but argues ULID is BOTH lexicographically sortable AND
                       collision-resistant across concurrent writers

round 2  claude_code   flags that Kiro conflates two properties: ULID's sortability and
                       its per-process monotonicity are not the same guarantee
         codex         agrees — the monotonic guarantee is per-process, not cross-node
         kiro          revises: cross-node, UUIDv7's timestamp prefix gives the locality
                       without relying on a per-process assumption

result   converged on UUIDv7, with a closing synthesis of where the panel agreed and why

The call returns the full per-round transcript plus the closing synthesis, so you can retrace who said what and where someone revised. Debates do not always converge or change a mind, but when they do the transcript shows precisely where.

Quickstart

You bring the crew. Rutherford does not install or authenticate any coding agent — it drives the ones you already have. You need Python 3.11+ and at least two ACP-capable agents installed and signed in (two is enough for a consensus or a debate). If you already use Claude Code or Codex, you have most of what you need.

1. Install Rutherford.

uv tool install rutherford-mcp-server
# or: pipx install rutherford-mcp-server  /  pip install rutherford-mcp-server

This puts the console entry point rutherford-mcp-server on your PATH. The same command starts the stdio server on Windows, macOS, and Linux; python -m rutherford is equivalent.

2. Register it with your MCP client.

claude mcp add rutherford -- rutherford-mcp-server      # Claude Code
codex mcp add rutherford -- rutherford-mcp-server       # Codex

For Claude Desktop, Cursor, and other JSON-config clients:

{ "mcpServers": { "rutherford": { "command": "rutherford-mcp-server" } } }

If rutherford-mcp-server is not on the client's PATH, use an absolute path, or python -m rutherford with the interpreter from the environment where you installed it. More clients and WSL: docs/mcp-client-integration.md.

3. Scaffold a config (optional). Rutherford works with zero config. To write a starter file, either run the one-shot CLI from your terminal:

rutherford-mcp-server init          # or: python -m rutherford init  [--global] [--yes]

or, once it is registered with a client, ask for the setup tool:

Run Rutherford's setup and write a project config.

Both resolve the config path, write a commented starter config.toml at the effective defaults, and never clobber an existing file. init targets <cwd>/.rutherford/config.toml (or the global path with --global); setup returns the path and content to the client and writes with write=true.

4. Run doctor first. Multi-agent auth and PATH is the most common thing that goes wrong, so confirm the crew actually drives before your first real task:

Run Rutherford's doctor and tell me which agents spawn, handshake, and answer.

doctor probes each agent with a real read-only ACP round trip — the only trustworthy health signal, since there is no cheap non-interactive auth check. Each report is ok, no_answer, handshake_failed, not_installed, or error. Two or more ok agents means you are ready.

No paid agent subscription? Run your first consensus for free against a local model. With Ollama or LM Studio running, Rutherford auto-detects each tool-capable model and registers it as a goose-based agent — no key, no account. See docs/local-models.md.

The tools

You rarely call these by name; your agent picks them from your request. Everything defaults to read-only.

Shared arguments on delegate / consensus / debate: working_dir, files (paths to put in scope), safety_mode, timeout_s, role, and mode (sync or async). delegate also takes trust_workspace for the mutating modes; debate takes rounds, judge, and synthesize.

The agent roster

Rutherford ships 20 built-in agents with curated launch commands and quirks (the Windows npm-shim resolution, per-agent handshake budgets, a fixed provider) that a bare acp.json cannot express, so they work with zero config:

codex and claude_code launch through the official Zed adapters (codex-acp and claude-agent-acp, npm @agentclientprotocol/*), which front the Codex and Claude Code CLIs as ACP servers and reuse the existing CLI login — no API key. cline drives over ACP only with Cline's own service auth (a ChatGPT-subscription or OpenRouter provider set in the desktop app does not reach the headless --acp path). hermes depends on the configured Nous model and its latency can be high. gemini is Google's official Gemini CLI (the --acp mode works as of CLI 0.46.0). qoder's --acp flag is real but hidden from --help, and Qoder's installer drops qodercli at ~/.qoder/bin/ rather than on PATH — add that directory to PATH, point [agents.qoder] command at the full path, or let discover find it. grok (xAI) is ACP-native and connects cleanly, but a completed turn needs a SuperGrok subscription — without it the model call returns 403; run doctor connect_only=true to confirm Rutherford can reach and configure it (it reports reachable and the advertised models) independent of the entitlement. Not every agent drives cleanly on every machine — run doctor to see which actually answer here.

Config-driven agents. Under ACP an agent is just how to launch it plus a few quirks, so the roster is config-driven. An [agents.<id>] section overrides a built-in's command / env / provider / model, disables one with enabled = false, or defines a brand-new agent (any unknown id, which must supply a launch command). enabled_agents restricts the registry to an allowlist. The launch fields mirror the Zed/Cline acp.json shape, and the loader auto-imports an acp.json beside the global config or in the project's .rutherford/. See docs/adding-an-agent.md.

Local models. With auto_detect_local_models on (the default), Rutherford probes a running Ollama (:11434) and LM Studio (:1234) at startup and registers each tool-capable model as a goose-based ACP agent automatically. You can also point an agent at a local runtime by hand. See docs/local-models.md.

Safety modes

Every delegation runs in one of four modes, defaulting to the most restrictive. Rutherford is the permission authority at the moment of each ACP tool call: it answers the agent's filesystem-write, terminal-execution, and tool-permission requests according to the mode.

A call that omits safety_mode adopts the configured default_safety_mode (read_only out of the box); an explicit value always wins. write and yolo require a trusted workspace: the target working_dir must be on the trusted_workspaces allowlist, or the call must pass trust_workspace=true. Full detail: docs/security.md.

Jobs, roles, and config

Background jobs. Pass mode="async" to delegate / consensus / debate to run the work off the request path: the call returns a small {job_id, status, tool} envelope immediately, and the work runs as an in-memory task. Manage it with list_jobs, activity, job_status, job_result, and cancel_job. A finished job's result envelope is byte-for-byte the same as the sync path's. Jobs are in-memory and clear on restart.

Roles. A role is a reusable system prompt. Pass role="<id>" to delegate / consensus / debate and the persona is prepended to your prompt. Five built-ins ship as package data: principal-reviewer, architect, debugger, security-reviewer, and explainer. A role_dirs directory adds new roles or overrides a built-in. list_roles enumerates the catalog.

Config. Rutherford works with zero config. When you do configure it, a TOML file at the global or project scope sets the agent roster, defaults, and safety policy; RUTHERFORD_* environment variables override specific fields. Full reference: docs/configuration.md.

Documentation

• docs/architecture.md — the v3 ACP-native architecture and the key seams.

• docs/configuration.md — the complete RutherfordConfig reference and config discovery.

• docs/adding-an-agent.md — config-driven agents, acp.json import, local backends.

• docs/local-models.md — Ollama and LM Studio as first-class voices.

• docs/recipes.md — task-oriented usage recipes.

• docs/mcp-client-integration.md — wiring Rutherford into MCP clients.

• docs/security.md — the safety model and the permission engine in depth.

• docs/troubleshooting.md — common problems and fixes.

• docs/integration-testing.md — running the real-agent integration suite.

The name

.---------.
|  \/\/\/ |
|  O  [==]|
|    <    |
|  \___/  |
'---------'
-- Ensign Sam Rutherford --
USS Cerritos . Engineering

Named for the cheerful engineer aboard the USS Cerritos in Star Trek: Lower Decks, who has a gift for getting heterogeneous systems to cooperate. That is the job here: one agent hands work to a crew of others and brings the results back. Star Trek and Lower Decks are trademarks of their respective owners; this is an unaffiliated, fan-named open-source project.

Contributing

See CONTRIBUTING.md. The whole core is testable without a real agent; run just check before pushing, then just test-integration for whatever agents your machine has installed and authenticated.

License

MIT (c) John Chapman. See LICENSE.

Star History