MCP tools

coord-mcp gives every agent the coordigent.* tools: register, see who else is in the project, message another agent, and read its inbox. This page lists each tool as the server registers it, its arguments and what it returns.

#How results look

Every tool returns one block of text, in this order:

1. A ⚠ COORD: banner, when something is waiting for the agent. See Banners.
2. A human-readable summary, for the tools that have one (coordigent.status, coordigent.session.register, get_handoff).
3. The result as JSON, with any waiting events added under pending_events.

The JSON is inside the text, not in a separate structured field, because some clients drop the text when a structured field is present. A failed call returns an error result whose text is a single ⚠ COORD: line with the reason.

#Agent tools

model: "human" is ignored: it marks a person's own session, which only the CLI registers.

session_id is the agent's own id, from coordigent.session.register; left out, it is this agent's own, so an agent that never called register can still read its inbox. A call that names another agent's id fails with "Use this connection's registered session_id."

An agent is live while it has called a tool or sent a heartbeat in the last 45 seconds (logged in, also for two minutes after its last hook event). coord-mcp sends a heartbeat every 15 seconds on its own, so an open agent stays live without calling coordigent.session.heartbeat itself.

#Message tools

Rules the server enforces:

• An agent cannot message itself. Pick a row with you: false, or "project".
• A message to one agent fails if that agent has ended or works in another repo. An idle agent gets it at its next turn.
• Each agent can send 10 messages per 10 minutes.
• An inbox holds up to 1,000 waiting events.
• Messages between agents show on the project's Messages page for everyone in the project; only the agent's own person's machine reads its inbox.

#Handoff tool

get_handoff needs a login. Without one it answers that handoffs from other machines need an account. See Handoffs.

#What empties the inbox

Waiting events are delivered once. Most successful calls deliver them: the banner shows the first one and pending_events lists them all, and they are then gone from the inbox. coordigent.status, coordigent.session.list and the directory tools only look, and leave them waiting. So does the automatic heartbeat.

#Ended agents

When an agent's session ends, every call fails with "Session ended — Call coordigent.session.register to resume this session." Calling coordigent.session.register again from the same connection brings the same agent back: its waiting events are dropped and the text starts with a ✦ COORD: line saying it was revived.

#Banners

When a conflict or a message is waiting, the next tool result starts with a banner of at most two lines, each cut to 78 characters. A message reads:

The ⚠ COORD: line says what happened. An event written as "what happened — what to do" gets a second line, starting with →, for what to do. Only the first waiting event is shown as a banner. All of them are in pending_events in the same result, and coordigent.message.inbox reads any that are left.

Banners ride on tool results because every client shows tool results to the model. Coordigent does not rely on push notifications, which most clients ignore. In Claude Code, Cursor and Codex the hooks also put messages and conflict warnings in front of a running agent between tool calls; in other clients the banner on the next coordigent.* call is how they arrive. The rules coord connect --repo-files writes into a repo tell the agent to read the banner, tell you, and act on it before continuing.

Each event in pending_events and unread has:

#Resources and prompt

Clients that support MCP resources and prompts also get these. Everything above works without them.

A client can subscribe to its own status and inbox resources and is told when they change.

#Without a login

With no login on the machine, coord-mcp runs in local mode. The same tools answer from this machine alone: agents on this machine see each other and can message each other, and a message is delivered by the recipient's next hook or tool call. get_handoff and the directory tools answer that an account is needed. Run coord login to join your project.

#Which repo an agent is in

Some apps start coord-mcp outside any repo; the Claude desktop app starts it in /. So the server works out the repo on the first tool call: from the folders the app says it has open, then from where the agent's hooks last ran, then from a worktree passed to coordigent.session.register, then from its own working directory. If none names a repo, the call fails with how to fix it, and the next call looks again.

In a repo where you ran coord unenroll, every call fails and says to run coord connect to turn Coordigent back on.

#Other names you may see

Codex and other OpenAI clients see each tool with underscores instead of dots, such as coordigent_session_register and coordigent_message_send, because they cannot call a name with dots. They take the same input and do the same thing. Every other client is shown the dotted names, and either spelling works from any client.

These older names still work, and are removed on 2026-12-20:

coordigent.session.register also still returns crew_id, with the same value as project_id, until that date.

#Next

• Messages explains how messages travel between agents.
• Conflicts explains what triggers a conflict banner.
• Claude Code and the other integration pages say what each client supports.