Agent Coordinator is a MCP proxy server that enables multiple AI agents to collaborate seamlessly without conflicts. It acts as a single MCP interface that proxies ALL tool calls through itself, ensuring every agent maintains full project awareness while the coordinator tracks real-time agent presence.

What is Agent Coordinator?

The coordinator operates as a transparent proxy layer:

Single Interface: All agents connect to one MCP server (the coordinator)
Proxy Architecture: Every tool call flows through the coordinator to external MCP servers
Presence Tracking: Each proxied tool call updates agent heartbeat and task status
Project Awareness: All agents see the same unified view of project state through the proxy

This proxy design orchestrates four core components:

Task Registry: Intelligent task queuing, agent matching, and automatic progress tracking
Agent Manager: Agent registration, heartbeat monitoring, and capability-based assignment
Codebase Registry: Cross-repository coordination, dependency management, and workspace organization
Unified Tool Registry: Seamlessly proxies external MCP tools while adding coordination capabilities

Overview

🏗️ Architecture Components

Core Coordinator Components:

Task Registry: Intelligent task queuing, agent matching, and progress tracking
Agent Manager: Registration, heartbeat monitoring, and capability-based assignment Codebase Registry: Cross-repository coordination and workspace management
Unified Tool Registry: Combines native coordination tools with external MCP tools
Every tool call automatically updates the agent's activity for other agent's to see

External Integration:

VS Code Integration: Direct editor commands and workspace management

External Server Management

The coordinator automatically manages external MCP servers based on configuration in mcp_servers.json:

{
  "servers": {
    "mcp_filesystem": {
      "type": "stdio",
      "command": "bunx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "auto_restart": true,
      "description": "Filesystem operations server"
    },
    "mcp_memory": {
      "type": "stdio",
      "command": "bunx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "auto_restart": true,
      "description": "Memory and knowledge graph server"
    }
  },
  "config": {
    "startup_timeout": 30000,
    "heartbeat_interval": 10000,
    "auto_restart_delay": 1000,
    "max_restart_attempts": 3
  }
}

Prerequisites

Choose one of these installation methods:

Docker

Manual Installation

Elixir: 1.16+ with OTP 26+
Node.js: 18+ (for some MCP servers)
uv: If using python MCP servers

Docker Setup

1. Start NATS Server

First, start a NATS server that the Agent Coordinator can connect to:

# Start NATS server with persistent storage
docker run -d \
  --name nats-server \
  --network agent-coordinator-net \
  -p 4222:4222 \
  -p 8222:8222 \
  -v nats_data:/data \
  nats:2.10-alpine \
  --jetstream \
  --store_dir=/data \
  --max_mem_store=1Gb \
  --max_file_store=10Gb

# Create the network first if it doesn't exist
docker network create agent-coordinator-net

2. Configure Your AI Tools

For STDIO Mode (Recommended - Direct MCP Integration):

First, create a Docker network and start the NATS server:

# Create network for secure communication
docker network create agent-coordinator-net

# Start NATS server
docker run -d \
  --name nats-server \
  --network agent-coordinator-net \
  -p 4222:4222 \
  -v nats_data:/data \
  nats:2.10-alpine \
  --jetstream \
  --store_dir=/data \
  --max_mem_store=1Gb \
  --max_file_store=10Gb

Then add this configuration to your VS Code mcp.json configuration file via ctrl + shift + p → MCP: Open User Configuration or MCP: Open Remote User Configuration if running on a remote server:

{
  "servers": {
    "agent-coordinator": {
      "command": "docker",
      "args": [
        "run",
        "--network=agent-coordinator-net",
        "-v=./mcp_servers.json:/app/mcp_servers.json:ro",
        "-v=/path/to/your/workspace:/workspace:rw",
        "-e=NATS_HOST=nats-server",
        "-e=NATS_PORT=4222",
        "-i",
        "--rm",
        "ghcr.io/rooba/agentcoordinator:latest"
      ],
      "type": "stdio"
    }
  }
}

Important Notes for File System Access:

If you're using MCP filesystem servers, mount the directories they need access to:

{
  "args": [
    "run",
    "--network=agent-coordinator-net",
    "-v=./mcp_servers.json:/app/mcp_servers.json:ro",
    "-v=/home/user/projects:/home/user/projects:rw",
    "-v=/path/to/workspace:/workspace:rw",
    "-e=NATS_HOST=nats-server",
    "-e=NATS_PORT=4222",
    "-i",
    "--rm",
    "ghcr.io/rooba/agentcoordinator:latest"
  ]
}

For HTTP/WebSocket Mode (Alternative - Web API Access):

If you prefer to run as a web service instead of stdio:

# Create network first
docker network create agent-coordinator-net

# Start NATS server
docker run -d \
  --name nats-server \
  --network agent-coordinator-net \
  -p 4222:4222 \
  -v nats_data:/data \
  nats:2.10-alpine \
  --jetstream \
  --store_dir=/data \
  --max_mem_store=1Gb \
  --max_file_store=10Gb

# Run Agent Coordinator in HTTP mode
docker run -d \
  --name agent-coordinator \
  --network agent-coordinator-net \
  -p 8080:4000 \
  -v ./mcp_servers.json:/app/mcp_servers.json:ro \
  -v /path/to/workspace:/workspace:rw \
  -e NATS_HOST=nats-server \
  -e NATS_PORT=4222 \
  -e MCP_INTERFACE_MODE=http \
  -e MCP_HTTP_PORT=4000 \
  ghcr.io/rooba/agentcoordinator:latest

Then access via HTTP API at http://localhost:8080/mcp or configure your MCP client to use the HTTP endpoint.

Create or edit mcp_servers.json in your project directory to configure external MCP servers:

{
  "servers": {
    "mcp_filesystem": {
      "type": "stdio",
      "command": "bunx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "auto_restart": true
    }
  }
}

Manual Setup

Clone the Repository

It is suggested to install Elixir (and Erlang) via asdf for easy version management. NATS can be found at nats.io, or via Docker

git clone https://github.com/rooba/agentcoordinator.git
cd agentcoordinator
mix deps.get
mix compile

Start the MCP Server directly

# Start the MCP server directly
export MCP_INTERFACE_MODE=stdio # or http / websocket
# export MCP_HTTP_PORT=4000 # if using http mode

./scripts/mcp_launcher.sh

# Or in development mode
mix run --no-halt

Run via VS Code or similar tools

Add this to your mcp.json or mcp_servers.json depending on your tool:

{
  "servers": {
    "agent-coordinator": {
      "command": "/path/to/agent_coordinator/scripts/mcp_launcher.sh",
      "args": [],
      "env": {
        "MIX_ENV": "prod",
        "NATS_HOST": "localhost",
        "NATS_PORT": "4222"
      }
    }
  }
}