MCP Server - Smithers

Smithers ships a built-in MCP stdio server: --mcp makes the CLI speak the Model Context Protocol over stdin/stdout instead of running interactively, so any MCP-aware client can connect to discover workflows, start runs, watch progress, resolve approvals, and revert attempts through structured tool calls. Use the MCP server when an AI agent should drive Smithers autonomously. Use the HTTP Server for REST endpoints for human-written code or webhooks.

Setup

Start the server

bunx smthrs --mcp

This starts the semantic surface: a stable, structured tool set for AI agent consumption, documented on this page. Two additional surfaces are available via --surface:

# Semantic tools only (default)
bunx smthrs --mcp --surface semantic

# Raw CLI-mirroring tools only
bunx smthrs --mcp --surface raw

# Both surfaces registered on the same server
bunx smthrs --mcp --surface both

Use --surface raw only for direct CLI parity; prefer the semantic surface for new integrations, where every tool returns a { ok, data, error } envelope with Zod-validated input and output schemas. Scope the semantic surface when a client should not receive every Smithers control tool:

# Expose only selected semantic tools
bunx smthrs --mcp --allowed-tools list_workflows,get_run

# Expose only tools annotated as read-only
bunx smthrs --mcp --read-only

--allowed-tools takes a comma-separated list of semantic tool names; an empty allowlist exposes no semantic tools. --read-only removes semantic tools with write or control side effects, such as starting runs, resolving approvals, or reverting attempts. Under --surface both, both flags apply to the semantic toolset only; raw CLI-mirroring tools are always registered by the raw surface.

Register manually

For clients that read JSON config directly:

{
  "mcpServers": {
    "smithers": {
      "command": "bunx",
      "args": ["smthrs", "--mcp"]
    }
  }
}

Project-scoped install (e.g. a monorepo where Smithers is a dev dependency; ensure smthrs is in the local package.json):

{
  "mcpServers": {
    "smithers": {
      "command": "bunx",
      "args": ["smthrs", "--mcp"]
    }
  }
}

If `mcp add` fails

bunx smthrs mcp add hands the launch command to a registration helper expecting a single argument. If a runner or shell word-splits it, the helper sees a bare --mcp token and aborts:

Registering MCP server...
code: MCP_ADD_FAILED
message: "error: unknown option '--mcp'"

Register with your agent’s own CLI instead: the -- separator marks everything after it as the launch command, so --mcp never gets parsed as one of the agent’s own flags:

codex mcp add smithers -- bunx smthrs --mcp
claude mcp add smithers -- bunx smthrs --mcp

Any MCP-aware CLI follows the same <agent> mcp add <name> -- <command> shape, or write the JSON/TOML config by hand from the snippets above. The Smithers CLI prints these fallback commands automatically whenever mcp add fails.

Tool Registration

On start, every tool registers with:

inputSchema: Zod object describing accepted parameters.
outputSchema: Zod schema for the structured response envelope.
annotations: MCP annotation metadata (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).

Structured tool envelope

Every tool returns the same shape:

{
  ok: boolean;
  data?: { ... };     // present on success
  error?: {           // present on failure
    code: string;
    message: string;
    details?: Record<string, unknown> | null;
    docsUrl?: string | null;
  };
}

The response is also echoed as a text content block, so clients that do not parse structuredContent still receive the JSON payload.

Tool annotations

Annotation	Tools	Meaning
`readOnlyHint: true`	Most query tools	Tool does not modify state
`readOnlyHint: false, openWorldHint: true`	`run_workflow`	Launches external processes
`readOnlyHint: false, destructiveHint: true, idempotentHint: false`	`resolve_approval`, `revert_attempt`, `rewind_run`, `restore_checkpoint`, `time_travel`	Mutates persisted state irreversibly
`readOnlyHint: false, idempotentHint: false`	`fork_run`, `replay_run`	Creates new run/branch state

Tool Reference

list_workflows

List all Smithers workflows discovered in the working directory. Input: none Output:

