Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@multiagent-mcp Start a multi-agent conversation with @Alice and @Bob about the project architecture."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Collaborative Multi-Agent Turn-Taking Hub over Model Context Protocol (MCP)
Orchestrate synchronized multi-agent dialogues, human-in-the-loop interactions (@user), mention-driven turn queues, and live Markdown transcript tracking on disk.
multiagent-mcp is a specialized Model Context Protocol (MCP) server engineered for multi-agent LLM coordination. It enables multiple AI agents (e.g. Architect, Reviewer, Optimizer) and a human user (@user) to participate in structured, asynchronous-aware, turn-taking discussions.
Instead of chaotic concurrent generations or complicated manual polling, multiagent-mcp coordinates turns via explicit @mentions, maintains an internal FIFO turn queue, handles arrival synchronization barriers, provides incremental unread message slicing, and writes an atomic, live Markdown transcript to disk in real-time.
flowchart TD
subgraph Clients["Agents & User"]
A["🤖 Agent @Alice\n(Architect)"]
B["🤖 Agent @Bob\n(Reviewer)"]
U["👤 User @user\n(Decider)"]
end
subgraph Hub["multiagent-mcp Server (FastMCP)"]
RM["RoomManager Engine"]
TQ["FIFO Turn Queue\n(+1 per @mention)"]
AB["Arrival Barrier &\nWakeup Broadcast"]
UMS["Incremental Unread Slicing\n(last_read_seq_id)"]
end
subgraph Storage["On-Disk Live Transcript"]
MD["📜 Obsidian / Markdown Note\n(Live File Tracking)"]
end
A -->|"1. join_conversation()"| AB
B -->|"2. join_conversation()"| AB
AB -->|"3. Global Wakeup & Welcome"| Clients
A -->|"4. send_message(@Bob, ...)"| RM
RM -->|"Update Turn Queue"| TQ
RM -->|"Append Message"| MD
RM -->|"Wakeup Target"| B
B -->|"5. wait_for_turn() / send_message(@user)"| RM
RM -->|"Signal @user Turn"| U
U -->|"6. send_message(@Alice, ...)"| RMRelated MCP server: Agent Communication MCP Server
@<Name>) & DeduplicationTurns are naturally passed across agents and the user by tagging handles in message content (e.g., "@Bob what do you think?").
Targeted Mentions: Agents should only mention participants who are directly addressed or expected to reply, rather than blindly tagging everyone.
Global Broadcast Tag (@all): In a public message (is_private=False), tagging @all addresses all active participants and enqueues each of them for +1 turn score.
Code Block Isolation: Mentions inside fenced (```) or inline (`) code blocks are automatically stripped before parsing to prevent false turn triggers.
Deduplication: Tagging @Bob multiple times within the same message queues @Bob exactly once (+1 max score per distinct participant per message).
Validation: If a message contains no valid active participant mentions, the server rejects it with a descriptive validation error specifying available handles or @all.
When agents join sequentially via join_conversation, the first participant is blocked in a synchronization barrier.
Once $\ge 2$ participants have joined, the server broadcasts an arrival notice (@Bob est arrivé dans la conversation), automatically unblocks waiting participants, and kick-starts the dialogue.
is_private=True)Public Messages: Appended to the transcript, delivered to all participants, and wakes all waiting listeners.
Private Messages (is_private=True):
Visible and delivered only to the sender and explicitly mentioned recipients.
@all Forbidden: Calling is_private=True with @all raises an explicit ValueError.
Formatted with dedicated 🔒 [Message Privé] blocks in the transcript for the human user.
Strict Transcript Ban: Agents are strictly forbidden from reading the on-disk Markdown transcript file directly (via view_file or shell commands), ensuring zero out-of-band information leaks.
All messages, participant tables, and system notices are written atomically to a specified Markdown file (filepath).
Enables real-time visual inspection in editors like Obsidian, Cursor, or VS Code (ideal for secondary display monitoring).
Each participant maintains a last_read_seq_id.
Calls to wait_for_turn or blocking send_message return only newly arrived unread messages (seq_id > last_read_seq_id), saving LLM context and preventing repetitive processing.
Python $\ge$ 3.10
pip or uv package manager
Clone the repository and install in editable mode:
git clone https://github.com/hjamet/multiagent-mcp.git
cd multiagent-mcp
pip install -e .multiagent-mcp supports both Standard I/O (stdio) (for local CLI integration in Claude Desktop, Antigravity, Cursor) and Server-Sent Events (sse) (for HTTP/networked microservices).
multiagent-mcp stdio# Default binding: 127.0.0.1:8000
multiagent-mcp serve
# Custom host and port
multiagent-mcp serve --host 0.0.0.0 --port 8000When running in SSE mode, the MCP endpoint is available at http://127.0.0.1:8000/sse.
Add multiagent-mcp to your mcp_servers.json (or .cursor/mcp.json / .gemini/antigravity/mcp_servers.json):
{
"mcpServers": {
"multiagent-mcp": {
"command": "multiagent-mcp",
"args": ["stdio"]
}
}
}{
"mcpServers": {
"multiagent-mcp": {
"url": "http://127.0.0.1:8000/sse"
}
}
}Edit your claude_desktop_config.json (located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"multiagent-mcp": {
"command": "multiagent-mcp",
"args": ["stdio"]
}
}
}The server exposes 4 FastMCP tools:
classDiagram
class MultiAgentHub {
+init_conversation(filepath, participants, topic) dict
+join_conversation(handle, name) TurnResult
+list_participants() dict
+wait_for_turn(handle) TurnResult
+send_message(sender, content, is_private) TurnResult
}init_conversationInitializes or resets a conversation room, clears memory structures, and generates the initial Markdown transcript file.
Parameters:
Parameter | Type | Required | Default | Description |
|
| Yes | — | Target path to the Markdown transcript file. |
|
| Yes | — | List of expected participant handles (e.g. |
|
| No |
| Conversation topic or briefing context. |
Returns (dict):
{
"status": "initialized",
"filepath": "notes/Discussions/Architecture.md",
"topic": "Multi-Agent Hub Protocol",
"participants": ["@user", "@Alice", "@Bob"],
"message": "Room initialized with 3 participants."
}join_conversationRegisters a participant in the room. Handles arrival synchronization barriers and broadcasts arrival notices.
Parameters:
Parameter | Type | Required | Default | Description |
|
| Yes | — | Participant handle (e.g. |
|
| No |
| Optional display name (defaults to cleaned handle). |
Returns (TurnResult):
{
"status": "joined",
"active_turn": "@Alice",
"new_messages": [],
"current_queue": [],
"active_participants": ["@user", "@Alice", "@Bob"],
"system_notice": "Joined room. Active participants: 3"
}list_participantsQueries current room participants, active turn speaker, turn queue, and total message count.
Parameters: None.
Returns (dict):
{
"participants": [
{
"handle": "@Alice",
"name": "Alice Architect",
"status": "active",
"joined_at": "2026-08-18T10:20:00+00:00",
"last_read_seq_id": 4
}
],
"active_participants": ["@Alice", "@Bob", "@user"],
"active_turn": "@Bob",
"turn_queue": ["@user"],
"message_count": 5,
"topic": "Architecture Review",
"filepath": "notes/Discussions/Architecture.md"
}wait_for_turnWaits indefinitely for your turn or new incoming messages.
Parameters:
Parameter | Type | Required | Default | Description |
|
| Yes | — | Participant handle (e.g. |
Returns (TurnResult):
{
"status": "your_turn",
"active_turn": "@Alice",
"new_messages": [],
"current_queue": ["@Bob"],
"active_participants": ["@Alice", "@Bob", "@user"],
"system_notice": null
}send_messagePosts a public or private message to the room. Validates mentions, updates the turn queue, appends to the Markdown file, and puts the sender into a waiting loop until it is their next turn or until a new message arrives, returning only new unread messages upon unblocking.
Parameters:
Parameter | Type | Required | Default | Description |
|
| Yes | — | Sender handle (e.g. |
|
| Yes | — | Message content. Must include at least one valid |
|
| No |
| If |
Returns (TurnResult):
{
"status": "your_turn",
"active_turn": "@Alice",
"new_messages": [
{
"id": 4,
"seq_id": 4,
"sender": "@Bob",
"recipients": ["@Alice"],
"content": "I agree with your proposal @Alice.",
"is_private": false,
"timestamp": "2026-08-18T10:21:00+00:00"
}
],
"current_queue": ["@user"],
"active_participants": ["@Alice", "@Bob", "@user"],
"system_notice": "Woken up by incoming message/mention for @Alice."
}multiagent-chat SkillThe multiagent-chat skill demonstrates how a supervisor orchestrates subagents and @user in Obsidian:
sequenceDiagram
autonumber
actor Henri as 👤 Henri (@user)
participant AGY as 👑 Antigravity (Supervisor)
participant Hub as ⚡ multiagent-mcp
participant Alice as 🤖 @Alice (Architect)
participant Bob as 🤖 @Bob (Reviewer)
participant MD as 📜 Live Transcript Note
Henri->>AGY: "Launch debate on AIVC memory protocol"
AGY->>Hub: init_conversation("notes/Debat.md", ["@user", "@Alice", "@Bob"], "AIVC Memory")
Hub->>MD: Creates header and participant table
par Spawn Subagents
AGY->>Alice: invoke_subagent(Role="@Alice", Prompt="...")
AGY->>Bob: invoke_subagent(Role="@Bob", Prompt="...")
end
Alice->>Hub: join_conversation("@Alice")
Note over Alice,Hub: Alice waits at arrival barrier
Bob->>Hub: join_conversation("@Bob")
Hub->>MD: Append "🔔 @Bob est arrivé dans la conversation"
Hub-->>Alice: Wakeup broadcast
Alice->>Hub: send_message("@Alice", "We should use SQLite vector cache. What do you think @Bob?", block=True)
Hub->>MD: Append Alice's message
Hub-->>Bob: Wakeup & Assign Turn
Bob->>Hub: send_message("@Bob", "Good idea, but let's check latency. @user do you approve?", block=True)
Hub->>MD: Append Bob's message
Hub-->>AGY: @user mentioned -> Signal turn to Supervisor
AGY-->>Henri: "C'est à vous de parler : Bob demande votre arbitrage sur la latence."
Henri->>AGY: "Je valide SQLite, la latence est négligeable."
AGY->>Hub: send_message("@user", "Je valide SQLite, la latence est négligeable @Alice.", block=False)
Hub->>MD: Append user message
Hub-->>Alice: Unblock AliceBelow is an example of the live Markdown file generated by multiagent-mcp:
# Multi-Agent Room
- **Fichier :** `notes/Discussions/Architecture_Review.md`
- **Sujet :** Multi-Agent Hub Protocol & AIVC Memory
- **Initialisé le :** 2026-08-18 10:20:00
> [!NOTE]
> 💬 **Dernier message :** **@user** ➔ @Alice, @Bob (10:21:45 UTC)
>
> Approche validée, privilégiez la simplicité d'implémentation @Alice.
## 📊 File d'Attente & État des Participants (Temps Réel)
| Participant | Statut |
|---|---|
| **@Alice** | ⏳ 1 mention |
| **@Bob** | 💤 sleeping |
| **@user** | 💤 sleeping |
---
## Fil de discussion
> 🔔 **Système :** @Bob est arrivé dans la conversation
### 💬 @Alice ➔ @Bob (2026-08-18 10:20:10 UTC)
Nous devons privilégier un protocole à mémoire partagée pour réduire la latence inter-processus. Qu'en penses-tu @Bob ?
---
### 🔒 [Privé] @Bob ➔ @Alice (2026-08-18 10:20:30 UTC)
> Vérifions d'abord la compatibilité Windows avant d'interpeller l'utilisateur.
---
### 💬 @Bob ➔ @user (2026-08-18 10:21:00 UTC)
D'accord sur le principe. @user, validez-vous cette approche pour le déploiement local ?
---
### 💬 @user ➔ @Alice, @Bob (2026-08-18 10:21:45 UTC)
Approche validée, privilégiez la simplicité d'implémentation @Alice.
---This project is licensed under the MIT License.
This server cannot be deployed
Chat where AI agents are first-class members, with their own identity and permissions.
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
Agent-to-agent network for teams: dm, who-knows-X routing, shared rooms. Human-in-the-loop.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.