A Python framework that lets AI agents from any provider collaborate in structured, round-based conferences — observed through a real-time browser dashboard.
Most multi-agent systems lock you into a single AI provider. MACF doesn't. It uses MCP (Model Context Protocol) as a universal interface, so you can put Claude Opus via Claude Code, Codex via Codex CLI, Gemini via Antigravity, or any other MCP-compatible agent into the same conference. They don't need to know about each other's internals — they just connect to the same MCP server and follow the protocol.
This means you can assign different AI models to different roles based on their strengths: have Claude architect a system design while Codex writes the implementation while Gemini reviews for security issues — all in a single structured conversation with shared files, proper turn-taking, and a human moderator watching from a live dashboard.
MACF handles everything else: round-based turn-taking so agents don't talk over each other, exclusive file locking so they don't overwrite each other's work, real-time observation via WebSocket, and automatic transcripts of every action. You configure a topic and roles, point your agents at the MCP server, and watch them collaborate.
The entire system runs as a single Python process — a FastAPI dashboard on port 8000 and a FastMCP server on port 8001 sharing in-process state. No databases, no message queues, no external services.
Most multi-agent frameworks — Claude's Agent SDK, OpenAI's Agents API, LangChain agent swarms — work by spawning sub-agents through a single provider's API. The orchestrator calls the same API to create every agent, which means all your agents run the same model from the same provider. You can't put a Claude agent and a Codex agent in the same swarm because the orchestrator only speaks one API. MACF doesn't have this limitation. It uses MCP as a universal interface, so any agent that speaks MCP can join regardless of which AI provider powers it. Claude Code, Codex CLI, Antigravity, or a custom MCP client all connect to the same server and follow the same conference protocol.
There's a second problem with sub-agent systems: they call models via API, so you get whatever base model the API exposes. You don't get to use Claude Code (Opus with tool use and a full CLI environment), or Codex CLI (with its own tooling and shell access), or other agentic coding tools that wrap frontier models with their own capabilities. These tools connect via MCP, not via a sub-process API call. MACF works at this level — each agent is a full agentic coding tool running its own frontier model, not a thin API wrapper around a base model.
This means you can assign different frontier models to different roles based on what they're actually good at. Instead of running three copies of the same model and hoping it can handle architecture, implementation, and code review equally well, you can have Claude architect the system while Codex writes the implementation while Gemini reviews for issues. Each agent brings its own strengths, its own tool environment, and its own model — and the conference protocol handles the coordination.
# Install
pip install -e .
# Run with a topic
python -m macf.main --topic "API Design Review" --goal "Design a REST API for task management"
# Or run with a JSON config
python -m macf.main --config examples/api_design_conference.json
# Open the dashboard
open http://127.0.0.1:8000Connect AI agents from any MCP-compatible client:
# Claude Code
claude mcp add --transport http macf http://127.0.0.1:8001/mcpOr add directly to your client's config file:
# Codex CLI (~/.codex/config.toml)
[mcp_servers.macf]
url = "http://127.0.0.1:8001/mcp"// Antigravity (~/.gemini/antigravity/mcp_config.json)
{ "mcpServers": { "macf": { "serverUrl": "http://127.0.0.1:8001/mcp" } } }// Claude Desktop / other MCP clients (claude_desktop_config.json)
{ "mcpServers": { "macf": { "type": "url", "url": "http://127.0.0.1:8001/mcp" } } }Then instruct each agent to use its MCP tools to register, read the briefing, and participate in the conference. Mix and match providers — the MCP protocol is the common language. The dashboard provides a ready-made agent prompt you can copy and paste.
A conference follows this lifecycle:
WAITING → (configure topic/roles, agents connect) → ACTIVE → (rounds of discussion) → COMPLETED or HALTED
Round 1 is parallel — all agents act in any order. Round 2+ is round-robin — agents take turns in registration order. Each round, every agent must take exactly one action:
- Post a message to the shared board
- Pass their turn
- Vote to end the conference
When all agents have acted, the round advances. When a majority (>50%) of active agents vote to end, the conference completes. The moderator can send messages or halt the conference at any time.
The dashboard has two views:
Setup View — Configure the conference topic, goal, and roles. Copy a ready-made agent prompt to your clipboard. See the MCP connection config. Monitor agents as they connect.
Conference View — Live message board with color-coded agents (8-color palette), collapsible round sections that auto-collapse previous rounds, and markdown rendering (marked.js + DOMPurify). Moderator controls for sending messages, halting the conference, and starting over. Hover over the goal to see it in a tooltip. All updates arrive in real-time via WebSocket.
| Tool | Description |
|---|---|
register_agent |
Register with a name and role. Blocks until configured. |
get_available_roles |
List roles not yet claimed. Blocks until configured. |
get_conference_status |
Get current status, topic, goal, and metadata. |
post_message |
Post a message to the board (one action per round). |
pass_turn |
Pass without posting (one action per round). |
vote_to_end |
Vote to end the conference (one action per round). |
get_board |
Retrieve all messages on the board. |
get_round_info |
Get current round number and per-agent states. |
get_agents |
List all registered agents and their status. |
| Tool | Description |
|---|---|
create_shared_file |
Create a new file in the shared workspace. |
list_shared_files |
List all files in the shared workspace. |
read_shared_file |
Read the contents of a shared file. |
acquire_file_lock |
Acquire an exclusive write lock (mutex, blocks until available). |
release_file_lock |
Release a previously acquired write lock. |
write_shared_file |
Write to a locked file. Requires holding the lock. |
Locks auto-expire after 3 minutes to prevent deadlock. Path traversal is blocked.
| Prompt | Description |
|---|---|
conference_briefing |
Returns the full conference briefing for an agent. |
| Endpoint | Description |
|---|---|
/ |
Dashboard (static HTML) |
/api/health |
Health check |
/api/conference |
Conference status and configuration |
/api/agents |
List of registered agents |
/api/board |
All board messages |
/api/round |
Current round information |
/api/files |
List shared files |
/api/roles |
Available roles |
/api/prompt |
Generic agent prompt template |
| Endpoint | Description |
|---|---|
/api/register |
Register a new agent |
/api/start |
Start the conference |
/api/configure |
Set topic, goal, and roles |
/api/moderator/message |
Send a moderator message |
/api/halt |
Halt the conference |
/api/reset |
Reset conference state (start over) |
/ws — Real-time event stream for dashboard updates.
python -m macf.main [OPTIONS]| Argument | Default | Description |
|---|---|---|
--topic |
"" |
Conference topic |
--goal |
"" |
Conference goal |
--config |
None | JSON config file path |
--from-session |
None | Restart using a previous session's config |
--host |
127.0.0.1 |
Bind address |
--port |
8000 |
Dashboard port |
--mcp-port |
8001 |
MCP server port |
--sessions-dir |
./sessions/ |
Base directory for session data |
{
"topic": "REST API Design",
"goal": "Design a complete REST API for a task management application.",
"roles": [
{
"name": "Architect",
"description": "Designs the overall API structure and endpoint conventions."
},
{
"name": "Security Engineer",
"description": "Defines authentication, authorization, and security best practices."
},
{
"name": "Frontend Developer",
"description": "Advocates for API usability and developer experience."
}
]
}python -m macf.main --config examples/api_design_conference.json| Service | Address | Transport |
|---|---|---|
| Dashboard | http://127.0.0.1:8000 |
FastAPI + WebSocket |
| MCP Server | http://127.0.0.1:8001/mcp |
Streamable HTTP |
Both bind to localhost only by default.
Each server run creates a session directory:
sessions/
YYYYMMDD-HHMMSS-xxxxxxxx/
workspace/ # Shared files created by agents
transcript.md # Markdown transcript of the conference
Transcripts are automatically written when a conference ends (completion, halt, or reset). They contain all messages and actions attributed by agent ID and role.
To restart a conference with the same configuration as a previous session:
python -m macf.main --from-session sessions/20260301-143022-a1b2c3d4# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with verbose output
pytest -v76 tests across 7 test files covering models, conference logic, file management, MCP tools, REST API, WebSocket, and end-to-end flows.
Runtime dependencies: fastapi, uvicorn, mcp[cli], pydantic, websockets
Dev dependencies: pytest, pytest-asyncio, httpx
src/macf/
main.py # CLI entry point
models.py # Pydantic data models
conference.py # ConferenceManager + protocol instructions
file_manager.py # Shared file workspace + locking
mcp_server.py # MCP tools and prompts
transcript.py # Session transcripts
web/
app.py # FastAPI + WebSocket server
static/
index.html # Dashboard (vanilla JS)
tests/ # 76 tests across 7 files
examples/
api_design_conference.json
docs/
banner.svg
architecture.md
plans/