MCP tools reference

The Roscoe MCP server (started by roscoe mcp) exposes 32 tools to Claude Code over stdio. They're grouped here by purpose. Tool names and input schemas are the canonical surface: anything not listed here is not part of the MCP contract.

All tools return JSON wrapped in MCP's content envelope. Error shapes are not uniform across groups:

• Run tools set isError only for genuine server failures and return { error } for user errors.
• Workflow-writer tools always set isError: true and return { error, code }, where code is a WriterErrorCode.
• test_workflow returns { ok: false, code, message }.

Treat code as the thing to branch on where a tool documents one, and don't assume ok: false is present. The grouping below mirrors apps/mcp/src/tools/*.ts.

Project scoping (cwd / global)#

Every tool below except the Docs group takes a scope input — exactly one of:

The MCP server is long-lived and project-agnostic; the scope tells each call where it applies. With cwd, the server resolves it to its enclosing git root, derives the project id, and isolates workflows + runs to that project. Two parallel calls with different cwds see different projects (per-call AsyncLocalStorage isolation). With global: true, there is no project: tools resolve from the global store, and runs are tracked in a shared global namespace. Workflow create/move tools may simply OMIT source — it defaults to repo when a repo source exists and global otherwise — so an explicit source: "global" is optional in global mode, while source: "repo" there returns no_repo_source.

Passing neither errors with CWD_REQUIRED; passing both errors with CWD_GLOBAL_CONFLICT. The server never silently guesses a project.

For brevity, the per-tool input tables below omit the scope row. Assume every project-scoped tool requires cwd or global.

Validation errors (returned as structured { error, code, cwd? }):

Cross-project access. Every run-lookup tool — get_run_status, advance_run, advance_consensus, advance_round_robin, advance_map, resume_run, cancel_run, get_run_history — compares the run's projectId to the caller's. A mismatch returns "Run not found." rather than leaking that the run exists in another project. Scope ownership is strict and symmetric: global-namespace runs (projectId = '', started with global: true) are reachable only by a global caller, and a project's runs only by that project's caller. This matches list_runs, which filters by the caller's exact project, so the by-id guard and the listing always agree.

The Docs tools (list_docs, get_doc, search_docs, ask_docs, answer_docs) are project-agnostic and do not take cwd.

Index#

Workflow CRUD#

list_workflows#

Lists all workflows from both Global and Project sources.

Returns: Array<{ id, name, description: string | null, source: 'global' | 'repo', shadowed: boolean }>

When the same id exists in both sources, repo wins and the global entry has shadowed: true. Cached agent prompts that assume single-dir lookups will silently start picking up repo workflows once a repo source exists — pass source: "global" to disambiguate.

get_workflow#

Returns the full workflow configuration.

Returns: the parsed WorkflowConfig plus a source field. When source is omitted, resolves repo-first if a project source exists.

create_workflow#

Writes a new workflow YAML file.

Returns: { id, source, path } on success, or { error, code, details? }. Validates schema + integrity before writing. code values: invalid_id, invalid_config, integrity_error, conflict, no_repo_source, io_error.

update_workflow#

Replaces an existing workflow's contents. Validates schema + integrity; refuses to write on either failure.

Returns: { ok: true, source, path } or { error, code, details? }.

delete_workflow#

Hard-deletes a workflow file. Requires literal confirm: true to actually delete, and REFUSES when another workflow references this one from a subworkflow node — returning { error, referencedBy } so you can see what would break. Pass force: true to delete anyway.

Returns: { ok: true, path, source }, { error, referencedBy } when referenced, or { error, code }.

list_workflow_references#

List workflows that reference the given workflow through a subworkflow node: the parents that would be orphaned by a delete, or left pointing at a dead id by a rename without a cascade. Call before delete_workflow or rename_workflow. The search covers every workflow on disk regardless of source, so source scopes nothing here; it exists only for input-shape consistency with the rest of this group.

Returns: { referrers: Array<{ workflowId, nodeId }> } — one entry per referencing subworkflow node.

move_workflow#

Move a workflow between Global and Project. Refuses if the target source already has the same id.

Returns: { ok: true, id, from, to, path } or { error, code }.

duplicate_workflow#

Copy a workflow to a new id (and optionally a new source). Updates the new file's name field to match to_id.

Returns: { id, source, path } or { error, code, details? }.

rename_workflow#

Rename the file stem AND update the name field on disk. Refuses if new_id already exists in the same source.

By default the rename cascades: every workflow whose subworkflow node points at the old id is rewritten to the new one. Pass rewrite_references: false to rename the file alone and leave those references pointing at an id that no longer resolves.

Returns: { id, source, path, rewritten, failed, rolledBack } or { error, code, details? }. rewritten lists the workflows updated, failed those that could not be, and rolledBack is true when a partial failure caused the whole rename to be undone.

