What can you do with this server?

This MCP server lets agents coordinate through a local SQLite-backed event bus with event publishing, polling, human-in-the-loop approvals, and resource locking. * Publish events to a workspace event log by topic with payload, trace/span lineage, idempotency, SLA timeout, and optional auth. * Poll events after a cursor for at-least-once delivery, with topic, limit, and since_id controls. * Check workspace bus health and list topics. * Review events pending human approval, hidden from standard polling. * Approve pending events so agents can see them on poll. * Reject pending events and notify the originating agent with a reason. * Acquire exclusive advisory leases on workspace resources with owner and TTL. * Release held leases idempotently. * Renew active leases via heartbeat TTL extension. * Check lock state without acquiring it; no auth required.

Which integrations are available for this server?

Enables Hermes agents to publish and poll structured events in a multi-agent workspace via MCP.

How do I use agentbus?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agentbus show recent handoff events" 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.

de en es ja ko ru zh

agentbus

by onicarps

Overview Schema Source Related Servers Discussions Admin

Python

Local

AgentBus

Test PyPI Python License: MIT

The Zero-Daemon, SQLite-Backed Event Bus & Visual Cockpit for Multi-Agent Coding.

When Cursor, Claude Desktop, Antigravity, terminal bots (Hermes, Aider), and custom Python scripts work together in the same workspace, coordinating them usually devolves into messy, append-only log.md files or heavy cloud dashboards.

AgentBus gives your AI agents a fast, typed, local pub/sub highway backed by a single SQLite file (.agentbus/events.db) and gives you an interactive God View Mission Control TUI to watch every handoff, trace execution lineage, and approve dangerous actions in real time.

⚡ 30-Second Quickstart (The "Ah-Ha" Moment)

You don't need complex configurations or Docker daemons to see AgentBus in action.

1. Install

# Installs AgentBus, its isolated Python runtime, and verifies the CLI.
curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/onicarps/agentbus/main/install.sh | bash

The installer does not create a bus in whichever directory you happened to run it from. It prints the direct command path for immediate use and adds its command directory to new interactive shells (bash, zsh, and fish).

Create a project workspace and initialize your first agent:

mkdir -p ~/my-agent-workspace && cd ~/my-agent-workspace
~/.local/bin/agentbus init --apply --producer-id my-agent

(Or via package manager in an existing environment: pipx install okf-agentbus or uv tool install okf-agentbus — the interactive TUI monitor is bundled out-of-the-box.)

2. Launch the Visual Monitor (Terminal A)

~/.local/bin/agentbus monitor

(Or use the standalone command: agentbus-monitor)

You are now in the God View TUI dashboard:

Live Event Stream: Watch real-time multi-agent activity as it occurs.
Trace Waterfall: Inspect trace_id lineage and parent-span relationships.
HITL Approvals: Review pending approvals with one-keystroke hotkeys ([a] approve / [r] reject).

3. Send Your First Message (Terminal B)

Open another terminal in the same folder and publish a handoff event:

~/.local/bin/agentbus publish \
  --topic okf/handoff \
  --producer-id my-agent \
  --payload '{"from":"my-agent","to":"reviewer","summary":"Added auth endpoints; please review and write tests."}'

👉 Look back at Terminal A: the event immediately pops up on your monitor!

Related MCP server: Hivemind

🛠️ Why AgentBus?

Approach	Limitations	How AgentBus Solves It
Shared `log.md` file	Race conditions, zero schemas, no delivery guarantees, unsearchable history	Typed topics, monotonic event IDs, SQLite transactional integrity, advisory file locks
Cloud SaaS (e.g. LangSmith)	Latency, cloud data egress, vendor lock-in, heavy setup for local development	100% local SQLite storage, zero cloud egress by default, instant startup
Heavy Brokers (Redis, Kafka)	Background daemon requirements, port collisions, Docker overhead	Zero daemons: embedded SQLite sidecar per project directory (`.agentbus/events.db`)
Framework Runtimes (LangGraph, CrewAI)	Locked into a single Python runtime or process	Connects heterogeneous agents across IDEs (Cursor, Claude Desktop), CLI tools, and scripts via standard MCP and CLI

