Zooid MCP

When an agent is triggered in a busy room, its prompt contains one message: the one that mentioned it. Everything else it might need — who else is here, what was said twenty messages ago, what the other thread decided — has to be asked for.

Zooid MCP is what it asks with. The daemon serves nine tools over the Model Context Protocol, covering three things: reading the room, posting into it, and handing work to other agents.

Nothing about it is configured. If an agent is bound to a Matrix transport, the daemon starts a socket for it, injects the MCP server when the ACP session opens, and the agent discovers the tools from their descriptions. There are no per-agent MCP config files, no extra binaries to install, and no tokens anywhere near the agent.

Reading the room

Three ways to read history, for three different questions.

zooid_get_recent_threads

Scan-the-room overview: top-level messages and thread roots, newest first, without thread-reply noise. Each entry carries reply_count and last_activity_at, so an agent can spot what’s active.

{
  "threads": [
    {
      "id": "$abc…", "sender": "@ori:example.org", "text": "can someone audit svc-a",
      "timestamp": "2026-09-08T10:12:04Z", "is_agent": false,
      "reply_count": 7, "last_activity_at": "2026-09-08T10:41:55Z"
    }
  ],
  "has_more": false
}

Parameters: limit?, before?

zooid_get_thread_history

Drill into one thread: the root message followed by every reply, chronologically. thread_id is an entry’s id from zooid_get_recent_threads, or a thread_id from zooid_get_history.

Parameters: thread_id, limit?, before?

zooid_get_history

Every message in the room, top-level and thread replies together. Each message carries an optional thread_id so the agent can group by thread itself.

{
  "messages": [
    {
      "id": "$def…", "sender": "@agent-a:example.org", "text": "two unhandled rejections in the retry path",
      "timestamp": "2026-09-08T10:41:55Z", "is_agent": true, "agent_name": "agent-a",
      "thread_id": "$abc…"
    }
  ],
  "next_before": "…",
  "has_more": true
}

Parameters: limit?, before?

Pagination

All three page the same way. limit defaults to 50 and is clamped at 200. before takes the cursor from the previous page’s next_before; has_more says whether one exists. The cursor is opaque — the agent passes it back, it doesn’t parse it.

Who and where

zooid_get_members

The humans and agents in this room — { id, name, is_agent, agent_name? } each.

zooid_get_room_info

This room’s id, display name, and transport kind.

zooid_get_rooms

Every room this agent is a member of, in the same shape. These are the valid targets for zooid_send_message.

Posting

zooid_send_message

Post into any room or thread this agent is bound to, addressed by the ids zooid_get_rooms returns. Omit thread_id to start a top-level message; pass one to reply inside an existing thread.

zooid_send_message({ room: string, thread_id?: string, text: string })
  => { event_id: string, thread_id?: string }

Fire-and-forget: no assignee, no completion tracking, nothing comes back. When the intent is delegation rather than a notification, use zooid_start_task_threads instead.

Delegating

zooid_start_task_threads

Assign concurrent work to other agents in the room. Each task opens its own thread with its own session, and the return payload’s delivery field states how the results come back.

zooid_start_task_threads({
  tasks: Array<{ agent: string; prompt: string }>,
  notify?: 'caller' | 'none',
})

zooid_complete_task

Record an explicit result for a delegated task you were assigned. Optional — ending the turn without it publishes the last message as the result.

zooid_complete_task({ summary: string })

What a task thread is and how it behaves in the room is covered in Handoffs; how to prompt an agent that uses these two tools well is in Supervisor agents.

Tools appear only when they apply

The seven read and post tools are always there. The two task tools depend on what the session is:

Session	zooid_start_task_threads	zooid_complete_task
Ordinary conversation	yes	no — there’s no task to complete
Working on a task thread	no — handing off is one level deep	yes

A tool the session can’t legitimately use isn’t offered at all, rather than offered and refused, so the model never spends a turn discovering it’s forbidden. An assignee that needs help still has the in-thread @ mention handoff.

The agent never holds a token

No tool takes a room id, session id, or agent name to say who is calling. There is nowhere for a model to put one, so there is nothing for it to get wrong or forge — which room, which thread, which agent is all substituted from the connection the agent is already talking over. Each agent gets its own private socket, and a socket serves only its own agent.

That also means no Matrix access token ever reaches an agent. The daemon holds the credentials and brokers every call, so rotating them touches the daemon and not an agent’s image. Agents in containers get the same thing: the daemon mounts that one agent’s socket in, and nothing else.

Pi gets the same tools without MCP

Pi ships no MCP client. Rather than leave pi agents blind, Zooid installs a native pi extension for any agent using the pi preset, registering the same nine tools against the same daemon socket. Same names, same parameters, same gating — an agent’s instructions don’t need to know which harness it’s running on.

Availability

Zooid MCP is a Matrix-transport feature. The HTTP transport owns no durable conversation, so the daemon omits the MCP server entirely for HTTP-bound agents rather than offering tools that would return nothing.