# MCP channel

A lightweight MCP channel server that lets agentic agents discover and communicate with each other through direct messages and named channels.
Built for multi-agent orchestration.

## Architecture

```
┌─────────────┐     HTTP/SSE     ┌────────────┐     HTTP/SSE     ┌─────────────┐
│    Agent    │◄────────────────►│   Broker   │◄────────────────►│    Agent    │
│  Session A  │  (channel.ts)    │ (broket.ts)│  (channel.ts)    │  Session B  │
└─────────────┘                  └────────────┘                  └─────────────┘
```

Each agent session spawns its own `channel.ts` MCP server as a subprocess. These servers connect to a shared `broker.ts` HTTP server that routes messages between them.

## Quick Start

### 1. Install dependencies

```bash
bun install
```

### 2. Start the broker

The broker must be running before any agent sessions connect:

```bash
bun run broker.ts
```

By default it listens on port 8900. Override with `CHANNEL_BROKER_PORT=9000 bun run broker.ts`.

### 3. Start agent sessions

In separate terminals, start agent sessions with different names. For Claude Code:

```bash
# Terminal 1
CHANNEL_SESSION_NAME=frontend claude --dangerously-load-development-channels server:channel

# Terminal 2
CHANNEL_SESSION_NAME=backend claude --dangerously-load-development-channels server:channel

# Terminal 3
CHANNEL_SESSION_NAME=coordinator claude --dangerously-load-development-channels server:channel
```

Each session auto-registers with the broker and can immediately communicate.

## Tools Available to the agent

| Tool | Description |
|------|-------------|
| `send_message` | Send a direct message to a session (by name) or to a channel |
| `list_sessions` | List all registered sessions and their online status |
| `list_channels` | List available channels and their members |
| `create_channel` | Create a named channel for group communication |
| `join_channel` | Join an existing channel |
| `leave_channel` | Leave a channel |

## Usage Examples

### Direct messaging

Tell one agent session:
> "Send a message to the backend session asking it to create the API endpoint for /users"

### Channel-based coordination

Tell the coordinator session:
> "Create a channel called 'project' and invite the other sessions to coordinate on building the user dashboard"

### Multi-agent workflow

1. Start a "coordinator" session and tell it the overall plan
2. Start "frontend" and "backend" sessions
3. The coordinator creates a channel, and instructs each agent on their role
4. Agents communicate through the channel to coordinate their work

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `CHANNEL_SESSION_NAME` | `session-<random>` | Human-readable name for this session |
| `CHANNEL_BROKER_URL` | `http://127.0.0.1:8900` | Broker server URL |
| `CHANNEL_BROKER_PORT` | `8900` | Port for the broker (broker.ts only) |

## How It Works

1. **Broker** (`broker.ts`): A lightweight HTTP server that maintains a registry of sessions, manages named channels, and routes messages via SSE streams
2. **Channel MCP Server** (`channel.ts`): An MCP server that agent spawns as a subprocess. It registers with the broker, opens an SSE connection for inbound messages, and exposes tools for sending messages
3. **Message delivery**: When the agent calls `send_message`, the MCP server POSTs to the broker, which pushes the message via SSE to the recipient's MCP server, which delivers it to the recipient's agent session as a `<channel>` notification