Skip to content
AndonDocs
GitHub
Look something up

MCP tools

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

Each run’s agent session gets an MCP server named andon, started by the agent (andon mcp). Its tools are how a run talks to the board: it asks you a question, shows a preview, records what it learned, and reports at the end of a turn. In Claude Code they appear as mcp__andon__<tool>.

The server holds no credentials. A tool call goes to this machine’s agent over 127.0.0.1 with the run’s id, and the agent writes to the board as the machine, for that run’s card only.

Four sets of tools exist. A card’s run gets the run tools; a conversation in the board’s chat gets the chat tools; a planning session gets the planning session tools; a coordinated workstream’s coordinator gets the coordinator tools. Every tool below, and the arguments of every run, planning session and coordinator tool, are checked against the code by a test (apps/agent/src/reference-docs.test.ts).

Run tools

An argument marked * is required.

Tool What it does Arguments
ask Ask the person a question on the board. The answer arrives as the run’s next message, so the run ends its turn after asking. question*
report Once at the end of each turn: a short structured summary for the board, and the outcome that moves the card (done, needs_review, blocked, parked). checked names the card notes’ checklist items the turn finished (by text or number); Andon ticks them in the notes. headline*, done, decisions, next, risks, outcome, verify, waiting_on, checked, issues
set_status_note Show a short progress line on the card (up to 280 characters). text*
note Append a short note to the card. text*
comment Comment in the card’s Comments thread, as the machine. It mentions nobody: to get an answer, use ask. A run comments only on its own card; reply_to answers a comment in its thread. text*, card, reply_to
add_card Make a follow-up card, in this card’s team and project unless another is named, with the default recipe. A named team or project the machine’s owner can’t see is refused as not found. title*, notes, team, project, column (inbox, backlog or next)
attach Attach a file from the workspace to the card, such as a screenshot. path*, caption
publish_output Publish a file from the workspace as a run output for review on the board. An .html file is shown as a page: one self-contained file of at most 5 MB. path*, label
step_done PR group runs: tick off one of the numbered issues in the prompt. item*, note
request_review Ask for an Andon code review of the card’s open pull request. The review starts in its own session once this turn ends. none
preview Share a web server the run started as a preview link on the card, through the machine’s tunnel. Only a port the run’s own process listens on; the app gets only the cookies it set. Fails when previews are off. port*, label
preview_screen Show a native app live on the card: the iOS Simulator (ios), an Android emulator or device (android), or a macOS window (window) of an app the run built or started. target*, app, device, label
preview_capture Capture a PNG frame of a preview and save it on the card as an output. A web preview is loaded read-only in headless Chrome at the given size (default 1280 × 800). label, port, path, width, height
preview_element Name the element at a pixel of a captured web frame: its CSS path, tag, role, text and box. frame, x, y
stop_preview Close a preview and take its link off the card. port*
memory_search Search the team’s active memory, ranked. query*, limit (1 to 20)
remember Record something the repository should remember: a proposed entry under .andon/memory on the run’s branch, staged for its commit. At most 5 a run. Secrets, email addresses and home paths are refused. See the file format. kind, title, text, evidence, tags, paths, supersedes
knowledge Write or rewrite a knowledge note, .andon/knowledge/<topic>.md, staged for the commit. topic, text, title, tags, paths
review_result Code-review runs: report the review round once, at the end, with each finding, the visual findings on captured frames, the pushed commit, and up to 5 things to remember. verdict* (clean, fixed or blocked), findings, head_sha, visual_findings, memory, memory_conflicts
propose_steps Propose a workstream’s steps for review on the board. Nothing is made until a person approves. steps*
propose_project Study runs: propose a new project with its cards, their order and the open questions. Nothing is made until a person accepts it. At most 30 cards. name, cards, description, questions
permission The permission prompt of a headless run. Claude Code calls it; a run never does. tool_name, input, tool_use_id

Chat tools

The board’s chat runs on a machine (when orchestrator is on there) with only these tools. Each acts for the person in the chat, within what they may see and do, and is audited as the chat’s. The ones marked “asks first” never act: the person sees a confirmation and their tap does it.