📦 Fresh Boot & Installation Guide

AgentBus requires Python 3.11+. The one-command installer bootstraps an isolated runtime automatically, including on a machine without Python. The God View interactive monitor (rich + textual) is bundled with the base package.

Option A: 1-Line Universal Installer (Recommended for fresh systems)

Handles fresh boots, non-root environments, and Linux PEP 668 (externally-managed-environment) automatically:

curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/onicarps/agentbus/main/install.sh | bash

Option B: Standalone CLI Tool (pipx or uv)

If you prefer isolated CLI tools without creating project virtual environments:

# Using uv (fastest)
uv tool install okf-agentbus

# Using pipx
pipx install okf-agentbus

Option C: In an existing virtual environment

If you have an active project virtual environment (.venv):

pip install -U okf-agentbus

💡 System Python: On modern Linux (Ubuntu 24.04+, Debian 12+) and macOS Homebrew, system Python correctly rejects bare pip install. Use the one-command installer above, uv tool install okf-agentbus, or pipx install okf-agentbus; do not bypass the OS protection.

🔌 Connecting Your AI Coding Agents

AgentBus speaks standard Model Context Protocol (MCP) over stdio as well as standard CLI commands.

1-Click Auto-Configuration

Navigate to your project workspace and run:

agentbus init --apply --producer-id my-agent

For a fresh default workspace, init maps my-agent to the least-privileged engineer role so its first okf/handoff publish works. It scans for installed tools (Cursor, Claude Desktop, Antigravity) and automatically generates the necessary MCP configuration without changing existing custom RBAC policies.

Manual IDE Configurations

For Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)

{
  "mcpServers": {
    "agentbus": {
      "command": "agentbus",
      "args": ["mcp-serve"],
      "env": {
        "AGENTBUS_WORKSPACE": "/path/to/your/project",
        "AGENTBUS_PRODUCER_ID": "cursor"
      }
    }
  }
}

For Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "agentbus": {
      "command": "agentbus",
      "args": ["mcp-serve"],
      "env": {
        "AGENTBUS_WORKSPACE": "/path/to/your/project",
        "AGENTBUS_PRODUCER_ID": "claude"
      }
    }
  }
}

Once connected, your AI agents will automatically see tools like:

agentbus_publish — publish task updates, handoffs, and questions.
agentbus_poll — check for incoming assignments.
agentbus_lock_acquire / agentbus_lock_release — prevent file edit collisions.

💡 Practical Examples for Beginners & Intermediates

Example 1: CLI Coordination (Zero Code)

Simulate two agents working together directly from the shell:

# Agent A publishes a completed task:
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"alice","to":"bob","summary":"Refactored database models"}'

# Agent B polls for new tasks:
agentbus poll --topic okf/handoff --since-id 0

Example 2: Python Script (Publishing & Polling)

Integrate any custom Python agent or bot in 5 lines:

from pathlib import Path
from agentbus.rbac import ensure_default_roles
from agentbus.store import EventStore

# Connect to current project workspace
workspace = Path.cwd()
ensure_default_roles(workspace)  # install the local role policy first
store = EventStore(workspace)

# Publish an event
event, _ = store.publish(
    topic="okf/handoff",
    producer_id="codex",
    schema_version="1.0",
    payload={"from": "codex", "to": "all", "summary": "Job completed successfully"},
)
print(f"Published event #{event.event_id}")

# Poll new events
messages = store.poll("okf/handoff", since_id=0)
for ev in messages["events"]:
    print(f"[{ev['event_id']}] {ev['payload']['summary']}")

store.close()

Example 3: Human-in-the-Loop (HITL) Safety Intercepts

Catch dangerous AI operations (e.g. database migrations, shell scripts, deletions) before they execute:

