Skip to main content
Glama

polyagent-mcp

Give your coding agent a team of cheaper workers. polyagent-mcp is an MCP server that lets your main agent hand work to other coding-agent CLIs (Codex, Claude Code, Grok, OpenCode, …) and get back only the answer, not the worker's raw output.

It does not replace your agent or its harness. It adds to it: cheaper web lookups, delegated implementation, cross-model second opinions, and filtered build/test output.

Status: v0.5, used daily by its author. Works in any MCP host; the best-tested setup is Claude Code. Linux today, macOS is the next goal (see Roadmap).

Why

Claude Code has one of the best agent harnesses available, so the research behind this project starts from it instead of fighting it. The harness is great; the expensive part is spending the top model's tokens on work a cheaper model does just as well: reading large files, searching the web, running noisy test suites, doing a self-contained edit.

polyagent-mcp routes that work to the model with the best cost/quality trade-off:

  • Models are placed on a Pareto line built from public intelligence benchmarks and local measurements (method and results). Today that puts mostly Codex models behind delegate.

  • Three named levels (low, middle, high) hide the model choice from the caller.

  • Every tool is designed for context economy: the worker's raw output never enters your agent's context. bridge_stats reports how much did.

The goal is better cost-efficiency, not just lower cost. Honest limits of what has and has not been measured are in docs/evidence.md.

Related MCP server: subagents

What you get

Tool

Use it to

delegate

Hand a self-contained task (feature, bugfix, build fix) to a worker with read/edit/shell access.

explore

Map or search a codebase read-only; get file:line references back.

read_slice

Read only the relevant lines of a big file.

run_filtered

Run a noisy command and keep only the signal.

web_lookup

Look up docs, errors and current versions on the web, cheaply.

fan_out

Get independent opinions from 2+ models and cross-check a risky call.

follow_up

Continue a worker session by session_id.

rate, bridge_stats

Grade results and see per-tool usage.

decide, generate_image

Calibrated yes/no probabilities; image generation via Codex.

Full parameters, levels and quota behavior: docs/tools.md.

Quick start

You need Node ≥ 18, bubblewrap (Linux), and at least one authenticated worker CLI. Codex is the primary engine for all three levels; Claude Code is the reserve when Codex is missing, unhealthy or out of quota.

git clone https://github.com/JaimeJunr/polyagent-mcp.git
cd polyagent-mcp
npm install && npm run build

# Claude Code
claude mcp add polyagent -s user -- node "$(pwd)/dist/index.js"

Any other MCP host: add this to its mcp.json.

{
  "mcpServers": {
    "polyagent": { "command": "node", "args": ["/abs/path/to/polyagent-mcp/dist/index.js"] }
  }
}

Using an AI agent to install it? Point it at INSTALL.md: a step-by-step guide for Claude Code, Cursor, Codex, Grok and generic hosts, including the permission allowlist.

Registering the tools is not enough: hosts tend to prefer their native Read/Grep/WebSearch. Three optional pieces make the agent actually use polyagent, strongest first:

  1. a PreToolUse hook that nudges at the moment of the native call,

  2. a managed CLAUDE.md routing block (npm run install-claude-md),

  3. a managed on-demand skill (npm run install-skill).

Details: docs/steering.md.

Will it save you anything? Run the doctor

npm run doctor

It lists the engines it found, tells you in plain words whether this setup saves anything ("saves host cost on medium or larger tasks" or "does not save quota: the worker uses the same subscription as the host"), and measures the fixed context cost of the install. With only Claude installed the levels fall back to the host's own subscription, so delegating saves nothing there. Numbers behind the verdict are host API-cost proxies; subscription quota savings are not demonstrated.

Documentation

Doc

Contents

docs/tools.md

Every tool, the three levels, quota behavior

docs/configuration.md

All environment variables

docs/steering.md

Hooks, CLAUDE.md block and skill

docs/evidence.md

What has and has not been measured

INSTALL.md

Agent-friendly install guide per host

research/

One dated study per design decision

CLAUDE.md

Architecture and invariants (read before changing code)

Safety

delegate and run_filtered give the worker full access and auto-approve its actions inside cwd. Every engine runs in a mandatory bubblewrap sandbox with an empty $HOME, so your global config, MCP servers, hooks and skills never load. delegate also accepts a deny list (for example git push, rm) as a guardrail against accidents; it is not a security boundary. explore, read_slice and web_lookup are read-only.

Roadmap

  • macOS and optional sandbox. The sandbox is Linux-only (bwrap) and mandatory today. Supporting macOS is a goal; see the open issues.

  • Publish to npm so npx works without cloning.

  • More worker engines and keeping the Pareto line current as models ship.

Contributing

Contributions are welcome: bug reports, new engines, benchmarks, docs. Start with CONTRIBUTING.md.

License

MIT

Available Tools

3 tools
delegateA

Delegate a task to the Cursor CLI agent running headless (agent -p). Cheap/fast worker with full tool access (read, edit, shell) in cwd. Use for routine implementation, edits, and tasks where a cheaper model is enough.

Inputs: prompt (required), cwd, model, effort.

exploreA

Read-only codebase exploration, the cheap counterpart to Claude's Explore. Two modes: omit files to get a general project map (layout, modules, entry points, build/test, conventions); pass files to answer a question about those specific files. Either way the code never enters your context — only the answer does.

Inputs: question, files, cwd, model, +1 more.

follow_upB

Continue a previous Cursor session by session_id (returned by every other tool). The prior context lives on Cursor's side, so you don't resend it.

Inputs: session_id (required), question (required), cwd, model, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: delegate is for task execution, explore for read-only exploration, and follow_up for continuing sessions. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names use verb-style in lowercase, with follow_up using an underscore for the two-word name. The pattern is consistent and predictable.

    Tool Count5/5

    With 3 tools covering core operations (task delegation, codebase exploration, session continuation), the count is well-scoped for a bridge server and neither too sparse nor excessive.

    Completeness4/5

    The tool set covers the primary interactions with the Cursor CLI agent. A minor gap is the lack of session listing or cancellation, but the essential workflows are complete.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server wrapping the Cursor CLI agent, enabling Claude Code and other MCP clients to delegate tasks to Cursor's AI agent for file writing, bash commands, and codebase queries.
      -
    • A
      license
      Not graded
      quality
      F
      maintenance
      An MCP server that enables Cursor to delegate complex, multi-step tasks to specialized subagents, including general-purpose and explore agents, with automatic discovery of existing Claude subagents.
      5 npm
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A fast, hardened MCP server that lets any MCP host drive the Cursor Agent CLI for heavy repo-aware tasks like search, analysis, planning, and edits, keeping host context small and token costs low.
      10
      1
      MIT