Tool What it does
orch_overview The board at a glance: machines, active runs, what needs the person, workstreams.
orch_list_cards Cards, filtered by column, team, project, group or text.
orch_card One card in full: fields, notes, workspace, PR group, latest run, requests, outputs, links.
orch_run_tail A run with more of its terminal output and its report.
orch_machines Every machine of the org: online, capabilities, active and queued runs.
orch_groups The PR groups, filtered by team, project and state.
orch_group One PR group by name or id.
orch_repo_memory What a team’s repositories remember (their .andon/ memory on the default branch).
orch_open Open a card, team, project or group on the person’s screen.
orch_create_card Make a card as the person. It never starts a run.
orch_plan_cards Add a feature planned in the chat as cards, in one call, once the person agrees to the plan: in order, in the Backlog, each card’s notes naming the earlier cards it depends on. Cards that ship together come back for orch_group_cards to propose.
orch_update_card Change a card’s title, notes, team, project, recipe or priority.
orch_move_card Move a card. Into Working starts a run.
orch_start_run Start a run on a card now.
orch_reply Send text to a card’s session, or continue it.
orch_stop Stop a run. Asks first when an interactive run is waiting on the person.
orch_propose_steps Propose a workstream’s steps for a card.
orch_run_group Run a planned PR group now.
orch_group_cards Asks first: group two or more cards into one pull request.
orch_decide Asks first: allow or deny a run’s pending permission request or question.
orch_remove_workspace Asks first: remove a card’s workspace from its machine.
orch_archive_card Asks first: archive a card.
orch_start_over Asks first: start a card over with a fresh run.
orch_move_to_machine Asks first: move a card’s work to another machine.

Planning session tools

A planning session’s agent builds a draft of cards with the person, beside the chat. It keeps these chat tools: orch_overview, orch_list_cards, orch_card, orch_repo_memory, orch_groups and orch_open, and gets the tools below instead of the rest: it never makes, moves or runs a card, and nothing it writes is a card until the person accepts the draft. It runs in a read-only checkout of the team’s repository and reads it with its own file tools (Claude Code’s Read inside the checkout, Codex’s shell under a read-only sandbox, Gemini CLI’s file-reading tools). Each change names the item’s rev as the agent last read it, so an edit over the person’s comes back as a conflict, with the item as it is now, instead of landing. A team, project or recipe is given by name or id, a board card by key (WEB-12) or id.

Tool What it does Arguments (* required)
plan_read_draft The draft: its project, cards, findings and questions, each with its key and rev. With since, only what changed after that draft revision and who changed it. since
plan_set_project The project the draft proposes, or instead the existing project it adds to. name, description, project (one of name or project)
plan_upsert_card Add a card to the draft (no rev; it needs a title) or change one (its rev; only the fields given change). depends_on names draft cards it waits for, pr_group gives cards that ship in one pull request the same handle. key*, title, notes, team, project, recipe, estimate, depends_on, depends_on_cards, pr_group, after, migration, protected_paths, rev
plan_remove_card Remove a card from the draft. key, rev
plan_move_card Move a card to go after another (after: null: first). Cards are made in this order. key, after
plan_add_finding Record a finding with its evidence: a file and line, a count and how it was counted, a command and its output, a link or a quote. With key and rev, change one. title, evidence, key, body, cards, rev
plan_remove_finding Remove a finding. key, rev
plan_ask Ask the person an open question, naming the draft cards it affects. An unanswered question holds back Accept of those cards. question*, key, cards
plan_answer Answer an open question once the code settles it. key, answer
plan_status Set the line on the session’s card; ready: true marks the draft ready to review. text*, ready
plan_git The checkout’s history: log, show, grep, blame, diff or ls-files, with flags from an allowed list and paths inside the checkout. Never --output, -O, --ext-diff, --textconv, -c, --exec-path, --git-dir, --work-tree or --no-index. Output is capped at 64 KB. command*, args

Coordinator tools

A coordinated workstream’s coordinator, on the machine that hosts it, has only these tools, on its own coordinator thread. Each acts for the person who switched the coordinator on, only on that workstream’s steps, and only while it handles an event; each decision goes on the step’s history as the coordinator’s. Starting a step or sending it back only queues a run: Andon still picks the machine. Under the plan permission mode it gets only coord_workstream and coord_step. A step is its card id or key (WEB-12).

Tool What it does Arguments (* required)
coord_workstream The workstream now: every step’s state, what it waits for, its accepted run, retries used, the open escalations and the turns left. none
coord_step One step in full: notes, latest run with its report and tail, pull requests and checks, outputs, pending questions. step*
coord_start_step Queue a step’s start run with the coordinator’s instructions, rendered into the run’s prompt. Refused while it has a live run or has run already, a step it waits for isn’t accepted and merged, the workstream is paused, or the step is archived. step, instructions (target, change, constraints, acceptance*, at most 8,000 characters together)
coord_accept_step Accept a step’s latest finished run, approving its outputs waiting for review. Never merges: the steps after it wait for its pull requests to merge, and the result names the steps that may start now. step*, note
coord_send_back Send a step back: a revise run with the feedback as its prompt, or a fresh run after a failure. Refused while its run is live, or once its retries are used up. step, feedback
coord_answer Answer a step’s pending question as the person would. Never a permission prompt. request, answer
coord_revise_steps Change steps that have no run yet, all or nothing: update a title, notes or what it waits for, add a step, archive one. Refused for a step with a run or in Done, or a change that makes a cycle. At most 30 changes. changes* (each {op: update, step, title, notes, waits_for}, {op: add, key, title, notes, waits_for, recipe, team} or {op: archive, step})
coord_escalate Ask the person something the coordinator can’t decide, with up to six choices. At most three open on a workstream. question*, choices, step