Authoring helpers#

get_workflow_schema#

Returns the JSON Schema for the workflow YAML, the registered executor list (with their config keys), the model ids permitted by roscoe.yaml, and an authoring array of runtime gotchas worth reading before you write. Call this once before authoring a new workflow so you have the exact shapes your write will be validated against.

Returns: { jsonSchema, executors: ExecutorSummary[], models: { available, default } | { error } }.

validate_workflow#

Dry-run schema + integrity validation. No filesystem writes. Pass either the full config OR id (+ optional source).

Returns: { valid: true, errors: [] } or { valid: false, code, errors: string[] }.

lint_workflow#

Schema + integrity validation plus a non-fatal lint pass: dead states, unreachable transitions, models missing from roscoe.yaml. Same input shape as validate_workflow.

Returns: { errors: string[], warnings: { code, message, state? }[] }. Warning codes include dead_state, unreachable_state, unknown_model.

Run lifecycle#

start_workflow#

Start a workflow in MCP mode. Synchronously runs through any script / condition nodes, then pauses at the first AI or human node and returns a pendingStep.

Returns: { runId, status, url, workflow, narration, pendingStep? } plus the AdvanceResult cost fields, and hostHint when a metered desktop-chat caller hits a fan-out node. workflow is { id, name, description } and narration is a ready-to-send opening line naming the workflow and its live URL. pendingStep appears for any node that hands back — ai_agent, ai_judge, consensus, human, round_robin, map. url points at the run page on the active server (dev port or roscoe serve port) and is a deep link: it carries a ?project= query (?project=global for a global: true run, otherwise the run's projectId) so opening it auto-selects the matching workspace in the web UI. runId is alphanumeric-only so the URL survives markdown rendering in a chat client unescaped.

get_run_status#

Get the current status of a run, including any pending AI step.

Returns: the same { runId, status, url, pendingStep? } shape.

Important: if the returned status is paused and the pendingStep is for a human node, you must NOT call resume_run autonomously — display the prompt and validTransitions to the user as a numbered list and wait for their reply. Only ai_agent / ai_judge pending steps may be answered programmatically (via advance_run).

advance_run#

Provide Claude's response to a pending AI step. For ai_judge, the response must satisfy the configured validator (the JSON envelope shape the prompt asked for). For ai_agent, any response is accepted.

Returns: the updated AdvanceResult shape (status, optional pendingStep for the next pause).

advance_consensus#

Advance a consensus step that paused for a subagent-capable host (Claude Code / Cowork): spawn agentCount independent subagents (none sees another's answer), each on the pendingStep model and prompt (or, if the pendingStep carries an agents array, subagent i runs agents[i].prompt on agents[i].model), and return every raw response here.

A most-consistent (USC) node pauses twice, signalled by consensusPhase: generate (each subagent returns free-form prose, not a JSON envelope), then aggregate (one subagent picks the most consistent response and returns {"reasoning": "...", "index": N}). For gate/answer nodes Roscoe validates each verdict; if some fail and a fix could still change the outcome, the node re-pauses with consensusPhase: 'retry' and a reduced agents[] covering only the failed ones.

Returns: the updated AdvanceResult shape.

advance_round_robin#

Advance a round_robin step, keyed by the pendingStep's roundRobinPhase. When it's resolve (candidates need a model call), the pendingStep carries a single agents[0].prompt: run one subagent and return its text as result. Otherwise (first / contested) the pendingStep carries criterion, model, and matchups (each { id, a, b }): spawn one independent subagent per matchup, have it pick A or B (no ties) with a 0-100 decisiveness margin, and return verdicts keyed by matchup id. Submit verdicts as waves complete; the node re-pauses with any still-outstanding matchups (and, in contested mode, a reversed re-judge batch) until every matchup is in.

Returns: the updated AdvanceResult shape.

advance_map#

Advance a map step. The pendingStep carries agents (one { model, prompt } per subagent), agentCount, and mapPhase. Run exactly agentCount independent subagents on agents[i].model / agents[i].prompt and return each raw response here, in agent order, regardless of phase: extract (one subagent turns a free-text list into branch prompts, then the node re-pauses with them), map (one subagent per branch; an empty response is a failed branch), or reduce (one subagent synthesizes the branch outputs). After the map round, a configured reduce re-pauses the node once more if at least one branch succeeded.

Returns: the updated AdvanceResult shape.

resume_run#

Resume a workflow paused at a human node by supplying the chosen transition.

Do not call autonomously. A human node represents a required human decision point. When a run is paused at one, you must (1) display the node's prompt, (2) present the valid transitions as a numbered list, and (3) wait for the user to reply with their choice before calling this tool. Do not infer or assume the choice.

Returns: the updated run detail.

cancel_run#

Cancel a running or paused workflow. In-flight executor work (a running script worker or claude CLI/SDK call) is aborted so it stops promptly rather than finishing in the background, and the node the run was sitting on is finalized with the dedicated cancelled status (distinct from failed). Errors (not a no-op) if the run is already terminal.

Returns: the run detail.

Run observability#

list_runs#

List recent workflow runs, newest first.

Returns: an array of { id, workflowId, workflowName, status, startedAt, completedAt, source, workflowSource, kind }.

get_run_history#

Full per-node trace for one run, including child sub-runs (e.g. consensus agents).

Returns:

{
  run: {
    id, workflowId, workflowName, status,
    startedAt, completedAt, source, workflowSource, context,
    parentRunId,        // the parent run, when this is a subworkflow child
    childRunIds,        // subworkflow runs this run spawned
    awaitingChild       // { childRunId } while paused on a subworkflow node
  },
  nodes: Array<{
    id, nodeId, nodeType, status,
    startedAt, completedAt, durationMs, attempts,
    input, output, error,
    children: Array<{ id, nodeId, nodeType, status, ... }>
  }>
}

Verification#

test_workflow#

Execute a workflow end-to-end against the real runner and the real DB, then delete the run row in a finally block. Identical execution path to production runs; the only differentiator is kind: 'test' on the workflow_runs row, which keeps these out of user-facing run lists.

Returns (success):

{
  ok: true,
  finalStatus: 'completed' | 'failed' | 'cancelled',
  durationMs: number,
  nodeTrace: Array<{ nodeId, nodeType, status, input, output, error, children, ... }>
}

Returns (failure): { ok: false, code, message, nodeId?, nodeType?, finalStatus?, durationMs?, nodeTrace?, details? }. code values: invalid_input, workflow_not_found, invalid_config, missing_mock, timeout, runner_error, fanout_in_test_mode_unsupported, unexpected.

Limitations and warnings:

• Every fan-out node — consensus, round_robin, map, and subworkflow (whose child may itself fan out) — calls the live Anthropic API directly and cannot be mocked. Workflows containing one are rejected with fanout_in_test_mode_unsupported unless ANTHROPIC_API_KEY is set, in which case real API spend will occur. The classification comes from the shared findFanoutNode, so a new fan-out node type is covered here and in start_workflow's gate from one definition — do not re-list the types by hand, which is how round_robin was once missed.
• The same rejection fires when the workflow config cannot be read.
• timeout_ms cannot interrupt a single non-yielding script — set the script's own timeout for that workload.
• The runner sweeps orphaned kind: 'test' rows on MCP startup (gated on ROSCOE_SWEEP_TEST_RUNS=1, set automatically by the MCP entry point).
• Mocks are required for any ai_agent, ai_judge, or human node the run reaches. Missing mocks fail fast with code: 'missing_mock' rather than hanging.

Skill import#

Convert markdown skills (the Agent Skills open standard — SKILL.md files with name + description frontmatter, optionally bundled with helper scripts) into Roscoe workflows. Works across Claude Code, Codex CLI, OpenCode, Gemini CLI, Cursor, and other harnesses that follow the standard.

list_skills#

Find skill candidates by content signature across the standard skill roots plus the current repo tree. A skill is any .md file whose YAML frontmatter contains both name: and description: (and is not a Jekyll/Hugo blog post).

Scan roots checked (in order):

• User-global: ~/.claude/skills/, ~/.agents/skills/, ~/.codex/skills/ (honors $CODEX_HOME), ~/.config/opencode/skills/, ~/.gemini/skills/
• Project-local (walks up to git root): .claude/skills/, .agents/skills/, .opencode/skills/
• Fallback: the repo tree, walked to a depth of 6. It does not consult .gitignore — the only exclusions are a fixed set: .git, node_modules, dist, build, .next, .turbo, .nx, coverage, .cache. Skipped entirely when content_scan: false.

Returns: { count, skills: Array<{ path, name, description }> }.

convert_skill + finalize_skill_conversion#

Convert one skill into a Roscoe workflow, in two steps so the conversion runs on your Claude subscription (the host runs the completion) rather than the Roscoe server calling a model. Bundled scripts/ are copied alongside the workflow and reachable from script nodes via $ROSCOE_WORKFLOW_DIR. Out of scope: references/, examples/, assets/ folders are detected and reported but not bundled. For a worked walkthrough, see Import a workflow from a skill.

Step 1 — convert_skill resolves the skill, reads its bundle, and returns a converter prompt for you to run as your own completion. It makes no server-side model call.

Returns a handback: { action: 'run_completion', prompt, model, finalize_args }. Run prompt yourself, then pass the raw output plus finalize_args to finalize_skill_conversion. (Resolve failures return { ok: false, stage: 'resolve', message }.)

Step 2 — finalize_skill_conversion takes your completion and writes the workflow. It re-reads the skill bundle from skill_path, so nothing you echo back is trusted as a write source.

Returns: { id, source, path, assetCount, skippedBundleDirs, skippedNote? }. Failure shape: { ok: false, stage, message } where stage is one of resolve, parse, validate, write. On parse/validate, the response includes rawModelOutput so you can re-run the prompt or repair — do not fabricate a workflow to force success.

Conversion guidance the prompt gives the model:

• Use {{ nodeId.field }} template interpolation whenever a step references "the previous result", "the gathered context", etc.
• A reference is only valid if the producing node runs on every path that reaches the consuming node (dominance check). Branching workflows must reference a node both branches converge through, or use a fallback like {{ nodeId.field || "default" }}.
• Default to ai_judge for routine routing; reach for consensus (3-5 agents with a quorum) for high-stakes decisions (production deploys, security severity, migration safety).
• Cycles (verify → fix → re-verify) must have maxIterations on at least one participating node, unless a human node sits in the loop.

Docs#

The docs tools cover three retrieval modes plus a synthesized Q&A wrapper. Pick by intent:

list_docs#

Returns the flat manifest [{ slug, title, description }] for every doc page on disk.

get_doc#

Fetch the full markdown body for one slug.

Returns: { frontmatter, markdown } or { error }.

search_docs#

Full-text search across all docs.

Returns: ranked hits, each with a headingId and a snippet of up to ~80 characters either side of the match — call get_doc (or ask_docs for richer context) for the full body.

ask_docs#

Knowledge-base retrieval. Takes a natural-language question and returns the most relevant heading sections (the markdown from a heading down to the next equal-or-higher heading), packed within a character budget. Designed for LLM hosts that want enough grounded context to answer the question themselves.

Returns:

{
  question: string;
  sections: Array<{
    slug: string;
    title: string;
    headingId: string | null; // null = page lede
    headingText: string | null;
    text: string; // full section markdown (mermaid + code preserved)
    score: number;
  }>;
  truncated: boolean; // true if more candidates were dropped to fit budget
  totalChars: number;
}

The headingId matches the id rehype-slug produces in the rendered DOM, so /docs/${slug}#${headingId} is a valid deep link.

answer_docs#

Q&A packaging. Internally calls ask_docs, then returns a citation-required prompt for you to answer yourself — it makes no server-side model call, so the answer runs on your Claude subscription. Present your answer with the returned citations. LLM hosts that just want the raw source should prefer ask_docs.

Returns:

{
  action: 'answer_prompt';
  instructions: string; // answer `prompt` yourself, cite `citations`
  prompt: string; // the citation-required answer prompt to run
  model: string; // suggested model id
  citations: Array<{
    slug: string;
    title: string;
    headingId: string | null;
    headingText: string | null;
  }>;
}

Failure modes:

• Empty/whitespace question → error.
• Zero relevant sections in retrieval → error (the tool refuses to hand back a prompt with no source; fall back to ask_docs to inspect the empty retrieval).

AdvanceResult shape#

The shared shape returned by start_workflow, get_run_status, advance_run, advance_consensus, advance_round_robin, advance_map, resume_run, and cancel_run:

{
  runId: string;
  status: 'running' | 'completed' | 'failed' | 'paused' | 'cancelled';
  url: string;          // deep link: /open/runs/<id>?project=<projectId|global>
                        // — /open hands the run to the desktop app when it is
                        //   installed, and falls back to the browser otherwise
  pendingStep?: {
    runId: string;
    nodeId: string;
    nodeType: 'ai_agent' | 'ai_judge' | 'consensus' | 'human' | 'round_robin' | 'map';
    prompt: string;     // full prompt — Claude reads this, calls advance_run
    validTransitions: string[];
    label?: string;               // the node's human-readable name
    transitions?: { event: string; target: string; targetLabel?: string }[];
    agentCount?: number;          // consensus: how many subagents to spawn
    model?: string;               // consensus + round_robin: the model to use
    agents?: { model: string; prompt: string }[];  // per-agent diversity
    consensusPhase?: string;      // generate | aggregate | retry
    criterion?: string;           // round_robin: what to judge on
    matchups?: RoundRobinMatchup[];
    roundRobinPhase?: string;
    mapPhase?: string;
  };
  // plus the cost fields: totalCostUsd, meteredCostUsd,
  // subscriptionEquivCostUsd, billingMode, inputTokens, outputTokens
}

Where to next#

• Using Roscoe over MCP — the same surface as a walkthrough, including how to connect a host to it.
• CLI commands — roscoe mcp itself, and the commands that share this server's data.
• REST API — the HTTP surface behind the same runs and workflows.
• Workflow sources — what source and the global-vs-repo split mean for every tool above.
• Subscription vs metered — what host decides, and why fan-out nodes hand back instead of calling the API.