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, 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) — and execution_path, agent: a caller walks the definition.

Pass working_directory as the absolute path of the checkout under work; the server derives owner/repo from that checkout's origin. repo is optional and must equal the derived origin when present.

With working_directory, planning lives under the top-level project folder holding that checkout, <project>/.engineering/artifacts/planning/, shared by every clone and worktree inside it.

Pass planning_folder as the absolute path of one planning folder. If it already holds session.json, the session resumes and workflow_id is ignored. A new folder must sit directly under the session's planning root, and its basename is the planning slug; a new folder anywhere else is refused, naming that root. A derived dated slug that already holds a session in that root opens the next free YYYY-MM-DD-<workflow_id>-N folder in the same call.

The variable bag is seeded with user_request, planning_folder_path, and the checkout facts host_repo_path, target_repo, component_path and is_monorepo, each path as the host path. A client this call opens, and a child dispatch_child opens, carry the same facts.

A fresh durable meta session that uniquely matches a catalog workflow, and that does not state resume intent, also dispatches that client and returns client.session_index. A durable meta start that cannot uniquely open a client returns a decision with no session_index; retry with user_request, target_workflow_id, planning_folder, or fresh. Origin binds even when the checkout folder is named for a branch.

Omit working_directory on a meta session to start a bootstrap session in a temp folder, unless planning_folder names a folder that already holds a session. Use dispatch_child later to promote it to an empty planning folder.

Child workflows are started with dispatch_child, not start_session.

Returns whether the session is active, blocked at a checkpoint, completed or aborted, plus the activities in flight, the completed activities, the last checkpoint answered and the variable bag.

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

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, planning_folder_path, and execution_path. The child's variables are seeded from the child workflow's defaults plus the parent's user_request; the parent records the child under triggeredWorkflows.

Also returns workflow.initialActivity — the activity the child's 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 an empty planning folder on disk, then embeds the child. You can keep using the parent's original session_index.

Promoting from a temporary parent onto a folder that already holds a session is refused as FOLDER_OCCUPIED; both session files are left untouched. A persistent parent appends a second child.

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 — one activity, or the branches a fanning exit opens, passed on as the graph gives them. Every call but the first names the activity it is returning.

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 the activity this context was dispatched for. Name it with activity_id where several are in flight; omit it on an ordinary walk, where the server reads the one activity 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.

Step-bound techniques whose gate answers true, and that fit the budget, are included in the response under step_techniques — the same content you would get from get_technique for that step. A step whose gate is false or unanswered, and a technique past the budget, still needs 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, what it has been delivered, may_continue, and, where bounded is true, the cap and the budget. 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. Emit an empty <checkpoint_yield> block in your output, which hands control up the chain; the user-facing agent reads the open checkpoint with present_checkpoint.

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 the checkpoint answered, the option chosen, the variable updates to apply, and the exit the option selected, if any. Where that exit carries ends_activity, run none of the remaining steps and report the ones you ran.

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.

An option whose effect declares recordReply takes the text the user typed as reply, stored in that variable. reply is refused with any other option.

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 carries the technique body with its own rules, naming its ancestors in inherits; each ancestor scope's shared inputs, outputs and rules arrive once under contracts, 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, on the basis the harness reports it: that activity's own spend, or the context's running total. 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.