# 1. Register an intercept rule: any handoff containing 'DROP' requires human approval
agentbus config set-intercept --topic okf/handoff --contains "DROP" --ttl-minutes 30

# 2. When an agent tries to publish:
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"agent","to":"db","summary":"DROP TABLE users"}'
# => Status becomes: PENDING_APPROVAL

# 3. View and approve/reject it in the TUI:
agentbus monitor
# Press [A] to approve or [R] to reject!

Example 4: Preventing File Collisions with Advisory Locks

When multiple agents write code at the same time, they can accidentally overwrite each other. Use advisory leases:

# Agent 1 locks a file before editing:
agentbus lock acquire --resource src/models.py --owner-id agent-1 --ttl 300

# Agent 2 checks lock status:
agentbus lock status --resource src/models.py

# Agent 1 releases the lock when finished:
agentbus lock release --resource src/models.py --owner-id agent-1 --lease-id <LEASE_ID>

Example 5: 1-Click Multi-Agent Swarm (`agentbus up`)

Instead of opening 5 terminal windows, orchestrate your agents, file watchers, and monitor together:

# 1. Generate default .agentbus/swarm.yaml
agentbus up --init

# 2. Start the swarm (daemons + God View monitor)
agentbus up

# 3. Check running background workers
agentbus ps

# 4. Tear down the swarm cleanly
agentbus down

📚 Complete Examples Catalog

Check out the examples/ folder for fully isolated, executable Python scripts:

01_core_pub_sub.py — Fundamental publish and poll flow.
02_hitl_intercepts.py — Catching sensitive payloads for human sign-off.
03_swarm_rbac.py — Swarm role-based topic permissions and identity tokens.
04_sla_timeouts.py — Automated dead-letter routing when an agent ghosts.
05_observability.py — Distributed trace waterfall lineage (trace_id, parent_span_id).
06_distributed_context.py — Sharing large artifacts/diffs via content hashing.
07_pydantic_schemas.py — Validating topic payloads with Pydantic models.
08_god_view.py — Passive OS filesystem, shell, and MCP call observation.
09_langgraph_bridge.py — A LangGraph-node handoff skeleton.
10_crewai_bridge.py — A CrewAI-task handoff skeleton.

See the Examples Guide for full documentation on each recipe.

⌨️ CLI Cheat Sheet

Command	What it does
`agentbus monitor`	Launch the interactive God View TUI dashboard (`agentbus-monitor` also works)
`agentbus publish --topic <t> --payload '<json>'`	Publish an event to the local SQLite bus
`agentbus poll --topic <t> [--since-id <id>]`	Read published events from the bus
`agentbus init --apply --producer-id <id>`	Auto-discover MCP configs for Cursor/Claude/Antigravity
`agentbus doctor`	Run non-destructive diagnostic checks on SQLite, schema, and environment
`agentbus lock acquire --resource <path>`	Acquire an exclusive lease/lock on a file or resource
`agentbus lock release --resource <path>`	Release a previously held lease
`agentbus config set-intercept --topic <t>`	Create Human-in-the-Loop approval rules
`agentbus up`	Boot multi-agent swarm services declared in `swarm.yaml`
`agentbus ps`	View active swarm background services
`agentbus down`	Terminate all active swarm processes

📖 Deep-Dive Documentation

📄 License

MIT — see LICENSE.

Available Tools

10 tools

agentbus_approveC

Approve a pending event so agents can see it on poll.

ParametersJSON Schema

