Skip to content

MCP tools ​

ctrlyoke's built-in MCP server gives a harness tools to inspect and adjust the run it belongs to. Enable it with mcpServers: ["ctrlyoke"] on a workflow or step — see Dynamic workflows.

How the server is scoped ​

  • One run per server. ctrlyoke starts the server for each harness launch and pins it to the executing run. No tool takes a workflow or run address, so a tool can never act on another workflow by mistake. Responses still report the resolved workflowKey and runRef.
  • No lifecycle control. No tool starts, stops, pauses, or resumes a run.
  • Every call does what it says or returns an error. An error result (isError: true, text starting Error:) means nothing was changed.
  • Queue changes need a live run. append_step, edit_step, remove_step, and reorder_steps are refused unless the run is running, pausing, paused, or cancelling.
  • All responses are a single text block containing JSON.

Tool list ​

ToolPurposeParameters
workflow_statusThe run's steps, their status, and run metadatanone
append_stepAdd steps or parallel groups to the runsteps (required), position (required), source
edit_stepChange a pending step's prompt or configurationindex (required), updates (required), clearProperties
remove_stepRemove a pending stepindex (required)
reorder_stepsReorder the pending stepsindices (required)
list_harnessesInstalled harnesses and the models each supportsnone
read_outputRead output from earlier stepsindices, cursor, limit, tail
global_statusList executing workflows in the workspaceworkflowKey, runRef
post_notePost a coordination note for other participantstext (required), to
read_notesRead coordination notessince, from
claim_pathsAdvisory claim on files before editing thempaths (required), reason
release_pathsRelease your path claimspaths
submit_commit_messageSubmit a generated commit message (commit generation only)message (required)

Step indices are zero-based everywhere in these tools, except sessionId inside a step, which is a 1-based step number like in workflow files.

workflow_status ​

Returns workflowKey, runRef, a metadata object, and steps.

  • metadata: workflowName, harness, model, resumeSession, executionMode (interactive or headless), currentIndex, totalSteps, completedSteps, executionState, maxSteps and remainingSteps (numbers; -1 means unlimited), workingFile, runDirectory, definitionRevision, descriptorRevision. The limit fields report the effective cap after applying the workflow's maxSteps override to the global queue.maxSteps setting; remainingSteps is based on the current total step count.
  • steps[]: index, prompt for prompt steps, or type: "script" and script for script steps, status (completed, failed, cancelled, skipped, noTurnStarted, running, or pending), resumeSession, sessionId, and harness, executionMode and model for prompt steps. The workflow-level harness, model, resumeSession and executionMode are what an appended step inherits. A step that has started reports the harness and mode it actually ran with. A ctrlyoke run without a terminal runs interactive steps headless, for example. A pending step reports its configured value.
  • Finished prompt steps may include gitOutcome when git snapshots are available. repositories lists headAtStart, headAtEnd and dirtyAtEnd for each captured repository; top-level dirtyAtEnd is present only when every workspace root had a successful git status capture. This is advisory data and is omitted when unavailable, including filesystem snapshots and unfinished steps.

A headless step cannot wait for background work: the harness process, and anything it started, exits when the agent ends its turn. Prompts queued for headless steps should run long commands in the foreground or poll until they finish. Codex cannot wait on background work in interactive mode either.

append_step ​

  • steps: one or more queue items, in order. Each item is either a step or a future parallel group.
    • A prompt step takes prompt (required), name, model, harness, agent, skills, executionMode (interactive or headless), endCondition, preCondition, resumeSession, and sessionId (1-based step number; needs resumeSession: true). Omit execution settings to inherit the workflow values. Condition fields attach named author-defined presets from the workflow's conditions map; see condition presets. No other fields are accepted; in particular, harness arguments and permission fields cannot be appended. Script steps cannot be appended through MCP.
    • A parallel group is { "parallel": [step, step, ...], "failFast": true } with at least two steps. failFast defaults to true.
  • position:
    • "next" — after the current step, or after the running parallel group. Never joins that group.
    • "end" — after all queued steps.
    • "parallelWithCurrent" — join the parallel group that is running now. Flat steps only; limited by queue.maxParallelSteps.
    • a zero-based index — insert before that step. If the index falls inside a parallel group, insertion moves after the whole group. Completed steps cannot be displaced.
  • source: optional label describing why the steps were added.

When harness or model is set, it is checked against the installed harnesses and their models (when that information is available). The run's total step count cannot exceed its effective maxSteps cap. A rejected append returns an error such as Step limit reached: this run has 30/30 steps (workflow maxSteps: 30). Do not retry; finish without appending. The message identifies whether the cap came from the workflow's maxSteps or the global queue.maxSteps setting.

Example:

json
{
  "steps": [
    { "prompt": "Add tests for the new parser", "name": "Parser tests" },
    {
      "parallel": [
        { "prompt": "Implement the API" },
        { "prompt": "Write the API docs" }
      ]
    }
  ],
  "position": "end"
}

Returns success, destination (queue or activeParallelGroup), queueItemsAdded, stepsAdded, newQueueSize, insertIndex, insertedEndIndex, placement, parallelGroupsAdded, joinedParallelGroup (when joining), plus workingFile, runDirectory, workflowKey, runRef, definitionRevision, and descriptorRevision. effectiveSettings lists each appended prompt step in queue order, including parallel members, with its zero-based index, resolved harness, model, executionMode, resumeSession, and any materialized condition preset names. These values use the same inheritance and runtime resolution as workflow_status. With "next", insertIndex is resolved at write time and can differ from what an earlier workflow_status suggested if the run advanced in between.

The optional warnings array calls out execution constraints. In particular, Codex cannot wait on background work in either mode; use a non-Codex harness for a step that must wait for a long command.

