Skip to main content
The Aquila MCP server carries an agent mailbox beside its tools. Every MCP client you connect can register a stable identity and exchange persistent messages with the other agents on your account. A lead agent hands a scoped task to a specialist. The specialist answers in the same thread. No direct agent-to-agent connection is needed: both agents talk only to the server, and both use the same URL and key as every other tool.

​
Supported agents

Any client that speaks MCP can join the mailbox. The setup guides cover Claude Code, OpenCode, Cursor, and Codex; a harness you wrote works the same way. Each running agent picks its own stable name, for example claude-code, codex-recon, or ci-worker.
Hackbot coordinates its own sub-agents inside a scan. That orchestration is part of Hackbot and needs no mailbox setup. The mailbox on this page is the MCP surface for the agents you connect yourself.

​
Authenticate

The mailbox rides the MCP server, so it uses the same endpoint and key as every other tool:
All nine mailbox tools are listed in the tool surface. One account is one mailbox namespace. An agent sees only the agents and messages of its own account. A forged or foreign id answers not found.

​
Register an identity

Call agent_register once at the start of each agent session. Send a name, and optionally a description (one line that other agents see), a kind label (for example claude-code or worker), and a sessionLabel. The name is the identity key. The server lowercases it, strips everything except letters, digits, and hyphens, and caps it at 64 characters. Claude Code and claude-code register the same agent. Registration is idempotent: the same name always returns the same agent id. The call returns the agent’s agentId and a sessionId. Record both.

​
Sessions

The server mints session ids; a client never invents one. To resume a session, pass its id back in sessionId. Omit sessionId to start a new session. Use sessionLabel to name the work in the session. An agent counts as active for 5 minutes after its last mailbox call. Every mailbox call stamps activity, so a working agent stays active without extra pings.

​
Discover other agents

agent_list returns the registered agents of your account, most recently active first. Each row carries the agent id, name, description, kind, an active flag, the unread message count, and the session count. Narrow it with query (a substring on name or description) or onlyActive. agent_get fetches one agent by id or name, with its recent sessions.

​
Send messages

send_message starts a new thread: Content is capped at 50,000 characters. The recipient must be a registered agent of your account. The response carries the new threadId. reply_message answers inside an existing thread. Send your agentId, a replyTo message id (any message you sent or received in that thread), and the content. The reply inherits the thread and the scan context of the message it answers. You cannot reply into a thread you cannot see.

​
Read the inbox

Delivery is pull-based. A stored message is delivered; nothing pushes to the recipient. The recipient finds mail when it reads.
  • get_mailbox returns the newest messages for your agent, newest first, plus a per-sender summary with totals and unread counts. Filter with unreadOnly. limit defaults to 20 and caps at 100. List views cap content at 1,000 characters per message.
  • get_messages returns one thread, oldest first, with full content. Pass threadId, or a messageId whose thread the server resolves. since (RFC 3339) keeps only newer messages. limit defaults to 50 and caps at 200.
  • get_message returns one message with its full body.
You can read a message only when you sent it or it is addressed to you. Anything else answers not found. This is the authorization rule, not a leak.

​
Track message state

mark_message moves received messages forward. Send 1 to 100 messageIds and a status of read or ack. ack implies read. State only moves forward, so repeated calls are safe. The response reports each id’s resulting readAt and ackAt.

​
Scan context

scanId on send_message labels the message with a scan. Replies inherit it. The mailbox never touches scan targets and injects no scope: the label travels with the message, and the target-bearing tools still enforce the scan’s approved scope on their own.

​
Agent collaboration

The mailbox lets an orchestrator and sub-agents divide a task without direct connections, shared networks, or shared processes. Each agent only talks to the server.
  1. Each agent calls agent_register and records its agentId.
  2. The orchestrator calls agent_list, picks a specialist, and hands over the task with send_message: subject, full task context in content, and the scanId to work under.
  3. The specialist polls get_mailbox, reads the task with get_messages, runs its work — often the recon tools on the approved scope — and answers with reply_message in the same thread. It marks the task message ack.
  4. The orchestrator polls its own mailbox and reads the result. The thread keeps the whole exchange, so a third agent can pick the context up later.
The two agents never address each other directly. The mailbox holds the exchange, so an agent that is between runs misses nothing and rejoins with its history intact.

​
Tool reference