{
  workflows: Array<{
    id: string;
    metadataVersion: number;
    displayName: string;
    scope: "local" | "global";
    entryFile: string;
    path: string;
    sourceType: string;
    description: string;
    tags: string[];
    aliases: string[];
  }>;
}

Use the returned id values as the workflowId parameter for run_workflow.

run_workflow

Start or resume a discovered workflow. Input:

Parameter	Type	Default	Description
`workflowId`	`string`	required	Workflow ID from `list_workflows`
`input`	`Record<string, unknown>`	`{}`	Workflow input object
`prompt`	`string`	-	Shorthand: sets `input.prompt` if `input` is unset
`runId`	`string`	auto	Custom run ID
`resume`	`boolean`	`false`	Resume an existing run; requires `runId`
`force`	`boolean`	`false`	Force-start even if this run ID already exists
`waitForTerminal`	`boolean`	`false`	Block until the run reaches a terminal state
`waitForStartMs`	`number`	`1000`	Background launches: wait time for the run row to appear in the database
`maxConcurrency`	`number`	-	Max concurrent nodes
`rootDir`	`string`	-	Root directory for tool sandboxing and path resolution
`logDir`	`string`	-	Directory for log files
`allowNetwork`	`boolean`	`false`	Allow network access in `bash` tool
`maxOutputBytes`	`number`	-	Cap on node output size
`toolTimeoutMs`	`number`	-	Per-tool call timeout
`hot`	`boolean`	`false`	Enable hot-reload of the workflow file
`startedBy`	`{ harness?, sessionId?, prompt? }`	-	Durable self-reported launch attribution. Harness/session may be inferred from Codex/Claude process markers when omitted; `prompt` is explicit-only, persisted, and visible to run readers (do not copy workflow input).

Output:

{
  workflow: {
    id: string;
    metadataVersion: number;
    displayName: string;
    scope: "local" | "global";
    entryFile: string;
    path: string;
    sourceType: string;
    description: string;
    tags: string[];
    aliases: string[];
  };
  runId: string;
  launchMode: "background" | "waited";
  requestedResume: boolean;
  status: string;
  observedRun: RunSummary | null;
  result: { runId, status, output?, error? } | null;
}

Background vs. waited launch By default (waitForTerminal: false) the tool fires the workflow and returns immediately with launchMode: "background"; observedRun reflects the run state polled during waitForStartMs. Use watch_run to track progress. Set waitForTerminal: true to block until the workflow finishes: result is then populated and launchMode is "waited". Run option forwarding rootDir, logDir, allowNetwork, maxOutputBytes, toolTimeoutMs, and hot forward verbatim to runWorkflow, overriding values baked into the workflow file.

list_runs

List recent runs with summary data. Input:

Parameter	Type	Default	Description
`limit`	`number` (1–200)	`20`	Max runs to return
`status`	`string`	-	Filter by status (`running`, `finished`, `failed`, etc.)

Output:

{
  runs: RunSummary[];
}

RunSummary fields: runId, workflowName, workflowPath, parentRunId, status, createdAtMs, startedAtMs, finishedAtMs, heartbeatAtMs, activeNodeId, activeNodeLabel, pendingApprovalCount, waitingTimers, countsByState.

get_run

Get the full detail record for a specific run, including steps, approvals, timers, loop state, lineage, config, and error. Input:

Parameter	Type	Description
`runId`	`string`	Run ID

Output:

{
  run: RunSummary & {
    steps: Array<{ nodeId, iteration, state, lastAttempt, updatedAtMs, outputTable, label }>;
    approvals: PendingApproval[];
    loops: Array<{ loopId, iteration, maxIterations }>;
    continuedFromRunIds: string[];
    childRunIds: string[];
    descendantRunIds: string[];
    activeDescendantRunId: string | null;
    config: unknown | null;
    error: unknown | null;
  };
}

watch_run

Poll a run at a fixed interval until it reaches a terminal state or a timeout expires. Input:

Parameter	Type	Default	Description
`runId`	`string`	required	Run to watch
`intervalMs`	`number`	`1000`	Poll interval (minimum enforced by runtime)
`timeoutMs`	`number`	`30000`	Wall-clock budget before giving up

