Skip to main content
Glama
ppetko98

cursor-dispatcher

by ppetko98

cursor-dispatcher

License: PolyForm Noncommercial 1.0

An MCP server + Claude Code plugin that lets Claude spawn Cursor subagents as async, bounded workers.

Claude delegates a task, gets a run_id back immediately, and continues talking to the user. When the subagent finishes, a plugin hook injects the outcome into Claude's next turn — no polling, no blocked chat.

The original design spec lives in PRD.md.


What it does

  • Spawn Cursor subagents on demand (spawn_subagent).

  • Message them mid-run via --resume=<chat_id> (send_subagent_message).

  • Stream their NDJSON events to disk as they run (readable via get_subagent_events or the subagent://<run_id>/events MCP resource).

  • Synthesize a structured completion payload — status, summary, artifacts (file edits + shell tool calls with stdout/stderr) — via get_subagent_result.

  • Cancel, list, prune.

  • Retain run history under ~/.claude-cursor-harness/ with tiered compression (7d → gzip, 14d → delete) and an LRU cap.

  • Notify Claude asynchronously via an UserPromptSubmit hook so subagent completions surface without polling.

  • Preflight cursor-agent auth on startup + every spawn; refuses with an actionable error if not logged in.


Related MCP server: cursor-mcp-server

Requirements

  • Node ≥ 20 (for the MCP server)

  • cursor-agent installed on $PATH, authenticated via cursor-agent login or CURSOR_API_KEY env var

  • Claude Code (for the plugin — hooks, skill, slash command)


Install

Public (via GitHub marketplace)

From inside Claude Code:

/plugin marketplace add ppetko98/cursor-dispatcher
/plugin install cursor-dispatcher@cursor-dispatcher
/reload-plugins

That's it — Claude Code clones the repo, wires up the MCP server, hook, skill, and slash command. You still need cursor-agent installed on $PATH and authenticated (see /cursor-login).

Local (for dev)

git clone https://github.com/ppetko98/cursor-dispatcher.git
cd cursor-dispatcher
npm install
npm run build

# From Claude Code:
/plugin marketplace add /absolute/path/to/cursor-dispatcher
/plugin install cursor-dispatcher@cursor-dispatcher
/reload-plugins

Then verify:

/mcp                     # cursor-dispatcher should be listed
/hooks                   # UserPromptSubmit → on-user-prompt.mjs
Skill: cursor-dispatcher:cursor-subagent
Slash: /cursor-login

Without the plugin (MCP-only)

If you only want the MCP tools without the hook + skill:

claude mcp add cursor-dispatcher -- node /absolute/path/to/cursor-dispatcher/dist/server.js

Usage (from Claude)

Typical delegation flow, driven by the shipped cursor-subagent skill:

  1. You: "have cursor scaffold a fastify server under ./demo."

  2. Claude: calls spawn_subagent({ prompt: "...", cwd: "...", permission: "auto" }) → returns run_id instantly. Tells you it's running and moves on.

  3. Subagent runs cursor-agent -p --output-format stream-json --resume-support in the background, streaming NDJSON events to ~/.claude-cursor-harness/runs/<run_id>/events.ndjson.

  4. You send any next message — the UserPromptSubmit hook scans for terminal transitions and prepends SUBAGENT <id> → completed — <summary> to your prompt.

  5. Claude sees the update inline in the very next turn and reports back with the outcome (files edited, shell output, etc.).

Follow-ups on the same run use send_subagent_message — it re-invokes cursor-agent --resume=<chat_id> so the subagent picks up where it left off.


Permission model

The harness maps the parent Claude session's own posture to Cursor's approval flags:

permission value

Cursor flags

When to pick

read

--mode ask (no --trust)

Parent Claude is in plan / read-only mode. Subagent cannot write files or run shell commands.

auto (default)

--trust --auto-review

Default. Server-side classifier auto-approves safe tool calls; unsafe ones would prompt (and effectively hang in headless mode).

trust

--trust --yolo

Fully autonomous. Use only when the user has explicitly said "let it rip."

Model must come from an allowlist (default: auto, gpt-5.2, claude-opus-5-thinking-high, claude-opus-4-8-thinking-high, composer-2.5). Working directory must live under a configured root (default ~/workspace).


MCP tools

All tools live under the cursor-dispatcher MCP server.

Tool

Purpose

spawn_subagent

Launch a new subagent. Returns { run_id, chat_id?, status } immediately.

send_subagent_message

Send a follow-up message to a run (resumes the same Cursor chat).

get_subagent_status

Cheap poll: status + last event id + current turn.

get_subagent_events

Fetch NDJSON events since a given event_id.

get_subagent_result

Terminal-run completion payload: { status, summary, artifacts: [{ type, ref, metadata }] }.

list_subagents

Filterable list of runs known to the harness.

cancel_subagent

SIGTERM the child.

prune_subagents

Manual cleanup: { compress_after_days?, max_age_days?, keep_last?, dry_run? }.

Resources are exposed at subagent://<run_id>/status and subagent://<run_id>/events, with notifications/resources/updated fired on each new batch of events.


Configuration

Precedence: env var > ~/.claude-cursor-harness/config.json > built-in defaults.

Example config file:

{
  "runtime": { "cursorBin": "cursor-agent" },
  "policy": {
    "models": ["auto", "gpt-5.2"],
    "defaultModel": "auto",
    "cwdRoot": "/Users/you/workspace",
    "sandbox": "enabled"
  },
  "retention": {
    "compressAfterDays": 7,
    "maxAgeDays": 14,
    "maxRuns": 200,
    "pruneOnStartup": true,
    "pruneOnSpawn": true
  }
}

Env-var overrides:

Env

Config path

CURSOR_HARNESS_HOME

root data dir (default ~/.claude-cursor-harness)

CURSOR_HARNESS_BIN

runtime.cursorBin

CURSOR_HARNESS_MODELS

policy.models (comma-separated)

CURSOR_HARNESS_DEFAULT_MODEL

policy.defaultModel

CURSOR_HARNESS_CWD_ROOT

policy.cwdRoot

CURSOR_HARNESS_SANDBOX

policy.sandbox

CURSOR_HARNESS_COMPRESS_AFTER_DAYS

retention.compressAfterDays

CURSOR_HARNESS_MAX_AGE_DAYS

retention.maxAgeDays

CURSOR_HARNESS_MAX_RUNS

retention.maxRuns

CURSOR_HARNESS_PRUNE_ON_STARTUP

retention.pruneOnStartup

CURSOR_HARNESS_PRUNE_ON_SPAWN

retention.pruneOnSpawn

CURSOR_API_KEY

cursor-agent auth (bypasses login)


Retention

Each run's data lives under ~/.claude-cursor-harness/runs/<run_id>/:

runs/<run_id>/
├── meta.json                 # RunMeta (status, model, chat_id, session, summary, retention state)
├── events.ndjson             # NDJSON of every parsed cursor-agent event
├── messages.ndjson           # Parent ↔ subagent message log
└── artifacts/                # Reserved for future materialized outputs

Lifecycle:

  • 0–7 days: kept fully.

  • 7–14 days: events.ndjson and messages.ndjson gzipped in place. meta.json gains retentionState: "compressed", compressedAt, and a materialized summary so it stays self-describing. get_subagent_result still works — readEvents transparently gunzips.

  • >14 days: entire run dir deleted.

  • LRU: if more than maxRuns terminal survivors remain, the oldest (by endedAt) are deleted regardless of age.

  • Non-terminal runs are never touched.

Triggers: startup (registry.load), after every spawn_subagent, and on-demand via prune_subagents.


The plugin bundle

Under plugin/:

  • MCP server — same code that ships as dist/server.js.

  • Skill cursor-subagent (plugin/skills/cursor-subagent/SKILL.md) — teaches Claude the non-blocking pattern, permission mapping, and follow-up flow.

  • Slash command /cursor-login (plugin/commands/cursor-login.md) — walks the user through interactive login or CURSOR_API_KEY setup.

  • Hook UserPromptSubmit (plugin/hooks/on-user-prompt.mjs) — before each of your prompts, scans for new terminal transitions and injects a summary block. Filters to this Claude Code session where possible; falls back to reporting mismatched-session runs as [unlinked] so nothing is silently missed.


Development

npm install
npm run build          # tsc
npm test               # vitest (34 tests)
npm run lint           # tsc --noEmit

Repo layout:

src/
├── server.ts          # MCP stdio entrypoint
├── config.ts          # Config layer (env + config.json)
├── session.ts         # Per-server session id resolver
├── types.ts
├── runtime/
│   ├── runner.ts      # Cursor CLI child process
│   ├── registry.ts    # In-memory + disk-backed run registry
│   ├── storage.ts     # ~/.claude-cursor-harness/ layout + gzip helpers
│   ├── events.ts      # NDJSON parser, summary + artifact synthesis
│   ├── cleanup.ts     # Retention engine (compress/delete/LRU)
│   ├── auth.ts        # cursor-agent status preflight
│   └── notifier.ts    # MCP notifications helpers
├── tools/             # One file per MCP tool
└── policy/            # Model allowlist, sandbox, cwd whitelist
plugin/
├── .claude-plugin/plugin.json
├── skills/cursor-subagent/SKILL.md
├── commands/cursor-login.md
└── hooks/on-user-prompt.mjs
tests/

Known limitations

  • Session linking is loose. Claude Code doesn't expose a shared session id to child MCP servers, so runs stamped with the MCP server's random UUID rarely match the session id Claude Code injects into the hook. The hook falls back to reporting these as [unlinked] so nothing is missed — noisy if you run concurrent Claude sessions.

  • True mid-silence wake-up isn't possible. MCP notifications reach the client but Claude Code doesn't (currently) auto-invoke the model on them. Subagent completions surface on your next prompt, not asynchronously.

  • spawn_subagent requires a working cursor-agent + auth. No queueing, no retry. If cursor-agent isn't installed or not authenticated, the tool call fails with a clear message pointing at /cursor-login.


License

PolyForm Noncommercial 1.0.0 — free for personal, research, educational, hobbyist, and other noncommercial use (including noncommercial open-source projects, charities, and government/academic institutions). Commercial use, hosting-as-a-service, and repackaging for resale are not permitted. If you want to use this in a for-profit setting, open an issue to discuss a commercial license.

Note: "noncommercial" here does not meet the OSI's Open Source Definition (which forbids field-of-use restrictions); this is a source-available license.

Available Tools

8 tools
cancel_subagentA

Terminate a running subagent (SIGTERM).

ParametersJSON Schema
NameRequiredDescriptionDefault
run_idYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the mechanism (SIGTERM), which suggests graceful termination, but it doesn't explain side effects like cleanup, reversibility, or behavior when the subagent isn't running. Basic info is present but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with zero wasted words. It communicates the action and key detail (SIGTERM) without fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple process-control tool with one parameter and no output schema, the description is reasonably complete. It covers what the tool does and how (signal). It lacks explicit mention of return values or error scenarios, but these are less critical for such a straightforward operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description adds no explicit parameter guidance. However, the single run_id parameter is self-explanatory as an identifier, and its type is a simple string. The low complexity reduces the need for additional semantic exposition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Terminate') and resource ('running subagent'), and the signal (SIGTERM) adds precision. This distinguishes it from sibling tools like spawn_subagent or list_subagents, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies clear usage context: use when a subagent is running and needs to be stopped. The word 'running' implicitly excludes finished subagents, providing a basic exclusion, though no explicit alternatives are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_subagent_eventsA

Fetch NDJSON events emitted by a subagent since a given event id. Use for polling or to catch up after a notifications/resources/updated ping.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
run_idYes
since_event_idNo

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It adds value by revealing the output format (NDJSON) and the polling/catch-up use case, but it leaves gaps: it doesn't explain ordering, the inclusive/exclusive semantics of since_event_id, default limit behavior when limit is omitted, or what happens when no events exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two focused sentences. The first sentence states the core functionality and key parameter; the second gives usage context. No fluff, no repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple and the description covers its purpose, output format, and intended usage. However, with no output schema and no annotations, it should more thoroughly explain run_id semantics and limit behavior, and how run_id relates to other subagent tools. The absence of these details leaves an agent guessing on how to correctly construct a call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only hints at since_event_id ('since a given event id'). It doesn't explain run_id (how to obtain it, that it identifies the subagent) or limit (pagination/result size). The schema provides types and constraints but not semantic meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetch'), the resource ('NDJSON events emitted by a subagent'), and the key scope ('since a given event id'). It also naturally distinguishes this tool from sibling tools like get_subagent_status and get_subagent_result by focusing specifically on the event stream.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly identifies when to use the tool: for polling or catching up after a notifications/resources/updated ping. This gives clear contextual guidance, though it doesn't explicitly mention when not to use it or name alternative tools for exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_subagent_resultA

Return the final structured completion payload for a terminated run (status ∈ {completed, failed, cancelled, timed_out}).

ParametersJSON Schema
NameRequiredDescriptionDefault
run_idYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits. It does reveal an important constraint (only terminated runs produce a result), but it does not mention what happens for running runs, error behavior (e.g., run not found), or whether this is a read-only operation. It gives partial transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly worded sentence. It front-loads the action ('Return the final structured completion payload') and immediately follows with the condition for use. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple tool with one parameter and no output schema. The description covers the core behavior (returns final payload), the applicable statuses, and the structured nature of the output. It does not detail return values, but given the simplicity and sibling context, the description is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description does not elaborate on the run_id parameter. It only appears in the schema with a type and required flag. The parameter name is self-explanatory, but the description adds no additional meaning (e.g., format, how to obtain it), and the low coverage requires compensation that is absent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('Return') and resource ('final structured completion payload for a terminated run'). It also specifies the exact statuses that qualify, effectively distinguishing it from sibling tools like get_subagent_status and get_subagent_events.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: after a run has terminated (status in the listed set). It provides clear context for the expected state of the run, though it does not explicitly name alternative tools or explicitly state 'use this instead of get_subagent_status'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_subagent_statusB

Return the current status of a subagent run.

ParametersJSON Schema
NameRequiredDescriptionDefault
run_idYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden. It merely says 'Return the current status' without disclosing whether this is read-only, whether it polls, what constitutes 'status', or any side effects. The safety profile is implicit at best.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is minimally viable but incomplete. It does not describe the format or possible values of the 'status' return, nor does it offer usage guidance. It is adequate but leaves gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the single parameter 'run_id' is semantically clear from its name and the phrase 'subagent run'. The description does not explicitly map run_id to the identifier, but context makes it obvious. It adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Return') and resource ('the current status of a subagent run'). It communicates the core function, though it does not explicitly distinguish itself from sibling tools like get_subagent_result or get_subagent_events.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., get_subagent_result or get_subagent_events). There are no mention of prerequisites, context, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_subagentsB

List subagent runs known to this harness.

ParametersJSON Schema
NameRequiredDescriptionDefault
sinceNo
statusNo

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It only states 'List subagent runs known to this harness,' implying a read-only operation but giving no details about scope, pagination, result format, or any side effects. The phrase 'known to this harness' is vague and unexplained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one short sentence with no filler words. It conveys the core action efficiently and earnestly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool, the description is under-specified. It does not clarify the return value (e.g., run IDs, statuses, timestamps) or any filtering behavior beyond what the schema hints at. Without an output schema, this lack of context makes the tool's behavior ambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no meaning to the parameters. The 'since' parameter's semantics (since what? timestamp? run index?) are unclear, and 'status' only lists enum values in the schema without explanation. The description fails to compensate for the lack of schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'list' with a clear resource 'subagent runs', making the tool's purpose immediately clear. It also distinguishes from siblings like get_subagent_status, which targets a single subagent, and prune_subagents, which implies removal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. It does not mention alternatives, exclusions, or typical use cases. The description merely states what it does without contextual direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

prune_subagentsA

Compress / delete old terminal runs. By default follows the retention config (compress after N days, delete after M days, LRU cap). Pass overrides to run a manual cleanup or set dry_run=true to preview what would happen.

ParametersJSON Schema
NameRequiredDescriptionDefault
dry_runNo
keep_lastNo
max_age_daysNo
compress_after_daysNo

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It explicitly discloses the destructive nature ('delete'), explains the default retention behavior, and highlights the dry_run safety feature. Some details like permanence or confirmation are missing, but the description is more informative than typical mutation tools.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action and quickly moves to overrides and dry_run. Every clause is meaningful and there is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description gives a good high-level understanding but lacks parameter-level detail and expected output/return behavior. Since there is no output schema, more explanation could help. However, the core purpose and safety preview are covered, making it minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It only explains dry_run and the concept of overrides, but does not clarify the meanings of keep_last, max_age_days, or compress_after_days. This leaves significant ambiguity for parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Compress / delete') and resource ('old terminal runs'), which is specific and distinguishes it from sibling tools focused on subagent lifecycle. It also mentions the retention config, adding context about default behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (for cleanup based on retention config) and when to use overrides or dry_run. It does not explicitly name alternatives, but no direct alternative exists among siblings, so the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send_subagent_messageA

Send a follow-up message to a running subagent (resumes the same chat). Errors if a turn is already in flight.

ParametersJSON Schema
NameRequiredDescriptionDefault
run_idYes
messageYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavior itself. It adds useful constraints such as 'resumes the same chat' and 'errors if a turn is already in flight', which go beyond the schema. However, it does not explicitly state side effects (e.g., that it mutates the subagent's conversation state) or any permissions required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the action and resource. Every word adds value, with no repetition of schema or redundant details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter send-message tool, the description covers the core behavior, the key error case, and the effect ('resumes the same chat'). No output schema exists, but the description does not need to explain return values. The main gap is lack of explicit permission or side-effect notes, but the tool's simplicity keeps it reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. The description mentions 'running subagent', which hints that run_id refers to that subagent, and message is the follow-up text. However, it does not explicitly map parameters to their roles, and the parameter names are already fairly self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Send a follow-up message'), the target ('a running subagent'), and the effect ('resumes the same chat'). It is distinct from sibling tools like spawn_subagent or cancel_subagent, which handle different lifecycle operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when you need to continue an existing conversation with a subagent. It does not explicitly name alternative tools, but the context ('running subagent') makes it clear this is for follow-ups, not initial spawns or status checks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spawn_subagentA

Launch a Cursor subagent with the given prompt. Returns immediately with a run_id; the subagent runs asynchronously. Model must be in the allowlist. Use get_subagent_events or subscribe to subagent:///events to observe progress.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory (must be under CURSOR_HARNESS_CWD_ROOT).
modeNoCursor mode. Defaults to 'agent'.
modelNoModel to use. Allowed: auto, gpt-5.2, claude-opus-5-thinking-high, claude-opus-4-8-thinking-high, composer-2.5.
promptYesInitial task prompt for the subagent.
sandboxNoSandbox mode. Defaults to 'enabled'.
permissionNoTool-approval posture. 'read' = read-only (forces --mode=ask if mode not set); 'auto' (default) = safe tools auto-approved via --auto-review + --trust; 'trust' = fully autonomous via --yolo + --trust. Choose based on the parent Claude session's own permission mode.
timeout_msNoPer-turn timeout in milliseconds.
context_filesNoFile paths to reference in the prompt.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It honestly explains the immediate return with a run_id, asynchronous execution, allowlist requirement, and how to observe progress. This provides strong behavioral context beyond a simple launch statement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short, purposeful sentences with no filler. The most important facts (launch, async, run_id) are front-loaded, and observation guidance is given next. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 params, async behavior, no output schema), the description covers the key elements: what it does, return value, allowlist, and how to track progress. It doesn't detail every side effect, but it's sufficient for effective use alongside the schema and sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are well-documented elsewhere. The description adds only a small amount of extra meaning (e.g., prompt, allowlist) but mostly doesn't need to, hence the baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Launch' with resource 'Cursor subagent' and 'give prompt', clearly stating the tool's core function. It also notes the asynchronous return of a run_id, which distinguishes it from sibling event/status/result tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implicitly establishes this as the tool to create subagents among siblings that manage them. It gives follow-up guidance ('Use get_subagent_events or subscribe...') and a precondition ('Model must be in the allowlist'), but lacks explicit 'when not to use' or alternative scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 8 tool updatesv0.1.0
    • First observedcancel_subagent
    • First observedget_subagent_events
    • First observedget_subagent_result
    • First observedget_subagent_status
    • First observedlist_subagents
    • First observedprune_subagents
    • First observedsend_subagent_message
    • First observedspawn_subagent

TDQS

A4/5.0
Disambiguation5/5

Each tool targets a distinct operation in the subagent lifecycle: spawn, message, status, events, list, cancel, result, and prune. There is no meaningful overlap between any pair; even status vs. result are clearly differentiated by current state vs. final completion payload.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (spawn_subagent, send_subagent_message, get_subagent_status, etc.). The verbs are specific and predictable, making the API easy to learn and navigate.

Tool Count5/5

Eight tools is ideal for a subagent dispatcher. Each tool earns its place by covering a distinct part of the lifecycle, and the count is neither thin nor bloated.

Completeness5/5

The set provides full lifecycle coverage: create (spawn), interact (send message), read (status, events, list), terminate (cancel), retrieve final output (result), and cleanup (prune). There are no obvious gaps that would hinder an agent using this server.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    MCP server that spawns autonomous Claude Code agents in GitHub repos, enabling task delegation with persistent state, multi-step workflows, and job monitoring.
    47
    94
    2
    Apache 2.0
  • 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.
    17
    1
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that lets any MCP-capable agent spawn and drive Claude Code sessions — effectively turning Claude Code into an orchestratable sub-agent fleet.
    255
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ppetko98/cursor-dispatcher'

If you have feedback or need assistance with the MCP directory API, please join our Discord server