Home
MCP Swarm

MCP Swarm

Agent Skills for the botz MCP Swarm CLI. The botz-mcp-swarm plugin lets your agent capture test suites from live MCP servers, run repeatable assertions and load tests, compare runs, review tool descriptions, record and replay wire traffic, diagnose failures, and upgrade saved suites.

The plugin ships skills and slash commands only — no MCP server or executable is bundled. On first use the skills install the botz host (@zotoio/botz-cli) and its mcp-swarm extension if they are missing.

Install

Client	Marketplace file	Install
Cursor	`.cursor-plugin/marketplace.json`	Add `zotoio/zoto-agents` as a marketplace, then install botz-mcp-swarm.
Claude Code	`.claude-plugin/marketplace.json`	`/plugin marketplace add zotoio/zoto-agents`, then `/plugin install botz-mcp-swarm@zoto-agents`
Codex	`.agents/plugins/marketplace.json`	`codex plugin marketplace add zotoio/zoto-agents`, then install from `/plugins`

The plugin carries a manifest per client — plugin.json (Agent Plugins 1.0, with OpenAI metadata under extensions["com.openai"]), .cursor-plugin/plugin.json, and .claude-plugin/plugin.json — all discovering the same skills/.

Requirements: Node.js 22.13+, npm, and shell access. Live capture and runs need network access to the target MCP server.

First-run setup

Every skill runs commands through the botz host as botz mcp-swarm (never the standalone botz-mcp-swarm or swarm executables). Before the first command in a session a skill:

Runs botz --version. If missing, checks node --version (22.13+) and installs the host with npm install -g @zotoio/botz-cli, telling you it did so. If Node is too old or the global install fails, it stops and reports — it never uses sudo or changes npm configuration.
Runs botz plugins info mcp-swarm --json; if installedVersion is null, runs botz plugins install mcp-swarm.
Confirms with botz mcp-swarm --version and checks a subcommand's --help before unfamiliar options.

npm install -g @zotoio/botz-cli
botz plugins install mcp-swarm
botz mcp-swarm --version

Skills & commands

All skills set disable-model-invocation: true, so they never trigger on their own. Run them by name (for example /mcp-swarm) or through their /z-<skill> command — a light wrapper that loads the skill with the text after the command as the request.

Skill	Command	Use it to
`mcp-swarm-guided`	`/z-mcp-swarm-guided`	Be walked through testing a server: target, credentials, test data, tool selection, and load, then capture, review, run, and summary.
`mcp-swarm`	`/z-mcp-swarm`	Capture, validate, refresh, and run suites directly, including suites that call several servers.
`mcp-swarm-flow`	`/z-mcp-swarm-flow`	Turn a task described in words into a suite whose steps call several MCP servers in order and pass values between them.
`mcp-swarm-report`	`/z-mcp-swarm-report`	Visualise one run in Cursor's `/canvas` or a self-contained HTML page, with VUs/TPS over time (`loadTimeline`/`timeSeries`) and a tool selector showing each tool's latency, errors, and sample request and response.
`mcp-swarm-compare`	`/z-mcp-swarm-compare`	Compare two runs or a series, and chart latency, error rate, and tool-eval trends in Cursor's `/canvas` or a self-contained HTML page.
`mcp-swarm-descriptions`	`/z-mcp-swarm-descriptions`	Review a server's tool descriptions, examine `optimize` suggestions, and measure a change with tool evals.
`mcp-swarm-record-replay`	`/z-mcp-swarm-record-replay`	Record redacted wire traffic and replay it as recorded, at maximum rate, or paced.
`mcp-swarm-diagnose`	`/z-mcp-swarm-diagnose`	Explain failed runs, missing credentials, and regressions.
`mcp-swarm-analyse`	`/z-mcp-swarm-analyse`	Have the model propose suite fixes for a failed run; review and accept or reject each proposal by explicit id.
`mcp-swarm-upgrade`	`/z-mcp-swarm-upgrade`	Update the CLI and migrate saved suites to the current layout.

mcp-swarm-compare ships scripts/runs-dataset.mjs and mcp-swarm-report ships scripts/run-dataset.mjs; both need only Node.js.

Usage

In your agent

/z-mcp-swarm-guided https://api.example.com/mcp
/z-mcp-swarm capture http://127.0.0.1:3000/mcp as docs-server and run it
/z-mcp-swarm run docs-server with concurrency 4 for 30 seconds
/z-mcp-swarm-flow find an open bug in GitHub, file it in Jira, and post to #triage
/z-mcp-swarm-report the latest docs-server run
/z-mcp-swarm-compare the last two docs-server runs
/z-mcp-swarm-descriptions docs-server
/z-mcp-swarm-record-replay record node server.mjs
/z-mcp-swarm-diagnose why did the docs-server run exit 2?
/z-mcp-swarm-analyse why did the docs-server run fail, and what should change?
/z-mcp-swarm-upgrade preview only

