Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-bus Any messages for me on the bus?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server per il bus Agent Team OS. Sostituisce heredoc bash e scrittura diretta di JSON nelle inbox con sei tool tipizzati.
Nato il 21 set 2026 dal bug delle sessioni parallele: due Kai aperti insieme
(microsoft-mcp e noi-calendar) si rubavano i messaggi perché il bus li vedeva come un
unico destinatario. Il fix (bus v1.4, agent/slug) vive nella lib bash; questo server lo
espone come API di prima classe.
Tool | A cosa serve |
| chi è sul bus e quali sessioni sono vive adesso, con i pendenti di ciascuna |
| i messaggi di questa sessione (i suoi + i broadcast); |
| un messaggio per intero, con |
| invia a |
| sposta in |
| rigioca una conversazione in ordine |
Related MCP server: claude-context-sync
Un agente può avere più sessioni, una per workspace:
kai → tutte le sessioni Kai (coda condivisa)
kai/noi-calendar → solo quella
kai/microsoft-mcp → solo l'altrabus_status prima di inviare, quando non si sa quante sessioni esistono. Uno slug non vivo
viene consegnato lo stesso con un warning: il messaggio aspetta che quella sessione
parta, invece di sparire.
Dedotta dalla working directory via le rules di AGENT_MAP.json, quindi una sessione non
deve dichiarare chi è. Override con AB_AGENT e AB_SESSION_SLUG dove le regole non
arrivano. AB_HOME punta a un bus diverso (i test lo usano).
Nota: detect_agent qui prende il prefisso più lungo che matcha, mentre la lib bash
prende la prima regola in ordine di file. Identico quando le regole non si annidano, più
sicuro quando lo fanno.
claude mcp add agent-bus -- uv run --directory ~/Projects/07-Tooling/mcp/agent-bus-mcp \
--with fastmcp --with pydantic python -m agent_bus_mcp.serveruv run --with pytest --with fastmcp --with pydantic pytest tests/ -q19 test. Quelli che contano davvero:
test_targeted_message_reaches_only_its_session,
test_two_sessions_do_not_overwrite_each_other,
test_archive_keeps_message_in_its_own_session_dir.
Non sostituisce la lib bash né gli slash command: /inbox, /bus, /send, /read
restano e leggono gli stessi file. I due layer convivono sullo stesso filesystem.
Sorgente del protocollo: ~/Projects/01-Building/agent-team-os (repo), da cui
install.sh copia hook e lib in ~/.claude. Non editare ~/.claude direttamente.
Piani: work-hub/plans/PLAN-BUS-V2-SESSION-IDENTITY.md (il fix),
work-hub/plans/PLAN-AGENT-TEAM-OS.md (la v2.0 hive-GOD, che questo abilita).
Scritture atomiche (temp + rename): un lettore non vede mai un file a metà.
Il campo to resta il nome nudo anche per i messaggi mirati: thread e lettori
esistenti non cambiano, lo slug vive nel percorso.
.read/ e .done/ nascono con la directory di sessione: senza, il primo messaggio
mirato arrivava dove non si poteva archiviare (trovato da Kai usandolo).
archive è idempotente: archiviare due volte non è un errore.
Una sessione senza heartbeat da 240 minuti è considerata morta (AB_SESSION_TTL_MIN).
File a message away so it stops blocking the session from closing.
The Stop hook counts what is still pending, so archive each message once it is genuinely handled — not to silence the reminder.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | 'done' when handled, 'read' when only seen. | done |
| message_id | Yes | Full or partial message id. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that archiving prevents the session from closing and warns against misusing it to silence reminders. However, it does not state whether the action is reversible, if permissions are required, or any other side effects beyond the blocking behavior. It gives some behavioral context but lacks full transparency for a mutation tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the primary purpose front-loaded and the usage caution following. It is efficient and contains no filler. Every sentence earns its place, making it an excellent example of concise and well-structured documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two parameters and an output schema present. The description covers its core purpose, the reason behind it (Stop hook), and the correct usage pattern. It does not mention any prerequisites or limitations beyond the caution, but for its simplicity the description is sufficiently complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (message_id and state) are already documented with clear descriptions. The tool description does not add additional meaning beyond what's in the schema; it only implies that state may be 'done' or 'read' via the caution about 'genuinely handled.' Since the schema already covers the semantics, the description adds minimal value, placing it at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (file away/archive) on a specific resource (a message) and clearly conveys the purpose: to stop the message from blocking session close. This distinguishes it from siblings like bus_read or bus_send, which serve different functions. The phrase 'File a message away' is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear rule for when to use the tool: 'archive each message once it is genuinely handled' and explicitly cautions against using it 'to silence the reminder.' This is actionable and prevents misuse, though it does not explicitly name alternatives or contrast with other tools. The context of the Stop hook counts pending messages reinforces the appropriate timing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pending messages for this session.
By default: messages addressed to this workspace plus broadcasts to the agent. Other sessions' queues are left out unless all_sessions is set.
| Name | Required | Description | Default |
|---|---|---|---|
| unread_only | No | Only messages needing a response. | |
| all_sessions | No | Include other sessions of this agent. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden of behavioral disclosure. It explains the default message scope (workspace-addressed plus broadcasts) and the exclusion of other sessions, which is meaningful behavior beyond the parameter names. It does not disclose ordering or whether listing mutates read state, but for a read-only list these are minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs with the core purpose front-loaded in the first sentence. The follow-up clarifies defaults and the one conditional flag without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional boolean parameters and an output schema, the description covers the key context an agent needs: what is listed, what is excluded by default, and when to set all_sessions. The unread_only option is sufficiently documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented. The description reinforces the all_sessions behavior by stating that other sessions' queues are left out by default, but it adds little beyond the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'List pending messages for this session,' which clearly distinguishes the inbox-listing behavior from the sibling tools (bus_read, bus_send, bus_status). The scope is explicit ('for this session'), and the default inclusion rules are stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when the defaults apply and when to set all_sessions: 'Other sessions' queues are left out unless all_sessions is set.' It does not explicitly name sibling alternatives or say when to prefer bus_read/bus_status, but the listing-versus-reading intent is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one message in full, including its payload and context refs.
| Name | Required | Description | Default |
|---|---|---|---|
| archive | No | Move to .read/ after reading. | |
| message_id | Yes | Full or partial message id. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It states the read action but omits that the 'archive' parameter moves the message to .read/ after reading, a side effect that contradicts a simple read-only mental model. It also doesn't mention auth or rate limits, leaving a meaningful transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action and result, with no redundant words. Every word earns its place and it is easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low parameter count and presence of an output schema, the description covers the read scope well. However, it omits the archive side effect and does not orient the agent among siblings, which are meaningful gaps for a tool with zero annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents message_id and archive thoroughly. The description adds no param-specific semantics—mentions payload and context refs but doesn't elaborate on how parameters affect the result, justifying a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' with a specific resource 'one message', and explicitly mentions payload and context refs, clearly distinguishing it from bus_inbox (likely a list) or bus_status. This is precise and leaves no ambiguity about the tool's core action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for reading a full message when payload and context refs are needed, but it never names siblings or states when to prefer bus_read over bus_inbox/bus_thread. No exclusions or conditions are provided, so usage context must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to another agent, or to one specific session of it.
Prefer agent/slug when the recipient has more than one session open:
a bare name lands in the shared queue that every session reads.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | 'kai' for every session, or 'kai/noi-calendar' for one. | |
| intent | Yes | Short intent, e.g. 'bug-fix', 'new-app', 'review-request'. | |
| details | No | Extra payload fields beyond the summary. | |
| summary | Yes | What the recipient needs to know, in plain prose. | |
| priority | No | low | normal | high | urgent | normal |
| thread_id | No | Continue an existing thread. | |
| in_reply_to | No | Message id this answers. | |
| response_by | No | ISO deadline for the reply. | |
| context_refs | No | Absolute paths the recipient should read. | |
| message_type | No | request | brief | response | question | event | handoff | request |
| requires_response | No | Recipient is expected to reply. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses a non-obvious routing behavior: bare names land in a shared queue read by all sessions, while `agent/slug` targets one session. This is useful beyond the basic send action, though it does not mention delivery guarantees or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler. The first sentence states the core action, and the second adds essential routing nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, a 100% schema-described input schema, and an output schema, the description does not need to restate parameters. It covers the most important non-obvious behavior for correct use, making it sufficiently complete, though it could add a note about asynchronous delivery.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, so the baseline is 3. The description adds meaningful semantics to the `to` parameter by explaining the difference between bare names and `agent/slug` addresses, going beyond the schema's terse examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the exact verb and resource: 'Send a message to another agent, or to one specific session of it.' This clearly distinguishes bus_send from siblings like bus_read, bus_inbox, and bus_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete addressing guidance: prefer `agent/slug` when the recipient has more than one session, and explains that a bare name goes to the shared queue every session reads. It gives clear context for choosing the recipient format, though it does not explicitly compare bus_send with non-obvious alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who is on the bus and which sessions are live right now.
Use before sending when an agent may have several sessions open, so the message reaches the workspace that is actually doing that work.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | Only this agent; omit for the whole roster. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of explaining behavior. It communicates that the tool returns a live snapshot of occupants and active sessionsaine, implying a read-only status operation without side effects. This is adequate for a simple status tool, though it does not mention access requirements or freshness guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The core purpose is front-loaded, and the usage context is given immediately after, making it easy for an agent to parse and apply.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and an output schema, the description includes both what the tool reports and when it should be used. Nothing essential is missing for an agent to correctly select and call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional parameter is fully documented in the schema with 100% coverage. The description does not add additional meaning about the agent parameter, but the schema already explains it, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource ('the bus') and the kind of information returned: who is present and which sessions are live. It is specific enough to understand what the tool does, though it does not explicitly contrast itself with sibling tools like bus_inbox or bus_send.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear 'when to use' directive: before sending, when multiple sessions may be open, to ensure the message reaches the active workspace. It does not list exclusions or alternatives, but the context is sufficiently actionable for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replay a conversation in order: who said what, when.
| Name | Required | Description | Default |
|---|---|---|---|
| thread_id | Yes | Thread id, e.g. 'thread-20260921-noicalendar'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It communicates that the tool returns an ordered conversation with speaker, content, and timing, but it does not explicitly state whether the operation is read-only, mention permissions, or describe edge cases like empty or missing threads.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no filler. The core behavior is front-loaded, and the colon efficiently introduces the expected output dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description and schema together cover the essential invocation details: what the tool does and what input to provide. The main missing piece is guidance on when to choose this tool over bus_read, but that gap is more about usage differentiation than invocation completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the only parameter thread_id is documented with an example. The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete action ('Replay a conversation in order') and specifies what the result contains: who said what, when. It clearly identifies the tool's purpose but does not explicitly distinguish it from sibling bus_read, which may also return messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use bus_thread versus siblings like bus_read or bus_inbox. The intended use is implied by the phrase 'conversation in order,' but there are no explicit conditions, exclusions, or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0bus_archivebus_inboxbus_readbus_sendbus_statusbus_threadScored across 6 tools
Each tool has a clearly distinct responsibility: status for live sessions, inbox for pending messages, read for full message detail, send for delivery, archive for resolution, and thread for chronological replay. No two tools overlap in purpose or would cause an agent to misselect.
All tools follow a uniform bus_<action> pattern, making the API predictable and easy to navigate. The action terms are concise and match their functions.
Six tools is well-scoped for a message bus: enough to cover the full interaction lifecycle without redundancy. Each tool serves a distinct, necessary operation.
The set covers the core message lifecycle fully: send, receive, read, archive, inspect status, and replay threads. Broadcast delivery and per-session targeting are handled through bus_send, and archive provides a clean closure mechanism.
Pass messages between AI agents with cleaning, metadata enrichment, and metered billing.
Let your AI sessions talk to each other — messaging, tasks, sessions, and alerts
End-to-end encrypted messaging and work coordination for autonomous AI agents.
One identity across Claude Code, Codex, Cursor, Gemini, Windsurf: shared inbox and handoffs.