throng-mcp

An MCP server that lets your agent hand work to another one. Any MCP client can call it, and the task goes to any supported harness.

• Another model's view. A review by another vendor's model, a design critique, a cheaper model for a mechanical pass.

• Second opinions. Hand one agent's result to another: Codex reviews, Claude fixes, Codex checks again, each in its own long-lived session.

• Real sessions, not one-shots. The nested agent keeps running; a follow-up goes to the same agent with everything it already knows.

• Background work. Several agents run at once while you carry on.

• Answers by schema. Pass a JSON Schema and the result comes back as data that fits it, not prose to parse: a list of findings, a verdict, a plan, ready to feed into the next step.

Supported harnesses: Claude Code, Codex, OpenCode (and every model it can reach), Gemini CLI, Cursor CLI, GitHub Copilot CLI. Setup for each is under Install.

Any other ACP agent can be described in the config as a custom harness: its command, and the mode or options that make it auto-approve or ask. throng installs nothing for it and guesses nothing; see Custom harnesses.

Example

You're in Claude Code and have just changed the payment flow.

Ask Codex to find a way this payment flow could charge someone twice. Don't change any files.

Claude calls run_thronglet with agent: "codex/gpt-6-sol:high", a self-contained prompt, the repository path and a schema, so the findings come back as data: file, line, steps to reproduce.

Give the findings to Opus. Have it fix each one, add a test for it and run the tests.

A second run_thronglet, with agent: "claude/opus". Codex's findings go into its prompt; Opus edits the code and runs the tests.

Now show the same Codex session what changed. Can it still make a customer pay twice?

That is send_message into the first session: Codex still has its findings in context and checks the fixes against them instead of starting over.

Any of these calls takes background: true: it returns at once and wait_thronglet collects the result later, which is how several agents work while you carry on.

Related MCP server: Claude Code MCP

Install

Three parts, in order: the server, the agents it may run, and the client it is called from. The skill at the end is optional.

The plugin covers parts 1, 3 and 4; the agents from part 2 you still install yourself.

claude plugin marketplace add agent-runbooks/throng-mcp
claude plugin install throng@throng-mcp

The plugin runs the server version it was released with. To move to a newer release:

claude plugin marketplace update throng-mcp
claude plugin update throng@throng-mcp

1. The server

The npm package throng-mcp. Needs node ^22.13 || >=24. Tested with node 24.11.1, claude 2.1.282, codex 0.156.1, opencode 1.18.30.

Two ways to run it:

• npx -y throng-mcp@0.9.1 straight in the client config, below. Nothing to install: npx fetches the package on the first start and caches it. The package has no dependencies, so that is one tarball and nothing else. The version is pinned, so the server changes only when you change it: to update, put the new version from the changelog into the command.

• A global install, then the command is throng-mcp. Starts faster than going through npx. To update, run the install again.

  npm i -g throng-mcp

2. The agents to run

Each agent needs its own CLI installed and logged in. throng talks to agents over ACP (Agent Client Protocol); Claude Code and Codex need an ACP adapter, and throng ships none. Install only the agents you want to delegate to.

npm i -g @agentclientprotocol/claude-agent-acp
claude auth status

throng passes the path of the claude it finds on PATH to the adapter (CLAUDE_CODE_EXECUTABLE), so the nested agent runs your installed, logged-in CLI. If claude auth status says not logged in, put CLAUDE_CODE_OAUTH_TOKEN into the config, see docs/configuration.md.

npm i -g @agentclientprotocol/codex-acp
codex login

The adapter gets the path of your codex the same way (CODEX_PATH).

OpenCode speaks ACP itself (opencode acp), so there is no adapter. Install it per https://opencode.ai/docs, then:

opencode auth login

Custom providers live in your ~/.config/opencode/opencode.json; throng doesn't touch it.

Gemini CLI speaks ACP itself (gemini --acp), so there is no adapter.

npm i -g @google/gemini-cli
gemini

Gemini CLI needs a Gemini API key (Google AI Studio) or Vertex: run gemini once, choose "Use Gemini API Key" and paste the key, or set GEMINI_API_KEY. The nested agent uses that key. Signing in with a personal Google account no longer works for Gemini CLI. Its limits under throng: docs/harnesses.md.

Cursor CLI speaks ACP itself (cursor-agent acp), so there is no adapter.

curl https://cursor.com/install -fsS | bash
agent login

throng finds cursor-agent on PATH and authenticates with the login agent login saved; without that login every run fails with harness_unavailable and Cursor's message asking to run agent login. Its limits under throng: docs/harnesses.md.

Copilot CLI speaks ACP itself (copilot --acp), so there is no adapter.

npm i -g @github/copilot
copilot login

throng finds copilot on PATH; the nested agent uses the login copilot login saved, or the GitHub CLI's. With a login from the GitHub CLI only, Copilot offers no model choice and every run fails with model_rejected; run copilot login. Its limits under throng: docs/harnesses.md.

3. The MCP client

The client is the session that calls throng. It may be the same program as one of the agents above, or a different one. The server speaks stdio and the command is npx -y throng-mcp@0.9.1, or throng-mcp after a global install.

claude mcp add --scope user throng -- npx -y throng-mcp@0.9.1

--scope user registers it for every project; without it, for the current project only. claude mcp list shows the result.

codex mcp add throng -- npx -y throng-mcp@0.9.1