Output:

{
  runId: string;
  intervalMs: number;
  pollCount: number;
  reachedTerminal: boolean;
  timedOut: boolean;
  finalRun: RunSummary;
  snapshots: Array<{ observedAtMs: number; run: RunSummary }>;
}

When timedOut is true the run is still active, so call watch_run again or raise timeoutMs. Terminal statuses: any status other than running, waiting-approval, waiting-event, or waiting-timer, including finished, failed, cancelled, and continued.

explain_run

Return a structured diagnosis explaining why a run is blocked, waiting, or stale. Input:

Parameter	Type	Description
`runId`	`string`	Run ID

Output:

{
  diagnosis: {
    runId: string;
    status: string;
    summary: string;
    generatedAtMs: number;
    blockers: Array<{
      kind: string;
      nodeId: string;
      iteration: number | null;
      reason: string;
      waitingSince: number;
      unblocker: string;
      context?: string;
      signalName?: string | null;
      dependencyNodeId?: string | null;
      firesAtMs?: number | null;
      remainingMs?: number | null;
      attempt?: number | null;
      maxAttempts?: number | null;
    }>;
    currentNodeId: string | null;
  };
}

summary is a human-readable sentence. blockers lists every node preventing progress; unblocker describes what action or event would unblock it.

list_pending_approvals

List approvals that are waiting for a human decision, optionally filtered by run, workflow, or node. Input: All parameters optional. Omit all to list every pending approval across all runs.

Parameter	Type	Description
`runId`	`string`	Filter by run ID
`workflowName`	`string`	Filter by workflow name
`nodeId`	`string`	Filter by node ID

Output:

{
  approvals: Array<{
    runId: string;
    nodeId: string;
    iteration: number;
    status: string;
    requestedAtMs: number | null;
    decidedAtMs: number | null;
    note: string | null;
    decidedBy: string | null;
    request: unknown;
    decision: unknown;
    autoApproved?: boolean;
    workflowName: string | null;
    runStatus: string | null;
    nodeLabel: string | null;
  }>;
}

resolve_approval

Approve or deny a pending approval. This tool is destructive and non-idempotent. Input:

Parameter	Type	Description
`action`	`"approve" \| "deny"`	required, decision to record
`runId`	`string`	Filter to a specific run
`workflowName`	`string`	Filter by workflow name
`nodeId`	`string`	Filter by node ID
`iteration`	`number`	Filter by loop iteration
`note`	`string`	Optional note to record with the decision
`decidedBy`	`string`	Identity of the decision-maker
`decision`	`unknown`	Structured decision payload passed back to the workflow

Ambiguity guard Zero matches errors with INVALID_INPUT; more than one also errors with INVALID_INPUT, returning matches in details.matches. Add runId, nodeId, or iteration to narrow the selection: the tool never guesses among multiple approvals. Output:

{
  action: "approve" | "deny";
  approval: PendingApproval;   // with updated status, decidedAtMs, note, decidedBy
  run: RunSummary | null;
}

ask_human

Block the current run, ask a human to make a decision, and wait for their answer: creates a durable pending human request and returns only once it’s resolved. Use this whenever the agent is blocked, uncertain, missing information, or about to take an irreversible or destructive action, instead of guessing. When run inside a Smithers task, the run/node context is taken from the SMITHERS_RUN_ID / SMITHERS_NODE_ID / SMITHERS_ITERATION environment variables Smithers injects into the agent; pass runId/nodeId/iteration explicitly to override, or rely on single-active-run autodetection. The orchestrating agent resolves the request on the human’s behalf: relay the question in conversation, collect their decision, then run bunx smthrs human answer <requestId> --value '<json>' (or bunx smthrs human cancel <requestId>) yourself, never instructing the human to run these. bunx smthrs human inbox lists everything waiting. Input:

