# Agent Swarm

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 933
- Author: desplega-ai
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/desplega-ai/agent-swarm
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/agent-swarm

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://{swarm_host}/mcp-user`
- Environment variables: `AGENT_SWARM_API_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI**
```bash
claude mcp add agent-swarm -e AGENT_SWARM_API_KEY=<AGENT_SWARM_API_KEY> -- npx -y @desplega.ai/agent-swarm
```
Replace <…> with your own values

2. **Platform CLI: remote server**
```bash
claude mcp add --transport http agent-swarm https://{swarm_host}/mcp-user
```

### Codex

1. **Platform CLI**
```bash
codex mcp add agent-swarm --env AGENT_SWARM_API_KEY=<AGENT_SWARM_API_KEY> -- npx -y @desplega.ai/agent-swarm
```
Replace <…> with your own values

2. **Platform CLI: remote server**
```bash
codex mcp add agent-swarm --url https://{swarm_host}/mcp-user
```

### Cursor

1. **Config file**
File `.cursor/mcp.json`:
```json
{
    "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

2. **Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "agent-swarm": {
            "url": "https://{swarm_host}/mcp-user"
        }
    }
}
```

### GitHub Copilot

1. **Config file**
File `.vscode/mcp.json`:
```json
{
    "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

2. **Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "agent-swarm": {
            "type": "http",
            "url": "https://{swarm_host}/mcp-user"
        }
    }
}
```

### Gemini CLI

1. **Platform CLI**
```bash
gemini mcp add -e AGENT_SWARM_API_KEY=<AGENT_SWARM_API_KEY> agent-swarm npx -y @desplega.ai/agent-swarm
```
Replace <…> with your own values

2. **Platform CLI: remote server**
```bash
gemini mcp add -t http agent-swarm https://{swarm_host}/mcp-user
```

## When to use it
- 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
- 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

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872
- [AIHawk](https://affpapa.org/en/nevibecode/mcp/aihawk.md) — MCP server · ★ 32221

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md