In ~/.config/opencode/opencode.json:

{
  "mcp": {
    "throng": {
      "type": "local",
      "command": ["npx", "-y", "throng-mcp@0.9.1"],
      "enabled": true
    }
  }
}

Any other MCP client: register a stdio server with that command.

4. The skill, optional

skills/throng tells the calling agent how to use the server: when to delegate, how to write the prompt, background runs, follow-ups, structured output, what a refused permission means. It is a file for the agent and does not install the server.

npx skills add agent-runbooks/throng-mcp --skill throng -g -a claude-code -y

-g installs into the agent's user directory, for every project; without it, into the current project. -a codex or -a opencode for the other agents. npx skills update pulls later changes.

Copy skills/throng into your agent's skills directory: ~/.claude/skills, ~/.codex/skills, ~/.config/opencode/skills. A global install also leaves it under the installed package, $(npm root -g)/throng-mcp/skills/throng.

Agents pick skills up at session start, so open a new session after installing.

Check

In a new session, ask the agent to call list_harnesses. It starts each installed adapter without a prompt (seconds, no tokens) and lists the installed harnesses with their models and effort levels; unavailable holds the ones that are configured or installed but broken, with the reason. A built-in harness you haven't installed is not listed, and run_thronglet on it says what to install. If a run then fails during the handshake, the usual cause is auth: claude auth status, codex login, opencode auth login, gemini (set the API key once), agent login (Cursor), copilot login (Copilot). More in troubleshooting.

Before the first run, two things to know. The agent edits the directory you name, with your user's rights; throng adds no isolation and rolls nothing back. Give it only trees you would let an agent edit unattended, and give parallel writers a worktree each.

Using throng

agent names harness, model and effort in one string, <harness>/<model>[:<effort>]:

claude/opus:max
codex/gpt-6-sol:xhigh
opencode/openrouter/z-ai/glm-5.3-flash
gemini/gemini-2.5-pro
cursor/gpt-5.4-nano
copilot/auto

The model is one of the harness's own values; list_harnesses has the current list. Effort is low | medium | high | xhigh | max; omitted means the harness default.

A call:

{
  "agent": "codex/gpt-6-sol:high",
  "prompt": "In this repository, add a --verbose flag to the CLI in src/cli.ts and a test for it. Run pnpm test. Leave the changes uncommitted and end with the list of files you changed.",
  "cwd": "/work/my-app",
  "description": "add --verbose flag"
}

The prompt is self-contained: the nested session sees nothing of the calling conversation. The call returns the agent's final message, a session_id for follow-ups, and why the turn stopped.

background: true on run_thronglet or send_message returns as soon as the turn is running; wait_thronglet collects the result later, which is how several agents run at once. schema asks for structured output: the agent ends with a JSON value matching the JSON Schema, and the result comes back as structured instead of text.

A failure is an MCP tool error with code, message and, when the session exists, session_id and the partial text. Every field, error code and stop reason of every tool is in DESIGN §3.

Permissions and safety

What a nested agent may do comes from the config file, never from a tool parameter, so the calling model cannot grant itself more than you allowed. Optional ~/.config/throng/config.yaml:

harness_mode: auto        # auto | ask
permission_answers: deny  # auto | allow | deny | elicit

• harness_mode is the mode the harness runs in: auto (the default) is its own auto-approve mode (Claude auto, Codex agent, OpenCode as configured, Gemini yolo, Cursor --force, Copilot allow_all), ask its asking mode.

• permission_answers is how throng answers what the harness still asks: deny (the default) refuses, allow allows once, elicit shows you a dialog in the MCP client (needs elicitation support; Claude Code has it), auto shows the dialog when the client can and refuses otherwise.

• harness_mode: auto with permission_answers: allow is effectively bypass.

• Both settings govern what a harness asks about. Some harnesses act without asking: Cursor CLI applies file edits on its own in either mode (docs/harnesses.md).

• The older permissions: auto | allow_all | deny_all | elicit still works as a shorthand for a pair (auto + deny, ask + allow, ask + deny, ask + elicit).

throng never answers "always allow", so no rule gets written into the agent's project settings. Per-harness overrides, extra env for an adapter, timeouts and the nesting limit are in docs/configuration.md.

What leaves your machine

throng makes no network requests of its own and sends no telemetry. It runs the agent CLIs you installed and logged in to, and each of them sends the prompt and the files it reads to its own model provider, under your account. The calling agent picks the harness from the ones you installed, and what a nested agent may do comes from the config above. With npx, the package comes from the npm registry on the first start.

On disk throng keeps one record per session in ~/.cache/throng/sessions/: harness, model, effort, working directory, a short description and the last result or error. The server deletes records older than 14 days when it starts. It keeps no transcripts: each harness logs its own sessions.

Documentation

• docs/configuration.md: the config file, environment variables, permissions in detail, auth, troubleshooting.

• docs/harnesses.md: how each harness behaves under throng, its limits and quirks.

• DESIGN §3: the exact inputs, results, error codes and stop reasons of every tool.

• skills/throng/SKILL.md: working patterns for the calling agent.

• docs/development.md: for maintainers; tests, smoke runs against real harnesses, files on disk.

• Agent Runbooks: multi-step procedures a session runs through subagents. Any step of a runbook can go to any harness through throng.

License

MIT, see LICENSE.