Skip to main content

​
Install the SwarmAI MCP CLI

The SwarmAI MCP CLI lets you log in with your SwarmAI API key, start an MCP bridge, and trigger test plans from terminals or CI—keeping the verification layer for coding agents close to your local tools.

​
Prerequisites

  • A SwarmAI API key with run permissions (see Generate an API key)
  • Node.js 18+ or any runtime that can launch a long-lived MCP process

​
Install

Install the CLI from npm or the installer script: 
npm i -g @swarmai/mcp
# or
curl -sSL https://get.swarm.ai/mcp.sh | bash
This installs the swarm binary on your PATH with MCP support for local tool bridges.

​
Log in

Authenticate once and the CLI writes a token to ~/.swarm/mcp.toml. 
swarm auth login --api-key sk-swarm-xxxxxxxx --workspace default
Confirm auth with swarm auth whoami, which prints your workspace, key scope, and token expiry.

​
Connect to MCP

Start the bridge so SwarmAI agents can call local tools exposed via MCP. 
swarm mcp up \
  --workspace default \
  --port 3939 \
  --agent swarm-runner \
  --tools git,fs,nightwatch
While running, the CLI maintains a heartbeat with SwarmAI and surfaces inbound tool calls in the terminal. Stop it anytime with Ctrl+C.

​
Trigger runs from the CLI

Kick off a plan directly: 
# List plans you can run
swarm plans list

# Run everything in a plan using your default reference model
swarm plans run plan_123 \
  --case "*" \
  --ref-model default \
  --notes "Post-merge smoke via MCP"
If your MCP bridge is online, SwarmAI forwards file reads/writes and git metadata requests back to the CLI so the agents can ground their evaluations.

​
Troubleshooting

  • swarm mcp up hangs: another process may be on port 3939; pass --port 4040.
  • Auth errors: regenerate a key in Settings → API Keys and re-run swarm auth login.
  • Verbose output: add --debug to any command to print the JSON RPC chatter between SwarmAI and MCP.