MCP tool reference

Stoat serves 52 tools over one streamable-HTTP MCP endpoint:

http://localhost:5526/api/mcp

Stateless, so every call is a self-contained request — a dropped connection costs nothing, and several agents share one server with no sessions to keep straight.

Every tool is licence-gated. The rule is that each [McpServerTool] calls LicenseGuard first, and it is enforced behaviourally rather than by scanning for the guard's text: McpLicenseGateTests invokes every discovered tool with null for every reference parameter, so an ungated tool either answers with real data or dies on a null — both fail the test. It found one the day it was written (list_runs was expression-bodied, so the sweep that added the other eight guards had no brace to insert after). See Installation for the note that the check itself is temporarily disabled in this build.

Plans — 21 tools

A plan is a cross-repository DAG. Nodes are GitHub issues, PRs, NuGet publishes and consumes, test-run gates and Event Modeling slices; edges are dependencies; status is derived from observation, never asserted.

Reading

Tool	What it does
list_plans	Every active plan. Use the slug with get_plan / plan_status.
get_plan	One plan's full DAG — nodes, depends_on edges, and dependencyOrder (every node listed after everything it depends on).
plan_status	The live view: each node's derived status — unrealized, unknown, missing, open, claimed, pr-open, abandoned, done, waiting, running, failed, mismatch.
plan_history	Every change ever made to a plan, oldest first: who, when, what.
next_ready_nodes	Ready work across every plan or one — dependencies all done, not itself done/missing/running. Sorted by leverage (how many nodes it unblocks).

Authoring

Tool	What it does
create_plan	An empty plan. Status derives from observation immediately.
change_plan	Title, anchor, repo aliases. Omitted values keep their current value.
add_plan_node	Kinds: issue, pr, publish, consume, test-run-gate, slice. An issue number is optional — unbound means unrealized. Refused with the reason when it would break the plan.
change_plan_node	Replaces a node wholesale; anything omitted is cleared. Use link/unlink for edges only.
remove_plan_node	Refused while others depend on it — dropping an edge is a decision, not a side effect.
link_plan_nodes	Add an edge. Refused if it would make a cycle.
unlink_plan_nodes	Remove an edge.
bind_plan_node	The materialize step: bind an unrealized node to the GitHub thing you just created.
archive_plan	Out of the active set; history stays.
import_plan	A whole plan as YAML (schema 1). Diffs into an existing plan, so re-importing the same document records nothing.

Claims

Tool	What it does
agent_roster	Every Claude Code session on the box: running / idle / stopped (with cause), what each holds, and whether anyone is actually working. Same derivation as GET /api/agents.
claim_node	Claim or renew. A lease (default 30 minutes), so a dead session does not hold a node forever. Refused with the holder's name when taken.
report_node	Attach or replace your note and renew the lease. For decisions worth surfacing, not a transcript.
release_node	Status stays whatever observation says: finishing the work is proven by the issue closing, the version appearing, the suite passing.

Parking

Tool	What it does
await_dependencies	Block until every dependency of a node is done. Returns ready, or timeout with what is still outstanding.
await_package_version	Block until a feed serves >= minVersion. Queries the feed directly, so it works for any package, not only ones a plan declares.

Repositories — 12 tools

The cross-plan knowledge base. Check here before asking a question a previous session answered.

Tool	What it does
list_repositories	Every repository: slug, what it publishes and consumes, CI workflows, dependencies, note count.
get_repository	One in full, including every markdown note with who wrote it and when.
register_repository	Slug is owner/name — the same shape issue refs use.
describe_repository	Description or default branch.
declare_repository_package	This repository publishes or consumes a package — the cross-repo edge planning runs on. Re-declaring a known fact is a no-op.
retract_repository_package	Removes it from publishes and consumes both.
declare_repository_ci	A gating check name — the expected-check list PR status is read against.
retract_repository_ci
declare_repository_dependency	Repository-to-repository, independent of any one package edge. Say why in reason.
retract_repository_dependency
add_repository_note	A gotcha, a convention, a decision. Append-only, recorded with who and when.
archive_repository	Out of the active set. The stream — and every note — stays.

Memory — 10 tools

What one session learned, the next one recalls.

Tool	What it does
recall	Free-text search, best match first. Call it before starting a node, and before asking something a previous agent may already have answered.
get_memory	One in full — and, when asked, every version from its stream with who changed it and why.
list_memories	Browse without a search term: filter by scope, kind, tags; newest change first, paged.
record_memory	What the next session should know. Not a progress note — that is report_node, and it is about the node you hold right now.
revise_memory	Only what you pass changes; earlier versions stay on the history.
refile_memory	Move to another scope — session → repository, once it turns out to be about the repository.
link_memories	A typed edge: example-of, supersedes, explains, contradicts. Recorded on the first, readable from both.
archive_memory	Hidden from recall and listings; history stays.
restore_memory	Back into recall and listings.
await_memories	Block until a memory is recorded or changed in a scope — how an agent hears what another session just learned, without calling recall in a loop.

Recall has a full-text leg always, and a semantic leg when an embedding provider is configured; the vector projection runs on the async daemon, so semantic recall needs Stoat:LiveUpdates on.

Runs and evidence — 9 tools

These arrived with the run console on 2026-09-18. They read the same registry the board does, through its locked Read/ReadAll, so live ingestion can never hand a tool a torn scenario collection.

Tool	What it does
list_runs	Every run: running, finished, and orphaned (rehydrated from an archive after its publisher died). Newest first.
run_status	Per-scenario outcomes, the executing scenario's live steps, retry activity — and for a supervised run the worker lanes, recycles, faults, stalls and progress.
failing_tests	Failed and aborted scenarios with error messages and failing steps. An empty list means nothing has failed so far — check run_status for whether it is done.
flaky_ledger	Scenarios that passed only after retrying. Green builds hiding real instability; spans every known run unless narrowed.
await_run_completion	Block until a suite settles. Returns finished, orphaned or timeout with the final summary.
export_run	ctrf (rich — retries, flakiness, steps) or junit (lossy, for CI ingestion).
event_model	Every slice with its command, handler, aggregates, emitted events, read models, messages and bound specifications. Empty until a producer pushes one.
slice_coverage	What is untested per slice, and the two gaps are kept apart because they imply different actions: no-spec (nothing bound — scaffold scenarios) and no-evidence (bound, but no run has exercised it).
failing_spec	Everything failing_tests summarizes away: every step of the final attempt with status, duration and error, plus prior attempts — the input for writing the code a red spec describes.

TIP

With several publishers active, a no-runId await_run_completion honestly latches whichever run is in flight — which may be another session's supervisor worker. Pass the runId from list_runs.

See also

• An agent's first session — these tools in the order a session uses them
• REST API — the same surface for a client that has no MCP
• Ports and wire contracts — the run console's wire, on the other port