Overview

BreakoutRoom MCP Server implements a Model Context Protocol (MCP) control plane to orchestrate secure peer-to-peer (P2P) rooms for autonomous agents and human collaborators. Instead of centralizing data and model state, the server provides lightweight room management, authentication, and signaling so agents can discover peers and establish direct P2P channels (typically WebRTC). This reduces latency and bandwidth, and gives teams stronger control over where sensitive data flows.

This server is useful when building multi-agent systems, human-in-the-loop workflows, or edge-first applications where agents coordinate to accomplish goals without a heavy central store. The MCP server focuses on coordination primitives (rooms, access tokens, events) while leaving payload transport and model compute to peers.

Features

Room lifecycle management: create, list, join, and revoke rooms/tokens
Secure access: JWT-based tokens and scoping for per-room permissions
WebRTC signaling for peer-to-peer connections (offer/answer/ICE exchange)
Optional TURN/STUN support for NAT traversal
Webhook and event hooks for integration with orchestration systems
Lightweight persistence for auditing and short-lived room state
REST API and WebSocket endpoints for control and signaling
Extensible: hooks for custom authentication and storage backends

Installation / Configuration

Requirements: Node.js 18+, optional Docker.

Clone and install:

git clone https://github.com/agree-able/room-mcp.git
cd room-mcp
npm install

Environment variables (example):

# .env
PORT=3000
JWT_SECRET="replace-with-a-strong-secret"
DATABASE_URL="sqlite://./data.db"   # or Postgres URL
TURN_URL=""                         # optional TURN server URL (for ICE)
STUN_SERVERS="stun:stun.l.google.com:19302"
ALLOW_GUESTS=false

Run locally:

npm run build
npm start
# or in development
npm run dev

Docker:

docker build -t breakoutroom-mcp .
docker run -e JWT_SECRET="secret" -p 3000:3000 breakoutroom-mcp

Docker Compose (example):

version: "3.8"
services:
  mcp:
    image: breakoutroom-mcp:latest
    ports:
      - "3000:3000"
    environment:
      - JWT_SECRET=supersecret
      - DATABASE_URL=postgres://user:pass@db:5432/mcp
  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=mcp

Available Resources

API endpoints (summary)

Method	Path	Description
POST	/rooms	Create a new room
GET	/rooms	List rooms
POST	/rooms/:id/join	Request a join token
POST	/rooms/:id/signal	WebRTC signaling (offer/answer/ICE)
GET	/rooms/:id	Get room metadata
POST	/webhooks	Register event webhook

Example: create a room

curl -X POST https://{SERVER_URL}/rooms \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{"name":"planning-room","ttl":3600,"maxPeers":4}'

Join a room (request token):

curl -X POST https://{SERVER_URL}/rooms/{roomId}/join \
  -H "Authorization: Bearer ${USER_JWT}" \
  -d '{}'
# returns a short-lived join token to use for signaling

Signaling over WebSocket (pseudo):

Connect to wss://{SERVER_URL}/signal with Authorization: Bearer
Exchange JSON messages: { type: “offer”|“answer”|“ice”, payload: … }

SDKs / client helpers

The repo includes minimal JavaScript helpers to perform token acquisition and WebRTC handshake. Use these as a starting point for integrating agent runtimes.

Use Cases

Multi-agent task planning: Split a complex goal among specialized agents (planner, retriever, executor). The planner seeds the room, agents join P2P, exchange small context objects, and coordinate execution without streaming large datasets through the server.
Human-AI handoff: A human-in-the-loop session where a human agent joins a room with an AI agent to review and approve steps. The server enforces per-room tokens and audit logs.
Secure data sharing between agents: Sensitive data can be passed peer-to-peer with end-to-end encryption negotiated between peers; the MCP server only facilitates connection and access control.
Bandwidth-heavy transfers: For payloads like images or model checkpoints, peers can form a direct channel (or use a TURN relay) to avoid central proxying, reducing server egress costs.

Security & Operational Notes

The server issues short-lived JWT join tokens; rotate JWT_SECRET and validate token TTL.
For reliable connectivity in restrictive networks, configure TURN servers and provide TURN credentials via environment variables.
Audit logs: enable persistent storage (Postgres) if you need room history and compliance records.
Run behind TLS and authenticate admin endpoints to avoid unauthorized room creation.

Next Steps

Clone the GitHub repo: https://github.com/agree-able/room-mcp
Try the included example clients to perform a WebRTC handshake between two local agents.
Integrate MCP controls into your agent orchestration: use webhooks to trigger orchestration actions when rooms are created or peers join.

Tags:developer-tools

BreakoutRoom MCP Server for P2P Agent Collaboration