CLI commands the skills run

botz mcp-swarm suite capture --url http://127.0.0.1:3000/mcp --name docs-server
botz mcp-swarm suite show --suite docs-server
botz mcp-swarm suite validate --suite docs-server --json
botz mcp-swarm doctor --suite docs-server --json
botz mcp-swarm suite run --suite docs-server --format json

# Add a second server to a multi-server suite and override one server at run time
botz mcp-swarm suite capture --url https://gh.example/mcp --name triage --alias github --bearer-env GH_TOKEN
botz mcp-swarm suite server add --suite triage --alias jira --url https://jira.example/mcp --bearer-env JIRA_TOKEN
botz mcp-swarm suite run --suite triage --target jira=https://staging-jira.example/mcp --bearer-env jira=JIRA_STAGING_TOKEN

# Inspect server drift without executing target tools
botz mcp-swarm suite refresh --suite docs-server --dry-run

# Propose reviewed fixes for a failed run and apply or reject by explicit id
botz mcp-swarm suite analyse docs-server --format json
botz mcp-swarm suite analyse docs-server --from .botz/mcp-swarm/runs/botz-run-123.analysis.json --apply p1

# Compare two run reports
botz mcp-swarm compare --base base.json --head head.json

For stdio servers, substitute --command <bin> and repeated --arg <value> for --url. Capture contacts the live server; review captured arguments and enabled steps before running, because tool calls can change target data. Write-like tools are never silently enabled.

Every suite, report summary, and chart names the server under test as <server name> <version> (<URL or command>), taken from the report's server field (or the saved suite for reports from CLI 0.6.1 and earlier).

Configuration

Setting	Details
Suite location	`.botz/mcp-swarm/suites/<name>` at the Git root, or `~/.botz/mcp-swarm/suites` outside a repository.
`suitesDir`	Set in `.botz/mcp-swarm/settings.json` to store suites elsewhere.
Credentials	Pass environment references, e.g. `--bearer-env MCP_TOKEN` or `--header-env X-Api-Key=MCP_KEY` (stdio: `--env-from K=VAR`). For multi-server suites, prefix with the server alias (`--bearer-env jira=JIRA_TOKEN`, `--header-env jira:X-Api-Key=JIRA_KEY`) and override endpoints with `--target <alias>=<url>`. Secrets are never printed or written to suite files.
Load & ramp-down	`--duration-ms`, `--concurrency`, `--ramp-up-ms`, `--ramp-down-ms`, `--ramp-down-strategy <graceful\|immediate>` (default `graceful`), and `--drain-timeout-ms <ms>`. Passes or session opens cut off after the drain deadline count under `report.rampDown` as cancelled rather than errors.
Suite limits	`limits` in `suite.json` (`maxCallCount` default 100000, `maxPayloadBytes` default 1048576), overridden with `--max-call-count <n>` / `--max-payload-bytes <n>` or `SWARM_MAX_CALL_COUNT` / `SWARM_MAX_PAYLOAD_BYTES` (recorded in `report.limits`).
Rate-limit retries	HTTP 429, `Retry-After` headers, and rate-limit errors use the `rate_limit` error class (separate from `auth`) and are retried automatically with exponential backoff + jitter (`load.retry`; `{ "enabled": false }` disables it), recorded in `report.retries`.
Inference & analyse	Opt-in with `--inference` for model evals, or `suite analyse <suite>` to propose reviewed fixes (`--apply <ids>` / `--reject <ids>`). Ordinary capture and runs need no model credentials.
Legacy layout	`.botz/suites` (pre-0.6) is still read; use `mcp-swarm-upgrade` to move it rather than editing it.

Exit codes & CI

Use --format json or --format junit in CI and preserve the process exit status.

Exit	Meaning (saved-suite runs)
`0`	Pass
`1`	Failed verdict (offline diagnostics also use 1 for failed checks)
`2`	Configuration / execution error
`130` / `143`	Interrupted

A report existing, or a run where no enabled tools executed, is never treated as success. Manifest runs have different error semantics — inspect the report.

Troubleshooting & limits

botz not found / install fails: install Node.js 22.13+ and retry; the skills won't use sudo or alter npm config.
Failed or erroring run: start offline with suite validate and doctor (no target or model contact), or run /z-mcp-swarm-diagnose. Use doctor --inference for model configuration issues.
Missing credentials: doctor reports missing environment-variable names without reading their values.
Schema drift: suite refresh --dry-run diffs the live surface without executing tools; review before applying.
Existing suite: capture refuses to overwrite unless --force is supplied.
Old directories (.botz/suites, .runs, .swarm-data, .otel): run /z-mcp-swarm-upgrade (needs mcp-swarm 0.6.1+). Skills installed by CLI 0.6.x can be removed with botz mcp-swarm skills uninstall.