mcp-agent-bridge

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

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:

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

OpenCode

Add to ~/.config/opencode/opencode.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)

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

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