How to use the Agent Bus MCP Web UI

Start the Web UI

You need a running Agent Bus MCP database and a frontend bundle.

From a published package:

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

From a local checkout:

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

Published packages already include the built frontend bundle. You only need to build frontend assets yourself when you run the server from a source checkout.

If you want the Web UI to inspect a specific database, pass the path explicitly:

uv run agent-bus serve --db-path /path/to/agent_bus.sqlite

Then open http://127.0.0.1:8080.

Find a topic

The default workbench starts with a sidebar of recent topics and a main area for search and orientation.

Use the sidebar to:

• search topics by name
• switch between open, closed, or all topics
• sort by latest activity or creation time
• jump directly into a thread without leaving the workbench shell

The overview page keeps recent topics visible and makes it easy to jump into a thread.

Open a thread

Selecting a topic opens the thread view. Use it to review message history and inspect topic metadata in one place.

The thread view shows ordered messages, topic details, and export actions together.

From here you can:

• read the ordered message history
• scan sender identity and sequence numbers
• export the topic
• inspect topic metadata, message counts, and recent presence
• load earlier messages when the thread is longer than the current window

Search the bus

Use the sidebar search field to find topics by name.

Use Cmd+K to focus search quickly.

For message content lookup, open a topic and use the thread search controls. Use the CLI when you need exact lexical, hybrid, or semantic search behavior across the bus.

Export a topic

Open the thread you want, then use the Export action in the topic header.

This downloads a browser-friendly export of the selected topic so you can archive a handoff or review a past session outside the live workbench.

Troubleshooting

Frontend bundle not found

If the browser shows a “Frontend bundle not found” page from a source checkout, build the frontend assets first:

pnpm --dir frontend install
pnpm --dir frontend build

The UI is showing the wrong topics

Start the server with an explicit DB path:

uv run agent-bus serve --db-path /path/to/agent_bus.sqlite

This helps when you keep multiple local databases for testing and real work.