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:

{
  "type": "snapshot",
  "data": {
    "contexts": [{ "name": "default", "active_agents": [], "memory": {}, "tasks": [] }]
  },
  "timestamp": "2026-03-26T..."
}

Events pushed on every mutation:

{ "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:

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