MCP tool reference

Call this first. Returns the server name, version, and the bootstrap steps for starting a workflow.

No session required. Use list_workflows to see what you can run.

Lists every workflow the server can run, with id, title, version, and tags.

If some workflow files cannot be loaded, you still get the working entries plus a load_errors list for the failures.

Quick ping to confirm the server is up. Returns status, name, version, workflow count, and uptime.

No session required.

Opens a new workflow session or resumes an existing one.

Returns a session_index (six characters), basic workflow metadata, and planning_folder_path — the absolute path agents should use for session artifacts (host bind path under Docker when HOST_PROJECTS_ROOT is set; server-local path under stdio).

Pass planning_folder as any absolute path whose basename is your planning slug (for example, .../planning/2026-05-28-my-slug). Only the slug is used; the server resolves it under its own workspace. A stale or wrong path prefix is harmless.

If that slug already has session.json, the session resumes and workflow_id is ignored. Otherwise the server creates a fresh session and seeds variables from the workflow defaults.

Omit planning_folder to start a meta bootstrap session in a temp folder. Use dispatch_child later to promote it to a real planning folder.

Child workflows are started with dispatch_child, not start_session.

Returns whether the session is active, blocked at a checkpoint, or completed, plus the current activity and completed steps.

If the session is nested under a parent, parent context is included too.

Read-only look at a session's stored state. Pick a view: summary (everything), identity, variables, checkpoints, activities, history, or children.

Returns a compact, purpose-built projection — never the raw session file.

Pass child_index to look one level into a child session listed under triggeredWorkflows; pass variable with view: variables to read a single value.

It never changes anything and works even while the session is paused at a checkpoint — which is often exactly when you want to look.

Starts a child workflow inside the parent session you are already in.

Returns the child's session_index and planning_folder_path. The child's variables are seeded from the child workflow's defaults; the parent is unchanged.

Also returns workflow.initialActivity when the child workflow declares one — the activity its first next_activity should name. A parent knows its own workflow's first activity, not its child's, and get_workflow stays where a session reads its own metadata, so this carries the child's across the boundary.

The child state is stored inside the parent's session.json under triggeredWorkflows.

When the parent is a temporary meta-bootstrap session, the server first promotes it to a real planning folder on disk, then embeds the child. You can keep using the parent's original session_index.

Dispatching from a temporary parent into a folder that already holds a child of the same workflow REPLACES that child rather than continuing it, and hands back the same session_index with an empty session behind it. A persistent parent appends a second child instead. See issue 429.

Loads the workflow definition for the current session.

The response starts with the orchestrator technique, then a separator, then metadata: rules, variables, initialActivity (the first activity to run), and a short list of all activities.

Use initialActivity for your first next_activity call — this is where a session reads its own. (dispatch_child returns the *child's*, for the parent to hand across.)

Also returns planning_folder_path (host bind path under Docker when HOST_PROJECTS_ROOT is set). Treat this as the one true artifact location; do not build paths relative to your own working directory.

If some activity files failed to load, activity_load_errors lists them and those activities are omitted from the list.

Moves the session to a new activity. This is the orchestrator's advance call — it updates state and records the trace but does not return the activity body.

After next_activity, the worker should call get_activity to load steps, checkpoints, exits, and technique references.

For the first transition, use initialActivity from get_workflow. After that, take the exit the activity reports and read its destination from the graph in get_workflow.

Optional step_manifest and exit help the server validate what you completed. Manifest checks are advisory — mismatches produce warnings, not hard errors.

Each item in these arrays is an object with the fields below.

Loads the full definition for whatever activity the session is currently on. No activity_id parameter — the server reads it from session state.

You must pass context_tokens: your worker's context window size in tokens. The server uses this to decide how many step techniques to bundle inline.

Ungated techniques that fit the budget are included in the response under step_techniques — the same content you would get from get_technique for that step. Gated steps and overflow techniques still need a separate get_technique call.

If the session uses persistent context mode (or you pass bundle: "reference"), content you already received may come back as short unchanged markers instead of full text. Pass bundle: "full" to force full delivery.

_meta.batch reports where your context stands against its batch bound: how many activities it has taken, the cap, what it has been delivered, the budget, and may_continue. On may_continue: false, finish this activity and report it — asking for another is refused with the payload undelivered, and the orchestrator dispatches a fresh worker under a new agent_id.

Call when a checkpoint step tells you to stop and hand control to the orchestrator.

Records the checkpoint as active and returns the session_index for a <checkpoint_yield> block in your output.

Each item in these arrays is an object with the fields below.

Call after the orchestrator resolves a checkpoint and resumes you.

Verifies the checkpoint is cleared and returns any variable updates to apply before continuing the activity.

Loads the active checkpoint's message, options, and effects so you can show it to the user.

Reads from state.activeCheckpoint — no separate checkpoint handle is needed.

Submits the user's checkpoint decision and clears the active checkpoint.

Present the checkpoint to the user and wait for input before calling this.

Provide exactly one of: option_id (user picked an option), auto_advance (timer elapsed on a checkpoint with a default), or condition_not_met (conditional checkpoint whose condition was false).

Variable effects from the chosen option are applied; type mismatches produce warnings in _meta.validation but do not block the response.

Fetches one technique for the current workflow or activity.

Before any activity is active, returns the workflow's first technique. During an activity, use step_id to fetch a specific step's technique, or omit step_id for the activity's first technique.

The response is fully composed: inherited inputs/outputs and merged rules from ancestor techniques, plus binding annotations when fetched via a step.

Techniques load one at a time. In persistent context mode, an identical refetch may return a short unchanged marker; pass full: true to get the full payload again.

Every fetch is recorded for trace and advisory manifest checks on the next next_activity call.

Loads reference material by id — templates, guides, or other markdown resources linked from techniques.

Bare ids (review-mode) resolve within the current workflow. Prefixed ids (meta/bootstrap-protocol) load from another workflow.

Add #section to fetch one heading slice instead of the whole file.

In persistent context mode, an identical refetch of the same resource_id (including any #section) may return a short unchanged marker; pass full: true to get the full body again.

Each fetch is logged for observability only (including when the answer is an unchanged marker); nothing validates that you called it.

Returns the tool-call history for debugging or audit.

Pass accumulated trace_tokens from next_activity responses to reconstruct a specific segment. Omit them to read the live in-memory trace for the session.

Orchestrator tool: record harness-reported token usage for ONE completed ACTIVITY (DELTA since the last figure for that dispatch). Call at every activity boundary — the first worker, a continue, a fresh worker after a timeout, a resume after a checkpoint yield, an out-of-band dispatch, and the terminal activity; a dispatch carrying a run of activities records one call per activity it covers. Optional agent_id attributes the row to a worker context.