Name	Required	Description	Default
`event_id`	Yes
`auth_token`	No
`reviewer_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must fully disclose behavior. It reveals that the tool changes state (approval) and makes events visible on poll, but omits critical details like required permissions, idempotency, reversibility, or side effects. Mutation tools need richer behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise (one sentence), which is efficient but arguably too brief given the tool's complexity (3 parameters, no schema coverage, mutation). A few more sentences would improve clarity without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a mutation with no annotations and an output schema (not described). The description does not cover what constitutes a 'pending event', the approval workflow, or the response structure. The context is insufficient for an agent to use the tool confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description adds no parameter meaning. It does not explain event_id, auth_token, or reviewer_id, leaving the agent to infer from names alone. The description must compensate for missing schema descriptions but fails to do so.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the verb 'Approve' and the resource 'pending event', and clarifies the effect 'so agents can see it on poll'. This clearly distinguishes it from sibling tools like agentbus_review, suggesting a specific approval step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It does not provide prerequisites, conditions for use, or exclusions. The sibling tools list is given but not leveraged to explain selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agentbus_lock_acquireC

Acquire an exclusive advisory lease on a workspace resource.

ParametersJSON Schema

Name	Required	Description	Default
`owner_id`	Yes
`resource`	Yes
`auth_token`	No
`ttl_seconds`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It only states that the lease is 'exclusive' and 'advisory,' but lacks details on what happens if the lock is already held, side effects, or return behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is under-specified for a tool with four parameters and an output schema; it sacrifices necessary detail for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (4 parameters, output schema, no annotations), the description fails to cover return values, failure modes, or how to use the parameters, leaving significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not explain any of the four parameters (owner_id, resource, auth_token, ttl_seconds), providing no added meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Acquire' and clearly identifies the resource as 'exclusive advisory lease on a workspace resource,' which distinguishes it from siblings like lock_release, lock_renew, and lock_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like lock_release or lock_renew, nor any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agentbus_lock_releaseB

Release a held lease (idempotent if already expired).

ParametersJSON Schema

Name	Required	Description	Default
`lease_id`	Yes
`owner_id`	Yes
`resource`	Yes
`auth_token`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions idempotency if the lease is already expired, which is a useful behavioral trait. However, with no annotations, the description carries the full burden and fails to disclose authentication requirements, side effects, or what happens if the lease is not held.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no wasted words. It could arguably add more detail without becoming verbose, but it is efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has four parameters and no parameter descriptions in the schema, the description should compensate but does not. The existence of an output schema mitigates the need to explain return values, but overall completeness is lacking.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage for parameters, and the tool description does not explain any of the four parameters (lease_id, owner_id, resource, auth_token). This is a critical gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Release a held lease', with a specific verb and resource. The sibling tools include acquire and renew, so the purpose is distinct and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the name and description, but there is no explicit guidance on when to use this tool versus alternatives like agentbus_lock_acquire or agentbus_lock_renew. No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agentbus_lock_renewC

Extend TTL on an active lease (heartbeat).

ParametersJSON Schema

Name	Required	Description	Default
`lease_id`	Yes
`owner_id`	Yes
`resource`	Yes
`auth_token`	No
`ttl_seconds`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only states the basic function (extending TTL) without mentioning side effects, error cases, or required permissions (e.g., auth_token needed).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is concise and front-loaded with the key action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (5 params, 0% schema coverage, and a locking context), the description is insufficient. It fails to explain parameters or output, leaving significant gaps for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain any of the 5 parameters. It adds no meaning beyond their names, leaving the agent to infer their purposes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Extend TTL on an active lease (heartbeat)' clearly specifies the verb (extend) and resource (active lease), and the heartbeat terminology distinguishes it from sibling tools like lock_acquire, lock_release, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It only states the action without context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agentbus_lock_statusB

Check lock state without acquiring (no auth required).

ParametersJSON Schema

Name	Required	Description	Default
`resource`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description discloses an important behavioral trait ('no auth required'), but omits other aspects like idempotency, side effects, or what the lock state entails. Minimal but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise with no filler. However, the brevity sacrifices clarity on parameter semantics. Front-loaded with key differentiating info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite low complexity and presence of output schema (not shown), the description fails to explain the sole required parameter. Leaves agent guessing about 'resource'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and description does not mention the 'resource' parameter at all. No guidance on its meaning, format, or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'Check' and resource 'lock state', distinguishing it from sibling tools like lock_acquire, lock_release, and lock_renew. No ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implicitly indicates when to use ('without acquiring') and notes no auth required, but does not explicitly list alternatives or when not to use. Context from sibling names helps, but description lacks explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agentbus_pollA

Fetch events after cursor (at-least-once delivery).

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`topic`	Yes
`since_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses 'at-least-once delivery', a meaningful behavioral trait indicating possible duplicate deliveries and implied consumption semantics. With no annotations provided, this adds value beyond the schema, though it omits other details like read-only vs. side-effect on the cursor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, with two short phrases that are front-loaded and contain no redundant information. Every word contributes to the meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description is too sparse to fully understand the tool's mechanics. It omits parameter semantics, ordering, and error behavior, making it incomplete for correct invocation, especially with no annotations to fill gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only hints at a 'cursor' without explicitly mapping to the since_id parameter. It does not explain the meaning of limit or topic, so the description fails to compensate for the lack of parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches events after a cursor, using the verb 'Fetch' and resource 'events'. This distinguishes it from sibling tools like agentbus_publish (writing) and agentbus_status (status checks), and the cursor aspect adds specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the name and sibling context (polling for events after a cursor), but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agentbus_publishC