Parameter	Type	Description
`prompt`	`string`	required, the decision or question to put to a human
`context`	`string`	Extra context appended to the prompt
`choices`	`string[]`	Fixed choices; restricts the human’s answer to one of these
`runId`	`string`	Run to attach to (default: `SMITHERS_RUN_ID` or the single active run)
`nodeId`	`string`	Node to attach to (default: `SMITHERS_NODE_ID`)
`iteration`	`number`	Loop iteration (default: `SMITHERS_ITERATION` or 0)
`timeoutSeconds`	`number`	Seconds before the request expires (0/unset = no timeout)
`pollSeconds`	`number`	Poll interval while blocking (default 3s)

Output:

{
  requestId: string;
  runId: string;
  nodeId: string;
  iteration: number;
  status: "answered" | "cancelled" | "expired" | "missing" | "aborted";
  decision: "approved" | "blocked";   // "blocked" => do not proceed
  response: unknown | null;            // the human's answer when status is "answered"
  answeredBy: string | null;
}

get_node_detail

Get enriched detail for a single node, including all attempts, tool calls, token usage, scorer results, and validated output. Input:

Parameter	Type	Description
`runId`	`string`	required
`nodeId`	`string`	required
`iteration`	`number`	Loop iteration (default: latest)

Output:

{
  detail: {
    node: { runId, nodeId, iteration, state, lastAttempt, updatedAtMs, outputTable, label };
    status: string;
    durationMs: number | null;
    attemptsSummary: { total, failed, cancelled, succeeded, waiting };
    attempts: unknown[];
    toolCalls: unknown[];
    tokenUsage: unknown;
    scorers: unknown[];
    output: {
      validated: unknown | null;
      raw: unknown | null;
      source: "cache" | "output-table" | "none";
      cacheKey: string | null;
    };
    approval: PendingApproval | null;
    limits: {
      toolPayloadBytesHuman: number;
      validatedOutputBytesHuman: number;
    };
  };
}

revert_attempt

Revert the workspace and frame history back to the state captured at a specific attempt. This is destructive and non-idempotent. Input:

Parameter	Type	Default	Description
`runId`	`string`	required	Run containing the node
`nodeId`	`string`	required	Node to revert
`iteration`	`number`	`0`	Loop iteration
`attempt`	`number`	required	Attempt number to revert to (must be ≥ 1)

Output:

{
  runId: string;
  nodeId: string;
  iteration: number;
  attempt: number;
  success: boolean;
  error?: string;
  jjPointer?: string;
  run: RunSummary | null;
}

fork_run

Create a branched run from a time-travel snapshot checkpoint without starting it. Input:

Parameter	Type	Description
`parentRunId`	`string`	Source run ID
`frameNo`	`number`	Snapshot frame number
`resetNodes`	`string[]`	Node IDs to reset to pending in the fork
`inputOverrides`	`Record<string, unknown>`	Input fields to overlay on the snapshot input
`branchLabel`	`string`	Optional branch label

Output: { runId, parentRunId, parentFrameNo, branch, snapshot, run }

replay_run

Fork a run from a checkpoint for replay, optionally restoring VCS state. Resume the returned runId with run_workflow when needed. Input: same as fork_run, plus:

Parameter	Type	Default	Description
`restoreVcs`	`boolean`	`false`	Restore the working copy to the source frame revision
`cwd`	`string`	-	Working directory used for VCS restore

Output: { runId, parentRunId, parentFrameNo, branch, snapshot, vcsRestored, vcsPointer, vcsError?, run }

rewind_run

Rewind a run to a previous frame, deleting later frames and invalidating derived state. This is destructive and requires confirm: true. Input:

Parameter	Type	Description
`runId`	`string`	Run to rewind
`frameNo`	`number`	Target frame number
`confirm`	`boolean`	Must be `true`

Output: { result, run }

restore_checkpoint

Restore the worktree to a durability checkpoint for a node (latest matching one if seq is omitted). Child subflow nodes with newer discarded checkpoints, plus their dependents, are reset so a resumed parent re-executes that work instead of preserving stale child results. This destructive operation requires confirm: true. Input:

