Throng MCP README

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.

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.

claude plugin marketplace add agent-runbooks/throng-mcp
claude plugin install 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 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.

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

  TerminalCopy

  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

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

opencode auth login

npm i -g @google/gemini-cli
gemini

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

npm i -g @github/copilot
copilot login

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, or throng-mcp after a global install.

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

codex mcp add throng -- npx -y throng-mcp

{
  "mcp": {
    "throng": {
      "type": "local",
      "command": ["npx", "-y", "throng-mcp"],
      "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

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.

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.