Append one event to the workspace event log.

ParametersJSON Schema

Name	Required	Default
`topic`	Yes
`action`	No
`payload`	Yes
`trace_id`	No
`auth_token`	No
`producer_id`	No
`causation_id`	No
`parent_span_id`	No
`schema_version`	No	1.0
`idempotency_key`	No
`sla_timeout_minutes`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'Append' implies a durable mutation, but the description says nothing about authentication (despite an auth_token parameter), idempotency/deduplication behavior (despite an idempotency_key parameter), ordering guarantees, or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single clean, front-loaded sentence with no filler, which is structurally good. But for an 11-parameter mutation tool the extreme brevity reflects under-specification rather than disciplined conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be explained, but the description leaves the auth requirement, idempotency semantics, and event-schema/versioning behavior unspecified for a complex write tool with no annotations and no parameter docs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 11 parameters, and the description adds no parameter meaning at all. Critical parameters such as auth_token, idempotency_key, causation_id, parent_span_id, and sla_timeout_minutes are entirely undocumented in both places.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb ('Append'), resource ('event log'), and scope ('one event', 'workspace'), so an agent can tell this is a write/publish operation. It does not, however, differentiate itself from siblings like agentbus_poll or agentbus_review, which an agent must distinguish on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no conditions selecting this over agentbus_poll or any other sibling, and no stated prerequisites. The agent must infer the entire usage context from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agentbus_rejectB

Reject a pending event and notify the originating agent.

ParametersJSON Schema