Parameter	Type	Description
`runId`	`string`	Run containing the checkpoint
`nodeId`	`string`	Node whose checkpoint should be restored
`iteration`	`number`	Optional loop iteration
`seq`	`number`	Optional checkpoint sequence
`confirm`	`boolean`	Must be `true`

Output: { runId, nodeId, iteration, seq, commitId, cwd, success, error? }

list_snapshots

List durability workspace checkpoints for a run and its descendant child runs, with the owning run ID and matching VCS operation IDs when available. Input: { runId: string } Output:

{ snapshots: Array<{ runId, seq, nodeId, iteration, attempt, tier, source, label, commitId, operationId, cwd, createdAtMs }> }

get_timeline

Return the time-travel timeline for a run, optionally including all child forks recursively. Input:

Parameter	Type	Default	Description
`runId`	`string`	required	Run ID
`tree`	`boolean`	`false`	Include child forks recursively

Output: { timeline: unknown }

time_travel

Reset a run back to a prior node attempt and optionally restore VCS state. This destructive operation requires confirm: true (and force: true if the run is still marked running). Input:

Parameter	Type	Default	Description
`runId`	`string`	required	Run ID
`nodeId`	`string`	required	Node to travel back to
`iteration`	`number`	`0`	Loop iteration
`attempt`	`number`	latest	Attempt number
`restoreVcs`	`boolean`	`true`	Restore filesystem state
`resetDependents`	`boolean`	`true`	Reset dependent nodes too
`force`	`boolean`	`false`	Allow time travel when the run is still running
`confirm`	`boolean`	`false`	Confirm the destructive operation; must be `true`

Output: { result, run }

list_artifacts

List structured output artifacts produced by nodes in a run. Input:

Parameter	Type	Default	Description
`runId`	`string`	required	Run ID
`nodeId`	`string`	-	Limit to a specific node
`includeRaw`	`boolean`	`false`	Include raw (pre-validation) output values

Output:

{
  artifacts: Array<{
    artifactId: string;   // "<runId>:<nodeId>:<iteration>"
    kind: "node-output";
    runId: string;
    nodeId: string;
    iteration: number;
    label: string | null;
    state: string;
    outputTable: string | null;
    source: "cache" | "output-table" | "none";
    cacheKey: string | null;
    value: unknown | null;
    rawValue?: unknown | null;   // only when includeRaw=true
  }>;
}

Only nodes with an outputTable and a non-none output source are included.

get_chat_transcript

Return the structured agent chat transcript for a run, grouped by attempts. Input:

Parameter	Type	Default	Description
`runId`	`string`	required	Run ID
`all`	`boolean`	`false`	Include all attempts, not just those with known output events
`includeStderr`	`boolean`	`true`	Include stderr messages
`tail`	`number`	-	Return only the last N messages

Output:

{
  runId: string;
  attempts: Array<{
    attemptKey: string;
    nodeId: string;
    iteration: number;
    attempt: number;
    state: string;
    startedAtMs: number;
    finishedAtMs: number | null;
    cached: boolean;
    meta: unknown | null;
  }>;
  messages: Array<{
    id: string;
    attemptKey: string;
    nodeId: string;
    iteration: number;
    attempt: number;
    role: "user" | "assistant" | "stderr";
    stream: "stdout" | "stderr" | null;
    timestampMs: number;
    text: string;
    source: "prompt" | "event" | "responseText";
  }>;
}

Messages sort by timestampMs; use tail to limit context window usage on long transcripts.

get_run_events

Return the raw structured event history for a run with optional filtering. Input:

Parameter	Type	Default	Description
`runId`	`string`	required	Run ID
`afterSeq`	`number`	-	Only events with `seq` greater than this value
`limit`	`number` (1–10000)	`200`	Max events to return
`nodeId`	`string`	-	Filter to events for a specific node
`types`	`string[]`	-	Filter to specific event types (e.g. `["NodeFinished", "NodeFailed"]`)
`sinceTimestampMs`	`number`	-	Only events at or after this timestamp

Output:

{
  runId: string;
  events: Array<{
    runId: string;
    seq: number;
    timestampMs: number;
    type: string;
    payload: unknown | null;
  }>;
}

