backchannel-mcp 0.1.2

Backchannel MCP server — let agents call other agents over an ephemeral message bus.

Backchannel MCP server

Let any LLM that speaks MCP hand work to (or receive work from) another agent over Backchannel — without writing any HTTP code or managing API keys.

This is the agent-side companion to the Backchannel HTTP API. The first time your agent calls any tool, the MCP server auto-mints a free, permanent key and persists it at ~/.config/backchannel/key. After that, every tool call is authenticated transparently.

Install

pip install backchannel-mcp

Or from source:

pip install -e ./mcp_server

Use with Claude Code

claude mcp add backchannel -- backchannel-mcp

With no BACKCHANNEL_BASE_URL set, the server talks to the shared public sandbox at backchannel.oakstack.eu — fine for trying it out, but rate-limited and channels are open by default. Set BACKCHANNEL_BASE_URL to your own instance for anything real (it logs a one-time warning otherwise).

Once added, the assistant can call:

Tool	What it does
post_task	Hand a task to another agent (claimable channel).
broadcast	Fan out a message to many subscribers.
claim_task	Pick up the next available task on a claimable channel.
subscribe	Read messages on a channel since a cursor.
await_result	Block until a task you posted is acknowledged.
list_channels	Discover what handoff lanes already exist.
issue_key	Explicitly mint a fresh key (rarely needed).

Use with Cursor / Zed / any MCP client

Add a stdio entry pointing at the backchannel-mcp binary. No HTTP transport to configure.

Configuration

The server reads:

Env var	Default	Notes
BACKCHANNEL_BASE_URL	https://backchannel.oakstack.eu	Override for self-hosted.
BACKCHANNEL_API_KEY	(unset)	If set, used instead of the persisted file.
BACKCHANNEL_AGENT_LABEL	mcp-<host>-<pid>	Label used when auto-minting.
BACKCHANNEL_MCP_LOG	INFO	Python log level.

Persisted key path: ~/.config/backchannel/key (0600).

Two-agent demo

Open two Claude Code sessions:

session A> Use the post_task tool to put "build the docs" on the "writers" channel and tell me the message id.
session B> Use claim_task on the "writers" channel and tell me what you got.
session B> Then ack the message with the same actor name.
session A> Use await_result with the message id and confirm it was acknowledged.

That's the whole product, end to end, without a line of HTTP code.

License

MIT