---
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-10-07"
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. |
| archive_self | Archives the calling session once its current turn ends, the way `a` does. |
| kill_self | Kills the calling session once its current turn ends, keeping its row for revive, the way `x` does. |
| 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. |
| report_issue | Files a bug report or a feature request on the public repo for the user. It composes a preview first, posts nothing until the user approves it, and files exactly what they saw. |

## 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. `model`, `effort` and `profile` launch the CLI on values it lists, the way the form's rows do, and a value the CLI does not list is refused with the ones it does.

`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.

### Ending its own session

An agent ends its own session with `archive_self` or `kill_self` (`agent-manager archive-self` and `kill-self` from a shell), so "archive yourself when it is merged" needs no trip back to the list. The call files the request and returns, the agent finishes its reply, and the manager acts on the first poll that reads the session at rest. Until then the row wears `↓` (archive) or `■` (kill) next to its name. `c`, or Cancel in the row's menu, keeps the session, and the agent can withdraw the request with `cancel`.

## 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 of the user's agent sessions, with the sender's name and the id to answer on. A receiving agent treats it as an instruction from the same operator and does the ordinary work it asks. Permission prompts and that session's CLI settings stay with the person at the keyboard, and so do commit, push, merge, publish and delete. `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 when to use these tools. They treat the other sessions the way the [coordination](#coordination) mode says, and open a terminal for human-visible work such as SSH. They list and reuse a running terminal first, send the command and read its screen while the job runs, and 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.

## Coordination

The `coordination` row in Settings (`s`) sets how far agents go with the other sessions on their own. `on request`, the default, tells each new session that the others exist and that it lists, messages, spawns or waits on them, and creates or claims shared tasks, only when you ask. "Spawn an agent for this" keeps working, since every tool stays registered. `proactive` has agents delegate a parallel workstream to a new session and check the shared task list before starting work, without waiting to be asked. A session is briefed when it starts, so the ones already running keep the mode they started with.

## 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, command-code | A one-time `mcp add --scope user` entry on first launch. |
| antigravity | A one-time `agy mcp add` on first launch, which writes `~/.gemini/config/mcp_config.json`. |
| 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 offering the `pip install mcp` line for the Python that runs Hermes. |
| muse | Muse reads MCP servers only from its settings file, so the first launch adds the `agent-manager` server to `~/.config/muse/settings.json` and keeps every other setting and server. |

Pi and Oh My Pi get no MCP registration, and their sessions use the subcommands below. 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 and Oh My Pi 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. Each one acts as the session or terminal it runs in.

```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"
agent-manager archive-self
```

`sessions`, `groups`, `spawn`, `read` and `wait` also run with no caller at all, so a script, a cron job or a CI step outside Agent Manager can open sessions that show up in your list. Such a `spawn` runs the CLI picked in Settings, in the root group and the directory the script runs in, unless `--tool`, `--group` or `--directory` says otherwise. `--model`, `--effort` and `--profile` pick what the CLI launches on.

```bash
agent-manager spawn --tool claude --group "Sprint Manager" --worktree \
  --name ticket-123 --prompt "Fix TICKET-123 and open a pull request" --json
```