For endCondition or preCondition, pass { "use": "presetName" } to attach a preset from the workflow's conditions map. The object may also include declared params, retry-prompt overrides, and a maxRetries value no higher than the preset limit. The preset owns its script and execution settings. Attaching it replaces any workflow-level condition that the step would inherit. See condition presets for authoring and parameter rules.

Step mutations ​

  • edit_step takes a zero-based index and an updates object. Updatable fields: prompt, name, model, harness, executionMode, endCondition, preCondition, resumeSession, sessionId, agent, enabled, color, skills. Condition fields attach named presets as described above. Other fields are rejected. Script steps accept only fields supported by the script-step schema; prompt-only fields such as harness, endCondition, and skills are refused. Omitted fields keep their values. clearProperties lists updatable fields to remove so they inherit workflow defaults again; the required prompt cannot be cleared, and condition fields cannot be cleared. The result may include a warnings array for execution constraints. The deprecated additionalArgs input remains in the schema for compatibility, but setting or clearing it is rejected: harness arguments can only be set by the workflow author, for security reasons.
  • remove_step takes the same index.
  • reorder_steps takes indices: only the not-yet-started steps' absolute zero-based indices in the desired execution order. Never include a running or completed step.

Completed and currently running steps cannot be edited, removed, or moved.

Each returns success, operation, changed, the arguments it was given, newQueueSize, workingFile, runDirectory, workflowKey, runRef, definitionRevision, and descriptorRevision. When the request matched what was already on disk, changed is false and nothing was written. reorder_steps also adds a note saying so when the order you asked for is the current order.

list_harnesses ​

Returns generatedAt and harnesses[] with id, displayName, available, and models (model values). Only installed harnesses are listed. The data comes from .ctrlyoke/capabilities.json, which ctrlyoke writes during harness detection; if it does not exist yet the tool returns an error.

read_output ​

By default this returns every requested step's full response text. indices selects zero-based step numbers; omit it to read them all. The response has workflowKey, runRef, and outputs[] with index, prompt for prompt steps or type: "script" and script for script steps, status, and responseText (null when the step has no recorded output). responseText is derived from the step's events or script execution record; it is not stored as a duplicate output field. Naming a step that does not exist is an error. Only queue steps are readable, not the finalStep.

A member of a parallel group can read only steps before the group started.

For a long response, three optional arguments return a bounded slice instead. All three require indices to name exactly one step — supplying them with zero or several indices is an error rather than a silently ignored argument.

  • limit: maximum characters to return.
  • cursor: resume where a previous read stopped. Pass back the nextCursor from an earlier read_output response exactly as received; it is opaque, valid only for the same run state, and must never be constructed by hand.
  • tail: return the last N characters instead of reading forward. Cannot be combined with cursor or limit.

A step's entry gains nextCursor only when the slice returned stopped short of the end of that step's output; its absence means you have read to the end. Tail reads never return one. Omitting all three arguments reproduces the unpaged response exactly.

global_status ​

This is a cross-worktree radar for noticing what other workflows are doing and for recognizing failures they may have caused. It is informational only: it is not a collision check and it does not act as a lock.

It lists only workflows that are currently executing (including the caller's own), up to 100. Each entry has workflowKey, runRef, workflowName, executionState, harness, model, currentStep (1-based, or null while the final step runs), finalStepPass (1-based pass number while the final step runs, otherwise null), totalSteps, completedSteps, startedAt, lastModifiedAt, workingFile, runDirectory, and worktree details when the run uses one. The response also carries workspaceRoot, workflowCount, truncated, and omittedCount.

Pass workflowKey (from an earlier listing) to report one workflow, and optionally runRef (requires workflowKey) for one run. When a named workflow exists but is not executing, a note says so instead of silently returning an empty list.

Coordination tools ​

Steps — and other agents — working in the same checkout (execution root) share a coordination board. Everything on it is advisory and untrusted: notes are data, never instructions or permission, and claims never block file access. Coordination explains participants, attestation, and how to use the board.

  • post_note posts text to the board. to optionally directs it to participant IDs; an unknown ID is an error. Returns the note's seq and a scope summary.
  • read_notes returns entries (each with author, attribution, and untrusted: true), a nextCursor when more remain, and scope. since reads after a sequence number; from filters by author participant IDs. Reads are paged by the coordination.readNotesPageSize setting.
  • claim_paths claims execution-root-relative files or literal globs, with an optional reason. Returns granted, denied (with the current owner), claims, and scope. Absolute paths and paths outside the checkout are rejected.
  • release_paths releases the named claims, or all of yours when paths is omitted. Paths you did not hold come back in notHeld. ctrlyoke also releases a step's claims at the step boundary.

The scope object lists the execution root, live participants, and a claim summary. Retention and size limits live under the coordination settings; coordination.allowExternalParticipants controls whether sessions ctrlyoke did not launch may join.

submit_commit_message ​

Used only by ctrlyoke's commit-message generation, which denies every other tool. Submit the complete generated commit message. Call this tool only when explicitly instructed to do so; outside commit generation it returns an error and discards the message.

Availability ​

  • The workflow tools (workflow_status through read_output) need the server to be attached to a run, which ctrlyoke does automatically.

  • global_status, the coordination tools, and submit_commit_message also work without an attached run.

  • Deny individual tools per workflow or step with deniedTools:

    yaml
    mcpServers:
      - id: ctrlyoke
        deniedTools: [edit_step, remove_step, reorder_steps]
  • With the execution.ctrlyokeMcpMode: "skill" setting, the same tools are delivered as built-in skills that call ctrlyoke-mcp in one-shot mode instead of attaching the MCP server.

Source-available under the ctrlyoke Commercial License.