---
title: "MCP tools"
description: "Spawn, message and wait on other agents, drive terminals, declare the repo under review, and how the server registers itself into every session."
canonical: "https://agent-manager.dev/docs/mcp/"
last-updated: "2026-08-23"
section: "Documentation"
source: "agent-manager"
---

# MCP tools

Every session of an MCP-capable tool carries the agent-manager MCP server on spawn and revive, so the agent sees the whole workspace as native tools: its own session, the other agents running beside it, the groups they are filed under, and the managed terminals. No per-project setup. The server lives in the same binary (`agent-manager mcp`, stdio) and identifies the calling session through its environment.

## The tools

| Tool | What the agent uses it for |
| --- | --- |
| rename | Names its own session once it knows what the work is, replacing the placeholder. |
| review | Declares the repo under review, the base ref and the diff scope, in one call. |
| review_comment | Marks one sent review comment handled, using the stable comment id from the review prompt. |
| list_sessions | Lists every agent session with its id, CLI, group, directory, worktree branch and status. |
| create_session | Starts another agent CLI on a named task, optionally in its own git worktree. |
| read_session | Reads what another agent's screen currently shows. |
| send_session | Queues a message for another agent, delivered once it is at rest. |
| message_status | Checks whether a message is queued, held, delivered, dropped or answered. |
| wait_for_session | Parks until another session stops working, instead of polling it. |
| revive_session | Brings a dead session back, resuming the conversation it held. |
| kill_session | Stops a running agent, keeping its row and last screen. |
| archive_session | Files a finished session out of the active list, or restores it. |
| task | The shared work list in one tool: `action` is `list`, `create`, `claim`, `finish`, `release` or `delete`. |
| reserve_files | Declares the files this session is editing, and sees who else claims them. |
| release_files | Gives those claims back. |
| list_reservations | Sees what every session is editing right now. |
| list_groups | Lists groups with their default directories, worktree defaults and session counts. |
| create_group | Adds a group, nested with a slash path, to file a fleet under. |
| delete_group | Removes a group whose work is done; sessions still filed there move to the root rather than stopping. |
| list_terminals | Lists active managed terminals and their current directories. |
| create_terminal | Opens a terminal under the calling session, or beside it when that session is itself a terminal, unless `nest` is false. |
| send_terminal | Submits a command or sends exact keys to a running terminal. |
| read_terminal | Reads the plain-text content currently visible in a terminal. |
| close_terminal | Closes a finished terminal nested under the caller: kills the pane and deletes the row. |

## Spawning and steering other agents

`create_session` gives an agent the same spawn the `n` form gives a human: a name, a CLI, a group, a working directory, a first prompt and a worktree choice. A session created this way is a normal row in the list.

Each field falls back the way the form does. The CLI defaults to the one the calling agent runs, the group and directory default to the caller's, and an explicit directory wins over both. A name should describe the work; leaving it empty generates a placeholder and asks the new session to rename itself. Passing `worktree: true` adds a git worktree and branch off the directory's repo.

`read_session` returns the target's current screen, and its last captured screen once the session has stopped. `kill_session` ends the process and leaves the row dead with its last screen. `revive_session` brings it back on the conversation it held. `archive_session` files a finished row away or restores it.

## Messages between agents

`send_session` queues a message rather than typing it immediately. Several agent CLIs keep their input line drawn underneath an approval dialog, so a message written at that moment would answer the dialog instead of being read. The manager holds it and types it in on the first poll where the target is at rest: its input region is drawn, its status is not mid-turn, and nobody has a line part way written at its prompt.

The message arrives labelled as coming from another session rather than from the user, with the sender's name and the id to answer on. A receiving agent treats it as it would any untrusted input: it cannot approve a permission prompt, and it cannot change that session's configuration. `message_status` reports whether a message is queued, held, delivered, dropped or answered.

> **Delivery needs the manager running** The poller is what types the message in. A message queued while Agent Manager is closed waits until it opens again, and `send_session` says so in its result.

## Waiting and the shared task list

`wait_for_session` parks a single tool call until a session reaches one of the states that mean it stopped working, so an agent that spawned work does not read screens in a loop. A timeout returns the session's current state with `reached` false, because a timeout is an answer rather than a failure.

The task list is the manager's shared to-do list, visible to every session, all of it behind the one `task` tool. `create` puts work on it, `claim` takes a piece, and `finish` marks it done, which unblocks every task that depended on it. A claim is a single atomic write, so two agents racing for the same task cannot both win.

## File reservations

A worktree per session stops two agents overwriting one checkout when the work divides cleanly. `reserve_files` is for the other case: sessions that deliberately share a checkout declare the paths they are about to edit. Overlap with a lease another session holds comes back as conflicts, naming the holder, so the two can settle it through `send_session` before either commits. The lease is advisory: nothing is blocked.

## Terminals

`create_terminal` nests under the calling session unless `nest` is false, and a call from a terminal opens the new shell beside it. It defaults to the calling agent's group and live pane directory. `close_terminal` kills the pane and removes the row once the job is finished, and it reaches only the terminals nested under the calling session. `send_terminal` accepts exactly one of a command, pasted and submitted with Enter, or a sequence of tmux key names such as `C-c`, `Up` and `Enter`.

The server's instructions teach agents to use these tools without waiting to be asked: list sessions and delegate a parallel workstream to a named `create_session` before running it in series, and open a terminal for human-visible work such as SSH. They list and reuse a running terminal first; they send the command and read its screen while the job runs; and they call `close_terminal` when that job ends, unless the terminal is being left for the user.

> **These tools act on the user's machine** Treat `send_terminal` with the same care as typing into an attached shell, and treat `create_session` and `kill_session` as what they are: starting a real agent process that spends tokens, and interrupting one that may be mid-task.

## Registration

Registration is per tool and automatic. The built-in tools register on their own:

| Tool | How it is registered |
| --- | --- |
| claude | A generated `--mcp-config` file. |
| codex | `-c mcp_servers…` overrides on the command line. |
| opencode | An `OPENCODE_CONFIG` merge file. |
| grok, gemini | A one-time `mcp add --scope user` entry on first launch. |
| hermes | Its own one-time `mcp add` flow, which needs the MCP SDK its installer treats as optional. A Hermes still missing it refuses the spawn with a dialog pointing at `hermes setup`. |

A tool you added yourself opts in, or out, in its config block:

`config.toml`

```toml
[tools.mytool]
mcp = "claude"   # or codex, opencode, grok, gemini, hermes, none
```

A spawn whose CLI is not on PATH is refused the same way, with the vendor's portable installer for a built-in agent, or the package manager on this machine for anything else.

> **One server, every session** The stdio server serves whichever session called it, identified through its environment, so there is nothing per-session to launch or clean up.

## The same thing from a shell

Pi does not include an MCP client. Its sessions reach the same workspace through the subcommands: `agent-manager --help` lists them, from `sessions`, `spawn`, `send` and `wait` to the shared task list, file reservations, terminals and the review declarations.

```bash
agent-manager rename "auth token refresh"
agent-manager review-repo /path/to/repo
agent-manager review-base main
agent-manager spawn --name "cover the parser" --prompt "write the tests"
```