swarm-mcp-server

An MCP server that lets multiple AI coding agents, on one machine or across a network, work as a coordinated swarm. Agents register themselves, claim tasks from a shared queue, message each other, share a knowledge base, and see fleet-wide machine capacity.

Built as the coordination bus for herdr-fleet, but usable by any MCP client (Claude Code, OpenCode, Codex, or your own).

Agents: if you are an AI agent joining a swarm, read AGENTS.md for the etiquette (register, heartbeat, claim-before-work, message hygiene).

Features

• Agent registry - register, heartbeat, find agents by capability; stale agents age out automatically.
• Task queue - create tasks with dependencies and subtasks; agents claim atomically, update status, and hand off.
• Messaging - direct messages, broadcasts, polling, read receipts, conversation history.
• Knowledge base - store and search findings; semantic search via ChromaDB + Ollama embeddings with automatic keyword fallback when neither is running.
• Machine capacity - a REST endpoint for lightweight host heartbeats (RAM, disk, load, agent counts) plus an MCP tool so agents can see the whole fleet before picking work.

27 tools total, all backed by a single SQLite database (WAL mode).

Transports

stdio (default)

Each client spawns the server as a child process; coordination happens through the shared SQLite file. Good for a single machine.

npm install && npm run build
claude mcp add swarm -- node /path/to/swarm-mcp-server/dist/index.js

Streamable HTTP (for a networked swarm)

One long-running instance serves every agent on the network. The transport is stateless: each request gets a fresh server instance, no protocol sessions, so restarts are invisible to clients and any replica can serve any request. All state lives in SQLite. (When the official SDK ships the 2026-07-28 stateless-core MCP spec, this server will adopt it; the current mode is compatible with today's clients.)

openssl rand -hex 32 > ~/.config/fleet/swarm-token && chmod 600 ~/.config/fleet/swarm-token
SWARM_TRANSPORT=http node dist/index.js
# listening on 127.0.0.1:4483

Publish it to your private network without widening the bind, e.g. over Tailscale:

tailscale serve --bg --http=8080 4483

Connect agents from any machine:

claude mcp add --transport http swarm http://<host>:8080/mcp \
  --header "Authorization: Bearer $(cat ~/.config/fleet/swarm-token)"

Every request (MCP and REST) requires the bearer token; a missing or wrong token is a 401.

Configuration

Env var	Default	What
SWARM_TRANSPORT	stdio	http enables the HTTP transport (or pass --http)
SWARM_HTTP_PORT	4483	HTTP port, bound to 127.0.0.1 only
SWARM_TOKEN_FILE	~/.config/fleet/swarm-token	Bearer token file (required in http mode)
SWARM_DATA_DIR	./data	SQLite + vector storage location
SWARM_DB_PATH	<data>/swarm.db	Database file
OLLAMA_BASE_URL	http://localhost:11434	Embeddings for semantic search (optional)
SWARM_HEARTBEAT_TIMEOUT_MS	30000	Agent staleness threshold

Capacity API

fleet report (or anything else) POSTs host metrics without an MCP handshake:

curl -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  http://127.0.0.1:4483/api/capacity \
  -d '{"machine":"home-server","os":"linux","ram_free_mb":9000,"ram_total_mb":16000,"disk_free_mb":120000,"disk_total_mb":500000,"load1":0.4,"cores":8,"pane_count":3,"agent_count":1}'

GET /api/capacity returns all machines; rows older than 60 s carry is_stale: true. Agents get the same view through the machine_capacity_list MCP tool.

Running as a service

Linux (systemd user unit), ~/.config/systemd/user/swarm-mcp.service:

[Unit]
Description=swarm MCP server
[Service]
Environment=SWARM_TRANSPORT=http
ExecStart=/usr/bin/node %h/swarm-mcp-server/dist/index.js
Restart=on-failure
[Install]
WantedBy=default.target

macOS: a LaunchAgent with RunAtLoad + KeepAlive pointing at the same command (herdr-fleet's fleet adopt installs one for you on fleet machines).

Development

npm run typecheck
npm run build      # tsc + copies SQL migrations into dist
npm run dev        # tsx watch, stdio mode

License

MIT