Paginate via afterSeq: pass the seq of the last received event to fetch the next page.

Usage Examples

List workflows and start a run

> list_workflows {}

{
  "ok": true,
  "data": {
    "workflows": [
      { "id": "bugfix", "displayName": "bugfix", "entryFile": "./workflows/bugfix.tsx", "sourceType": "user" }
    ]
  }
}

> run_workflow { "workflowId": "bugfix", "prompt": "Fix the auth token expiry bug" }

{
  "ok": true,
  "data": {
    "runId": "smi_abc123",
    "launchMode": "background",
    "status": "running",
    ...
  }
}

Watch until complete

> watch_run { "runId": "smi_abc123", "timeoutMs": 120000 }

{
  "ok": true,
  "data": {
    "reachedTerminal": true,
    "timedOut": false,
    "finalRun": { "status": "finished", ... }
  }
}

Resolve a pending approval

> list_pending_approvals { "runId": "smi_abc123" }

{
  "ok": true,
  "data": {
    "approvals": [
      { "nodeId": "deploy", "iteration": 0, "nodeLabel": "Deploy to production", ... }
    ]
  }
}

> resolve_approval { "action": "approve", "runId": "smi_abc123", "nodeId": "deploy", "decidedBy": "alice", "note": "Looks good" }

{
  "ok": true,
  "data": {
    "action": "approve",
    "approval": { "status": "approved", "decidedAtMs": 1707500100000, ... },
    "run": { "status": "running", ... }
  }
}

Debug a blocked run

> explain_run { "runId": "smi_abc123" }

{
  "ok": true,
  "data": {
    "diagnosis": {
      "summary": "Run is waiting for a human approval on node 'deploy'.",
      "blockers": [
        {
          "kind": "approval",
          "nodeId": "deploy",
          "reason": "Node requires human approval before proceeding.",
          "unblocker": "Call resolve_approval with action=approve or action=deny."
        }
      ]
    }
  }
}

Revert a failed attempt

> get_node_detail { "runId": "smi_abc123", "nodeId": "analyze" }

{
  "ok": true,
  "data": {
    "detail": {
      "attemptsSummary": { "total": 3, "failed": 2, "succeeded": 1 },
      ...
    }
  }
}

> revert_attempt { "runId": "smi_abc123", "nodeId": "analyze", "attempt": 1 }

{
  "ok": true,
  "data": {
    "success": true,
    "run": { "status": "running", ... }
  }
}

Error Codes

Errors follow the structured envelope. Common codes:

Code	Meaning
`RUN_NOT_FOUND`	No run or workflow exists with the given ID
`INVALID_INPUT`	Missing required field, failed validation, or ambiguous approval filter
`WORKFLOW_MISSING_DEFAULT`	Workflow file has no default export

​Setup

​Start the server

​Register manually

​If mcp add fails

​Tool Registration

​Structured tool envelope

​Tool annotations

​Tool Reference

​list_workflows

​run_workflow

​list_runs

​get_run

​watch_run

​explain_run

​list_pending_approvals

​resolve_approval

​ask_human

​get_node_detail

​revert_attempt

​fork_run

​replay_run

​rewind_run

​restore_checkpoint

​list_snapshots

​get_timeline

​time_travel

​list_artifacts

​get_chat_transcript

​get_run_events

​Usage Examples

​List workflows and start a run

​Watch until complete

​Resolve a pending approval

​Debug a blocked run

​Revert a failed attempt

​Error Codes

Setup

Start the server

Register manually

If `mcp add` fails

Tool Registration

Structured tool envelope

Tool annotations

Tool Reference

list_workflows

run_workflow

list_runs

get_run

watch_run

explain_run

list_pending_approvals

resolve_approval

ask_human

get_node_detail

revert_attempt

fork_run

replay_run

rewind_run

restore_checkpoint

list_snapshots

get_timeline

time_travel

list_artifacts

get_chat_transcript

get_run_events

Usage Examples

List workflows and start a run

Watch until complete

Resolve a pending approval

Debug a blocked run

Revert a failed attempt

Error Codes