MCP tools for agents

Agents talk to volee, and to each other, through an MCP server that volee runs for each of them (ADR 0005). Agents launched by volee get it automatically. Any MCP-capable harness can use it too:

{
  "mcpServers": {
    "volee": { "type": "stdio", "command": "volee", "args": ["mcp", "--agent", "ag_01jc5…"] }
  }
}

The server speaks for one agent, given by --agent. It starts the volee daemon if needed.

An agent of another harness, which volee did not launch, joins instead (ADR 0014):

volee mcp --join <name> [--harness <kind>] [--mission <title, short id or id>]

The directory the server runs in is the agent’s workspace. The agent is idle while the server runs and stopped once it exits; each tool call shows as its activity. No hooks hand it messages, so the server’s instructions ask the model to call read_messages at the start of a task, after a question, and before it finishes. The guide has configurations for Codex CLI and Gemini CLI.

Agents volee launches may call every tool below without a permission prompt: their settings allow mcp__volee, so that a background agent never stalls on asking to send a message. Only a mission’s coordinator may call spawn_worker and request_approval; only a lead may call spawn_agent and start_mission. No tool merges or closes a mission: volee does both, once the human approved.

Tools

whoami

The caller’s identity: id, name, role, state, repository, branch, worktree, base branch, mission and parent. For a lead, also repos: the repositories of the person’s configuration, which it can name when it launches.

list_agents

Every agent volee knows, those that need attention first. Each entry has an id, a name, a role, a state, the repository and branch, the mission, the parent, the harness, and can_message: whether the caller may write to it. The caller’s own entry is in the list too, with you: true in place of can_message: a lead that reads the list before it launches does not take itself for a duplicate.

send_message

Routing follows ADR 0006: inside a mission every member writes to every member; otherwise an agent writes to its parent, its children, its mission’s coordinator, the agent that requested its mission, and the human. A refusal comes back as a tool error that explains why, so the model can correct itself.

A message to an agent whose session ended resumes it, unless the human stopped that agent or its mission is over: then the message waits. When the human stops a worker of a running mission, volee tells the coordinator in the mission’s thread, so that it plans without that worker.

read_messages

Messages addressed to the caller, oldest first, with sender, kind, id and references. Returned messages are marked as read.

Messages also reach the agents volee launched without this tool: at the end of a turn through the Stop hook, or by waking an idle agent. An agent that joined with --join has no hooks: this tool is the only way its messages reach it.

ask_human

Asks the human a question that only they can decide, with the answers they choose from. The question stays on top of the human’s messages, in the interface and in volee msg questions, until they answer it.

The answer reaches the agent as an answer message in reply to the question, like any other message. Its text is one of the options, in the option’s own spelling, when the human picked one; anything else is the human’s own words and is never a yes. The tool returns at once: the agent ends its turn and volee wakes it with the answer.

send_message with the kind question still asks a question without options. Options on anything but a question to the human are refused (ADR 0031).

report

Tells the agent’s parent, its mission’s coordinator and the human that the task is done, blocked or failed. A done report is a report message; blocked and failed are alert messages.

spawn_worker

For a mission’s coordinator: launches a worker on a new branch, in its own worktree of one of the mission’s repositories. volee tells the coordinator when the worker stops, with the evidence it checked. A mission launches at most [missions] max_workers agents (8 by default); past it, the tool returns an error that tells the coordinator to ask the human.

spawn_agent

For a lead (ADR 0033): launches an agent on one task in one repository, on a new branch in its own worktree. The agent’s parent is the lead: it reports to it. The arguments are those of spawn_worker; repo is a name whoami lists, or an absolute path. volee refuses, with the name of the agent to write to instead, when an agent already works on that branch of that repository.

start_mission

For a lead: starts a mission in its name. Its coordinator answers to the lead: its reports go to it, and each may write to the other.

volee refuses, with the name of the coordinator to write to instead, while a mission is open under the same title.

request_approval

For a mission’s coordinator, once volee told it that every worker delivered: presents its report to the human and asks for their approval (ADR 0032).

volee posts the report as a question from the coordinator to the human, in the mission’s thread, with the answers ok merge and no (ok close and no for an analysis mission); the lead that asked for the mission reads it too. The mission waits: nothing is merged or closed before the human answers. The tool returns at once, and the coordinator ends its turn. volee then tells it what the answer was. On the approving answer, volee merges each worker’s work itself, closes the mission, tidies its workers and stops the coordinator, which has nothing more to do; if a merge does not go through, volee tells it why, and it presents its report again once what blocks is settled. On any other answer, nothing is merged and the mission stays open.

Refused, with the reason, when the caller is not the coordinator, while a worker has not delivered (a report presented for approval says the work is ready), while the human has not answered the report already presented, and once they approved.