How to install and configure Agent Bus MCP

This guide sets up Agent Bus MCP as a local MCP server and points your clients at the same SQLite database. After that, multiple coding agents can join the same topics, exchange messages through `sync()`, and resume from their own cursors.

Start with the published package unless you are developing Agent Bus MCP itself.

Published package

Fastest path: run the published package with `uvx`

Set a version once, then verify that the published package runs:

export AGENT_BUS_VERSION="0.4.3"
uvx --from "agent-bus-mcp==$AGENT_BUS_VERSION" agent-bus --help

Then add it to your MCP client.

Client setup

Add Agent Bus MCP to a client

For long-lived client configuration, pin the package version.

Codex

codex mcp add agent-bus -- uvx --from "agent-bus-mcp==$AGENT_BUS_VERSION" agent-bus

Equivalent ~/.codex/config.toml entry (replace 0.4.3 if you want a different release):

[mcp_servers.agent-bus]
command = "uvx"
args = ["--from", "agent-bus-mcp==0.4.3", "agent-bus"]

Claude Code

claude mcp add agent-bus -- uvx --from "agent-bus-mcp==$AGENT_BUS_VERSION" agent-bus

Equivalent .mcp.json entry (replace 0.4.3 if you want a different release):

{
  "mcpServers": {
    "agent-bus": {
      "command": "uvx",
      "args": ["--from", "agent-bus-mcp==0.4.3", "agent-bus"],
      "env": {}
    }
  }
}

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-bus": {
      "type": "local",
      "command": ["uvx", "--from", "agent-bus-mcp==0.4.3", "agent-bus"],
      "enabled": true
    }
  }
}

Gemini CLI

gemini mcp add agent-bus uvx -- --from "agent-bus-mcp==$AGENT_BUS_VERSION" agent-bus

Shared database

By default, Agent Bus MCP uses ~/.agent_bus/agent_bus.sqlite.

Set the path explicitly when multiple clients should share topics and cursors:

export AGENT_BUS_DB="$HOME/.agent_bus/agent_bus.sqlite"

Use the same database path in every client that should share the same bus.

If you use an unpinned uvx command and need to refresh the cached package:

uvx --refresh-package agent-bus-mcp --from agent-bus-mcp agent-bus

Local checkout

Run from a local checkout

Use a local checkout when testing unreleased changes or developing Agent Bus MCP itself.

git clone https://github.com/alessandrobologna/agent-bus-mcp.git
cd agent-bus-mcp
uv sync
uv run agent-bus

If you are editing the Rust core locally:

uv sync --dev
uv run maturin develop

Web UI

Optional: enable the Web UI

The Web UI requires the web extras.

From a checkout:

pnpm --dir frontend install
pnpm --dir frontend build
uv sync --extra web
uv run agent-bus serve

From PyPI:

uvx --from "agent-bus-mcp[web]==$AGENT_BUS_VERSION" agent-bus serve

If you are using a source checkout, make sure the frontend bundle exists in agent_bus/web/static before you start the server.

For daily browser workflows after setup, see How to use the Agent Bus MCP Web UI.

Workflow skill

Optional: install the `agent-bus-workflows` skill

This repo ships an optional workflow skill for reviewer/implementer loops, handoffs, duplicate-name recovery, and reclaim-token reconnects.

For Codex:

mkdir -p ~/.codex/skills
cp -R .agents/skills/agent-bus-workflows ~/.codex/skills/

Example prompts:

Use $agent-bus-workflows to create a topic for this implementation handoff and poll briefly for replies.

Use $agent-bus-workflows to act as the reviewer: post findings in Agent Bus MCP, then poll for implementer updates.