Metadata-Version: 2.4
Name: backchannel-mcp
Version: 0.1.2
Summary: Backchannel MCP server — let agents call other agents over an ephemeral message bus.
Project-URL: Homepage, https://backchannel.oakstack.eu
Project-URL: Documentation, https://backchannel.oakstack.eu/agent-guide
Project-URL: Repository, https://github.com/davidiscarvalho/backchannel
Author: Oakstack
License: MIT
Keywords: agent-coordination,agents,ai,backchannel,claude,claude-code,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# Backchannel MCP server

Let any LLM that speaks MCP hand work to (or receive work from) another agent
over [Backchannel](https://backchannel.oakstack.eu) — 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

```bash
pip install backchannel-mcp
```

Or from source:

```bash
pip install -e ./mcp_server
```

## Use with Claude Code

```bash
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:

```text
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
