--- title: MCP tools order: 3 --- # MCP tools The mount at `https://mainmind.app/mcp` (streamable HTTP), surface v0.4.0. This page is generated from the same registry the server registers its tools from, so it cannot drift from the runtime. Machine-readable twin: [/api/surface](/api/surface). Authentication, error shapes and a worked example are on [Auth, errors, examples](/docs/using-the-api). > OAuth mounts carry {member, name, role, charter, tenant} as token props, stamped at /authorize when the person types their invite code. Roles are enforced at registration: a tool a role may not use is a tool that role's session never sees. ## whoami *Roles:* all Who am I on this mount, identity, role, tenant, and how fresh the read is. Cheap; call it when unsure what this connection may do. *Returns:* One line of identity plus the projection's commit and freshness. ## boot *Roles:* all Call this FIRST in any session that will do real work for the organization. Returns the organization's entry documents (ORG.md, AUTHORITY.md), your role charter, and how to work from this mount. Everything else routes from here. *Returns:* ORG.md, AUTHORITY.md, your charter, and the working rules, at a named commit. ## find_process *Roles:* all Route a task to the organization's Process for it. Give the task in plain words ('a customer wants a refund', 'restock from a vendor'); returns the routing index plus closest matching Processes. Read the matched Process with read_node before acting. | Argument | Type | Required | What | |---|---|---|---| | `intent` | string | yes | What you're trying to do, in plain words | *Returns:* Closest matching Processes plus the routing index. ## read_node *Roles:* all Read one document from the company file by path, e.g. 'processes/create-purchase-order.md' or 'records/systems/shopify.md'. Returns full content plus the commit it reflects. Cite the path when you use what you read. | Argument | Type | Required | What | |---|---|---|---| | `path` | string | yes | Repo-relative path, as listed by search/find_process | *Returns:* The full node at the projection's commit, never with third-party annotations mixed in. ## search *Roles:* all Full-text search across the whole company file: processes, records, lessons, decisions, roles. Returns paths with snippets, follow up with read_node on the hits that matter. | Argument | Type | Required | What | |---|---|---|---| | `query` | string | yes | Words to find, e.g. 'gst refund shiprocket' | | `kind` | string | no | Limit to a kind: process \| record \| lesson \| decision \| role \| system | *Returns:* Ranked hits (BM25 + vector, fused, reranked) with snippets. ## run_start *Roles:* steward, founder Open a run on the live control plane at the START of real work, before doing it. This is what makes you visible to the whole team as currently working. Returns a run_id, carry it through run_heartbeat, emit_event and run_finish so everything you do is attributed to one run. | Argument | Type | Required | What | |---|---|---|---| | `task` | string | yes | One plain-English sentence: what this run is setting out to do | | `actor_label` | string | no | Who is working, as a person would say it. Defaults to your member identity | | `actor_id` | string | no | Stable slug for the actor. Derived from the label if omitted | | `harness` | string | no | claude-ai \| claude-code \| codex \| byo \| cron | | `process` | string | no | The Process being run, e.g. 'reconciliation-run' | | `doing` | string | no | The first step, short | | `scopes` | string[] | no | repo: scopes this run holds, e.g. ['repo:processes/reconciliation-run.md'] | *Returns:* run_id ## run_heartbeat *Roles:* steward, founder Report that a run is still alive and say what it is doing now. Call this as you move between steps. It is what the dashboard renders as the live line. A run that stops heartbeating shows as stalled, not working. | Argument | Type | Required | What | |---|---|---|---| | `run_id` | string | yes | The run_id returned by run_start | | `doing` | string | no | What is happening right now, one short phrase | | `scopes` | string[] | no | Replace the scopes this run holds | *Returns:* Acknowledgement. ## run_finish *Roles:* steward, founder Close a run. Use status 'landed' when the work is done, 'awaiting-ruling' when it is parked on a founder decision (the run keeps its branch and stays visible), 'conflict' when the target moved and the work must be rebuilt, 'failed' when it broke. | Argument | Type | Required | What | |---|---|---|---| | `run_id` | string | yes | The run to close | | `status` | landed \| awaiting-ruling \| conflict \| failed | yes | landed \| awaiting-ruling \| conflict \| failed | | `outcome` | string | no | One or two plain sentences on how it ended | | `proposal_ref` | string | no | The branch carrying the diff, if one was pushed | *Returns:* Acknowledgement with the terminal status. ## list_runs *Roles:* all List runs on the live control plane: which are open right now (and what each is doing), and which recently ended. *Returns:* JSON: open runs (with derived staleness) and recent finished runs. ## emit_event *Roles:* steward, founder Report a real operational event from a run to the live control plane. Use after completing real work. Title must be one plain-English, buyer-readable sentence; no secrets, no repo paths. Pass run_id to attribute it to an open run. | Argument | Type | Required | What | |---|---|---|---| | `type` | run \| brief \| judgment \| ruling \| deposit \| note | yes | run=a process ran; brief=morning brief; judgment=needs the founder; ruling=founder ruled; deposit=lesson/record/amendment landed; note=anything else | | `title` | string | yes | One plain-English sentence, buyer-readable, no jargon, no secrets | | `detail` | string | no | Optional 1-3 sentences of context | | `amount` | string | no | Optional money figure involved, e.g. $1,240.00 | | `needs_you` | boolean | no | true if this waits on the founder | | `actor` | string | no | Who did it, e.g. 'operator (claude code)' | | `run_id` | string | no | The run this belongs to, from run_start | *Returns:* Acknowledgement with the recorded timestamp. ## list_events *Roles:* all List recent events from the live instance feed. | Argument | Type | Required | What | |---|---|---|---| | `limit` | number | no | max events, default 20 | *Returns:* JSON array of events, newest first. ## ask_founder *Roles:* steward, founder Put ONE decision to the Founder as a link with two buttons. Use when work hits something only the Founder may decide, an approval boundary, spend, a rule change. You do the reading and arguing first; what reaches the Founder is one question and what becomes true on yes. Returns a URL. It lands in the Founder's queue, and you can also paste it to them directly. | Argument | Type | Required | What | |---|---|---|---| | `ask` | string | yes | The one question, plain words, answerable yes/no | | `becomes` | string[] | yes | Short lines: what becomes true if they say yes | | `because` | string | no | One sentence of why now | | `cost` | string | no | What it costs or gives up, one line | | `run_id` | string | no | The run this belongs to | *Returns:* The decision URL (/d/), one question, two buttons, evidence attached.