# mcp-agent-bridge

A local MCP server that gives any number of AI agents — Claude Code, OpenCode, Codex, Hermes, OpenClaw, or any MCP-compatible client — a **shared, real-time context** across windows and sessions.

Every write (memory, message, task, artifact) is instantly pushed to all other connected agents via **WebSocket** and **MCP resource notifications**. No polling required.

---

## Features

- **Named contexts** — create isolated workspaces (`hackathon`, `my-project`, `review`) and choose which one each agent joins
- **Real-time push** — WebSocket + MCP `notifications/resources/updated` on every state change
- **Any agent type** — works with Claude Code, OpenCode, Codex, Hermes, OpenClaw, or anything that speaks MCP
- **Shared memory** — key/value store scoped per context
- **Tasks** — create, assign, and track tasks across agents
- **Messaging** — direct messages and broadcast within a context
- **Artifacts** — share code, plans, JSON, markdown between agents
- **Discussions** — threaded brainstorm threads per topic
- **Sessions** — orchestrated multi-agent collaboration sessions
- **Persistent** — all state is written to JSON files and survives restarts

---

## Quick Start

```bash
git clone https://github.com/YOUR_USERNAME/mcp-agent-bridge
cd mcp-agent-bridge
npm install
npm start
```

Server runs on `http://localhost:3721`.

---

## Client Configuration

### Claude Code

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "agent-bridge": {
      "type": "http",
      "url": "http://localhost:3721/mcp"
    }
  }
}
```

### OpenCode

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "agent-bridge": {
      "type": "remote",
      "url": "http://localhost:3721/mcp",
      "enabled": true
    }
  }
}
```

### Any MCP client (Streamable HTTP)

Endpoint: `http://localhost:3721/mcp`

### Legacy SSE clients

Endpoint: `http://localhost:3721/sse`

### WebSocket (real-time events, no MCP required)

```js
const ws = new WebSocket("ws://localhost:3721/ws");
ws.on("message", (data) => console.log(JSON.parse(data)));
```

---

## Auto-start (macOS launchd)

Create `~/Library/LaunchAgents/com.mcp-agent-bridge.plist`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.mcp-agent-bridge</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/node</string>
    <string>/path/to/mcp-agent-bridge/server.js</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/mcp-agent-bridge.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/mcp-agent-bridge.log</string>