Name	Required	Default
`reason`	No	rejected by human reviewer
`event_id`	Yes
`auth_token`	No
`reviewer_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of disclosing behavioral traits. It does mention the notification side effect, but it omits critical information such as whether the rejection is permanent, how the event state changes, or any authentication requirements. This is a significant gap for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that immediately communicates the primary action and key side effect. It is front-loaded and contains no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given four parameters, no annotations, and zero schema description coverage, this description is insufficiently complete. It does not explain the lifecycle of the event, the meaning of reviewer_id, or any prerequisites, leaving the agent to rely on the output schema which does not cover these behavioral aspects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no parameter details. While event_id and reason may be self-evident from their names, auth_token and reviewer_id are not explained, forcing the agent to guess their purpose and required format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Reject', the resource 'a pending event', and the side effect 'notify the originating agent.' It is specific and distinguishable from sibling tools like approve and review, which have contrary or different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage context is implied: use this tool when rejecting a pending event. However, it does not explicitly mention alternatives or when not to use it, nor does it contrast with approve or review, so the guidance is only implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agentbus_reviewA

List events pending human approval (hidden from standard poll).

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`topic`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only states the basic purpose (listing pending events) but does not clarify whether the operation is read-only, any side effects, authentication requirements, or behavior under different conditions (e.g., empty results). The description is too minimal for a tool without annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that front-loads the core purpose. Every word is necessary; there is no redundancy or extraneous information. It is appropriately sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema (which covers return values) and the tool's straightforward nature (listing pending events), the description provides the essential context. However, missing details such as filtering behavior or relationship to sibling tools (like agentbus_approve) could be added for completeness, even though the tool is simple.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. However, the description does not mention the parameters 'limit' or 'topic' at all. While the parameter names are somewhat self-explanatory, the description adds no additional context or usage guidance, which is insufficient given the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'List' and clearly identifies the resource as 'events pending human approval', making the purpose immediately clear. It also distinguishes the tool from siblings by noting these events are 'hidden from standard poll', implying that other tools like agentbus_status show standard events.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool—to view events that are not visible through the standard poll. It does not explicitly state when not to use it or mention alternatives, but the context of sibling tools (e.g., agentbus_approve for approvals) provides implicit guidance. A higher score would require explicit when/when-not statements.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agentbus_statusB

Workspace bus health and topic list.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It only states that the tool returns health and topic list, implying a read-only operation but doesn't mention side effects, authorization needs, or error states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and front-loaded, but it's a noun phrase rather than a complete sentence. It is efficient but could be improved with a verb.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and the presence of an output schema, the description adequately explains the tool's purpose and return value. It is sufficiently complete for a simple status-check tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so the baseline is 4. The description adds meaning by specifying what the output covers (health and topic list), which goes beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns workspace bus health and topic list, distinguishing it from sibling tools like agentbus_review or agentbus_approve. However, it lacks a verb like 'get' or 'retrieve', making it slightly less directive.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings. The sibling names suggest different purposes (review, approve, lock operations), but no explicit conditions or exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

1 tool updatev0.23.0Sep 13, 2026

Changedagentbus_publish1 field changed

addedInput schema / properties / action

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Action"
+}

3 tool updatesv0.18.0Aug 12, 2026
- Addedagentbus_poll
- Addedagentbus_publish
- Addedagentbus_reject
8 tool updatesv0.17.0Jul 22, 2026
- Addedagentbus_approve
- Addedagentbus_lock_acquire
- Addedagentbus_lock_release
- Addedagentbus_lock_renew
- Addedagentbus_lock_status
- Removedagentbus_publish
- Addedagentbus_review
- Addedagentbus_status
3 tool updatesv0.16.3Jul 18, 2026
- Removedagentbus_poll
- Addedagentbus_publish
- Removedagentbus_reject
8 tool updatesv0.16.3Jul 18, 2026
- Removedagentbus_approve
- Removedagentbus_lock_acquire
- Removedagentbus_lock_release
- Removedagentbus_lock_renew
- Removedagentbus_lock_status
- Removedagentbus_publish
- Removedagentbus_review
- Removedagentbus_status

1 tool updatev0.6.0Jul 7, 2026

Changedagentbus_publish2 fields changed

addedInput schema / properties / parent_span_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Parent Span Id"
+}

addedInput schema / properties / trace_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Trace Id"
+}

4 tool updatesv0.4.0Jul 7, 2026
- Addedagentbus_approve
- Changedagentbus_publish1 field changed
  - addedInput schema / properties / sla_timeout_minutes
```
Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Sla Timeout Minutes"
+}
```
- Addedagentbus_reject
- Addedagentbus_review
4 tool updatesv0.2.0Jul 7, 2026
- Addedagentbus_lock_acquire
- Addedagentbus_lock_release
- Addedagentbus_lock_renew
- Addedagentbus_lock_status
3 tool updatesv0.1.0Jul 7, 2026
- First observedagentbus_poll
- First observedagentbus_publish
- First observedagentbus_status

Deploy Server

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

B3.3/5.0

Scored 2026-09-13 03:20 across 10 tools

Disambiguation4/5

Tools are mostly distinct: publish vs poll vs review vs approve/reject are clearly separated, and lockdown tools (acquire/status/release/renew) are distinguishable. Minor potential overlap between poll and review for fetching events, but descriptions clarify that review shows hidden pending events.

Naming Consistency4/5

Consistent 'agentbus_' prefix with verb_noun patterns for most tools (e.g., lock_acquire, lock_release, lock_renew). Deviations like 'approve' and 'reject' use a single verb, but they remain readable and fit the domain.

Tool Count5/5

10 tools are well-scoped for an agent bus handling event approval, polling, publishing, and lock leasing. Each tool appears to serve a distinct purpose with no redundancy.

Completeness5/5

Covers the full lifecycle: publish, poll, review, approve/reject, status, and lock management (acquire, status, renew, release). No obvious gaps for the stated event bus and lock leasing domain.

Maintenance

ActivityActive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

ContextLattice
io.github.sheawinkler
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Knowledge & Memory Agent Orchestration Autonomous Agents
2154
StateyOAuth
ai.statey
An agent-native database over MCP: shared, validated, structured records in every AI chat.
Databases Knowledge & Memory
2
ctlsurf B
com.ctlsurf
System-of-record notebook for AI coding agents: pages, datastores, tasks, skills over MCP.
Autonomous Agents Developer Tools Knowledge & Memory
502
memnodeOAuth
dev.memnode
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Knowledge & Memory Autonomous Agents Agent Orchestration
2

Related MCP Servers

claude-sync
Agent Orchestration Knowledge & Memory
the-firmament
A
license
Not graded
quality
C
maintenance
Local-first MCP server that enables multiple Claude agents to coordinate through a shared message bus with SQLite persistence and real-time clock anchoring.
Updated 5 months ago (2026-04-30 03:08 UTC)
MIT
Hivemind
Agent Orchestration Knowledge & Memory Autonomous Agents
gbram1
F
license
Not graded
quality
D
maintenance
Persistent, append-only event log for AI agent coordination, enabling agents to publish, query, and react to structured events across tools and sessions.
Updated 6 months ago (2026-04-07 02:12 UTC)
12 npm
1
-
Claude State MCP Server
Databases Knowledge & Memory
mfitzhenry
F
license
Not graded
quality
D
maintenance
SQLite-backed MCP server for Claude Code session persistence and multi-agent coordination. Provides tools for session management, event logging, decision tracking, file locking, agent registry, and plan tracking.
Updated 7 months ago (2026-03-07 01:43 UTC)
-
nuzo-memory
Knowledge & Memory Databases
fabionfsc
A
license
Not graded
quality
F
maintenance
Local-first, auditable memory for AI agents. Provides durable context for MCP hosts with SQLite storage, CLI, and MCP tools for memory management.
Updated 2 months ago (2026-08-14 21:46 UTC)
2
Apache 2.0

AgentBus

⚡ 30-Second Quickstart (The "Ah-Ha" Moment)

1. Install

2. Launch the Visual Monitor (Terminal A)

3. Send Your First Message (Terminal B)

🛠️ Why AgentBus?

📦 Fresh Boot & Installation Guide

Option A: 1-Line Universal Installer (Recommended for fresh systems)

Option B: Standalone CLI Tool (pipx or uv)

Option C: In an existing virtual environment

🔌 Connecting Your AI Coding Agents

1-Click Auto-Configuration

Manual IDE Configurations

For Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

For Claude Desktop (claude_desktop_config.json)

💡 Practical Examples for Beginners & Intermediates

Example 1: CLI Coordination (Zero Code)

Example 2: Python Script (Publishing & Polling)

Example 3: Human-in-the-Loop (HITL) Safety Intercepts

Example 4: Preventing File Collisions with Advisory Locks

Example 5: 1-Click Multi-Agent Swarm (agentbus up)

📚 Complete Examples Catalog

⌨️ CLI Cheat Sheet

📖 Deep-Dive Documentation

📄 License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

For Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)

For Claude Desktop (`claude_desktop_config.json`)

Example 5: 1-Click Multi-Agent Swarm (`agentbus up`)