Agent Swarm — Claude Code MCP server: multi-agent orchestration
An MCP server that wires your coding environment into Agent Swarm, a self-hosted system where a lead agent hands work to containerised workers. Useful when tasks arrive from Slack, repos or the API.
claude mcp add agent-swarm -e AGENT_SWARM_API_KEY=<AGENT_SWARM_API_KEY> -- npx -y @desplega.ai/agent-swarmWhat Agent Swarm does
Agent Swarm is an open-source, self-hosted setup for running AI agents. A lead agent picks up goals from Slack, repositories, issue trackers, email or the API, then passes them to workers. Each worker runs in its own Docker container, and memory plus identity carry over between sessions.
The MCP server is the entry point. Through it, your harness — Claude, Codex, Cursor, GitHub Copilot, Windsurf, Cline or Zed — talks to the swarm. Task results can be validated against a schema, deferred tasks wake when watched tasks finish or a deadline hits, and the dashboard takes file attachments. Schedules, scripts and apps cover recurring work. TypeScript extensions land as inert drafts and only a trusted lead, operator or dashboard user can switch them on.
You need an AGENT_SWARM_API_KEY; without it the server will not connect. Two transports are available: stdio through npx -y @desplega.ai/agent-swarm, or HTTP at https://{swarm_host}/mcp-user. Standing up the swarm itself is separate — the installer checks Docker and Compose v2, adds Bun if it is missing, then runs agent-swarm onboard --yes. It starts with the single-agent solo preset, so pass --preset full to get every official template.
What it helps with
- connect a coding harness to an agent orchestrator over MCP
- route tasks from Slack and repositories to worker agents
- keep agent memory and identity alive across sessions
- set up deferred tasks that wake on a deadline
- run recurring work on a schedule
Example prompts for the agent
- Add the Agent Swarm MCP server to Claude using the API key from my environment
- List the Agent Swarm tasks and show their statuses
- Create a deferred task that wakes once all watched tasks finish
How to install Agent Swarm
1Platform CLI
claude mcp add agent-swarm -e AGENT_SWARM_API_KEY=<AGENT_SWARM_API_KEY> -- npx -y @desplega.ai/agent-swarmReplace <…> with your own values
2Platform CLI: remote server
claude mcp add --transport http agent-swarm https://{swarm_host}/mcp-user1Platform CLI
codex mcp add agent-swarm --env AGENT_SWARM_API_KEY=<AGENT_SWARM_API_KEY> -- npx -y @desplega.ai/agent-swarmReplace <…> with your own values
2Platform CLI: remote server
codex mcp add agent-swarm --url https://{swarm_host}/mcp-user1Config file
{
"mcpServers": {
"agent-swarm": {
"command": "npx",
"args": [
"-y",
"@desplega.ai/agent-swarm"
],
"env": {
"AGENT_SWARM_API_KEY": "<AGENT_SWARM_API_KEY>"
}
}
}
}Replace <…> with your own values
2Config file
{
"mcpServers": {
"agent-swarm": {
"url": "https://{swarm_host}/mcp-user"
}
}
}1Config file
{
"servers": {
"agent-swarm": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@desplega.ai/agent-swarm"
],
"env": {
"AGENT_SWARM_API_KEY": "<AGENT_SWARM_API_KEY>"
}
}
}
}Replace <…> with your own values
2Config file
{
"servers": {
"agent-swarm": {
"type": "http",
"url": "https://{swarm_host}/mcp-user"
}
}
}1Platform CLI
gemini mcp add -e AGENT_SWARM_API_KEY=<AGENT_SWARM_API_KEY> agent-swarm npx -y @desplega.ai/agent-swarmReplace <…> with your own values
2Platform CLI: remote server
gemini mcp add -t http agent-swarm https://{swarm_host}/mcp-userStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Agent Swarm
How do I install Agent Swarm in Claude Code?
Add the marketplace with /plugin marketplace add desplega-ai/agent-swarm, then install the plugin: /plugin install agent-swarm@agent-swarm.
What does Agent Swarm do?
It is a self-hosted system for orchestrating AI agents: a lead agent takes incoming tasks and distributes them to workers in Docker containers, with memory that persists between sessions.
What does the MCP server need to run?
An AGENT_SWARM_API_KEY and a running Agent Swarm instance. It connects either over stdio with npx -y @desplega.ai/agent-swarm or over HTTP at https://{swarm_host}/mcp-user.