</dict>
</plist>
```

```bash
launchctl load ~/Library/LaunchAgents/com.mcp-agent-bridge.plist
```

---

## Usage

### 1. Register your agent

Always call `identify` first. Optionally join a context immediately.

```
identify("claude", session_label="window-2", context="my-project")
```

### 2. Create and join contexts

```
create_context("hackathon", description="Weekend project")
join_context("hackathon")
```

All subsequent operations (memory, tasks, messages, etc.) are scoped to `hackathon`.

### 3. Share memory in real-time

```
set_memory("stack", "Next.js + Postgres")
get_memory()
```

Any other agent in the same context receives a `notifications/resources/updated` push and a WebSocket event instantly.

### 4. Send messages

```
send_message("opencode", "DB schema is ready, check artifacts")
read_messages()
broadcast("Starting code review now")
```

### 5. Coordinate with tasks

```
create_task("Write API routes", "Implement /api/notes CRUD", assigned_to="codex")
list_tasks(filter="mine")
update_task("<id>", status="done", notes="All routes covered with tests")
```

### 6. Share code and plans

```
save_artifact("db-schema", "<SQL>", type="code", language="sql")
get_artifact("db-schema")
```

### 7. Check context status

```
list_contexts()       # all workspaces + who's in them
context_status()      # your current context summary
agent_status()        # all agents grouped by context
```

---

## MCP Tools Reference

### Context Management

| Tool | Description |
|---|---|
| `create_context(name, description?)` | Create a named workspace |
| `list_contexts()` | List all contexts with active agents and stats |
| `join_context(name)` | Switch to a context — all ops become scoped to it |
| `leave_context()` | Return to `default` context |
| `delete_context(name, confirm: true)` | Delete context and all its data |
| `context_status()` | Show current context, peers, memory/task counts |

### Identity

| Tool | Description |
|---|---|
| `identify(agent_name, session_label?, context?)` | Register this session; optionally join a context |

### Memory

| Tool | Description |
|---|---|
| `set_memory(key, value, tags?)` | Write to shared memory — peers notified instantly |
| `get_memory(key?, tag?)` | Read one key or list all (optionally filter by tag) |
| `delete_memory(key)` | Remove a key |

### Messaging

| Tool | Description |
|---|---|
| `send_message(to, content, metadata?)` | Direct message to an agent in context |
| `read_messages(mark_read?, include_read?)` | Read your inbox |
| `broadcast(content)` | Send to all agents in context |

### Tasks

| Tool | Description |
|---|---|
| `create_task(title, description, assigned_to, priority?)` | Create and assign a task |
| `list_tasks(filter?)` | List tasks (`all`, `mine`, `pending`, `in_progress`, `done`, `blocked`) |
| `update_task(id, status?, notes?)` | Update status or add progress notes |

### Artifacts

| Tool | Description |
|---|---|
| `save_artifact(name, content, type, language?, description?)` | Save code/text for sharing |
| `get_artifact(name)` | Retrieve an artifact |
| `list_artifacts(type?)` | List all artifacts |

### Discussion

| Tool | Description |
|---|---|
| `add_to_discussion(topic, content)` | Add to a named thread |
| `get_discussion(topic?)` | Read a thread or all threads |

### Session / Orchestration

| Tool | Description |
|---|---|
| `start_session(goal, context?)` | Start a collaborative session; peers notified |
| `get_session()` | Get active session details |
| `end_session(summary?)` | End the session |

### Status & Events

| Tool | Description |
|---|---|
| `agent_status()` | All connected agents grouped by context |
| `get_events(since?, type?, limit?)` | Poll event log since a timestamp |

---

## MCP Resources

All resources are live — reading them always returns current state. Agents receive `notifications/resources/updated` when the underlying data changes.

| URI | Content |
|---|---|
| `agent-bridge://contexts/{context}/memory` | Shared memory for a context |
| `agent-bridge://contexts/{context}/tasks` | Tasks for a context |
| `agent-bridge://contexts/{context}/session` | Active session |
| `agent-bridge://contexts/{context}/discussion` | Discussion threads |
| `agent-bridge://contexts/{context}/artifacts` | Shared artifacts |
| `agent-bridge://contexts/{context}/messages/{agent}` | Agent inbox |

---

## WebSocket Protocol

Connect to `ws://localhost:3721/ws`.

**On connect** — receive a full state snapshot:
```json
{
  "type": "snapshot",
  "data": {
    "contexts": [{ "name": "default", "active_agents": [], "memory": {}, "tasks": [] }]
  },
  "timestamp": "2026-03-26T..."
}
```

**Events pushed on every mutation:**
```json
{ "type": "memory_updated", "context": "hackathon", "data": { "key": "stack", "updated_by": "claude" }, "timestamp": "..." }
{ "type": "message_sent",   "context": "hackathon", "data": { "from": "claude", "to": "opencode" }, "timestamp": "..." }
{ "type": "task_created",   "context": "hackathon", "data": { "title": "...", "assigned_to": "codex" }, "timestamp": "..." }
{ "type": "agent_connected","context": "hackathon", "data": { "agent": "hermes" }, "timestamp": "..." }
```

**Commands you can send:**
```json
{ "type": "ping" }
{ "type": "subscribe_events_since", "since": "2026-03-26T10:00:00Z", "context": "hackathon" }
```

---

## REST API

| Endpoint | Description |
|---|---|
| `GET /health` | Server status, all contexts, connected agents |
| `GET /contexts` | List all contexts with active agents and stats |
| `GET /contexts/:name` | Context details including memory and tasks |

---

## Data Storage

All state is persisted to `./data/`:

```
data/
  contexts_meta.json     — registry of all context names + metadata
  ctx_default.json       — state for the "default" context
  ctx_hackathon.json     — state for the "hackathon" context
  ctx_my-project.json    — ...
```

Each context file contains `memory`, `tasks`, `messages`, `artifacts`, `session`, `discussion`, and `events`.

---

## Supported Agent Types

Any MCP client works. Tested with:

- **Claude Code** (Anthropic)
- **OpenCode** (open source)
- **Codex CLI** (OpenAI)

And any client you register via `identify("your-agent-name")`.

---

## License

MIT