MCP server

alineo-mcp is an MCP server that exposes alineod's swarm-control API as tools, so an AI client can create a run, fork agents, steer them, and collect their results without you writing any HTTP calls.

MCP client ── stdio ──▶ alineo-mcp ── HTTP + SSE ──▶ alineod ──▶ OpenSandbox + Pi
(Claude Code, Cursor, …)  (npx, local process)         (daemon)

It is a small local process, not a hosted service. The client launches it over stdio, and it talks to an alineod that you (or init) have running. It is published on npm as alineo-mcp.

Connect a client

There is nothing to install. The client runs npx -y alineo-mcp on demand.

claude mcp add alineo -- npx -y alineo-mcp

# only for the current project
claude mcp add alineo --scope project -- npx -y alineo-mcp

{
  "mcpServers": {
    "alineo": {
      "command": "npx",
      "args": ["-y", "alineo-mcp"]
    }
  }
}

{
  "mcpServers": {
    "alineo": {
      "command": "bunx",
      "args": ["alineo-mcp"]
    }
  }
}

Restart the client and it will list 16 tools, named {subject}_{verb} — run_start, agent_spawn, spec_add and so on.

Pass environment variables through the client

Many clients start MCP servers with a limited environment rather than your shell's, so set anything alineo-mcp needs in the config's env block:

{
  "mcpServers": {
    "alineo": {
      "command": "npx",
      "args": ["-y", "alineo-mcp"],
      "env": {
        "ALINEOD_URL": "http://127.0.0.1:4600",
        "NVIDIA_API_KEY": "nvapi-..."
      }
    }
  }
}

For Claude Code: claude mcp add alineo --env NVIDIA_API_KEY=nvapi-... -- npx -y alineo-mcp.

Start alineod

Every run_*, agent_* and result_* tool needs alineod reachable at ALINEOD_URL (default http://127.0.0.1:4600). Either:

• Ask the client to call init. It starts OpenSandbox and alineod in Docker, pulling images if needed, and writes alineo.config.json in the current directory if missing. It forwards any model provider key found in alineo-mcp's own environment into the alineod container, which is why the key belongs in the env block above. This is the same setup as alineo init.
• Or run alineod yourself, as described in the Quickstart and Deployment, and point ALINEOD_URL at it.

Run a swarm from chat

With the server connected and alineod up, you can describe the swarm and let the client drive the tools:

Add the agent spec at ./agents/reviewer.json, start a run with it, fork two child agents from the root, and give me each one's result.

Behind that, the client makes calls in roughly this order:

For a complete, runnable version of this flow, see the MCP Agent Swarm cookbook: a lead agent forks two reviewers, one is paused and the other steered, and an editor merges their findings, all through these tools.

Tools

Swarm control (need alineod)

Setup and specs (work without alineod)

Not exposed through MCP yet

The tools cover alineod's core routes, not everything the HTTP API has gained since. These are available over HTTP only:

• scope: "subtree" on pause, resume, and stop (and on steer), which act on an agent and all its descendants. The MCP tools act on the one agent you name. To end a whole swarm, use run_stop.
• GET /agents/:agentId/transcript
• The coordination routes: await, notify-on, and the inbox.

Configuration

alineo-mcp shares alineo.config.json and the spec directory with alineo-cli, so a spec added by either shows up in both.

Troubleshooting

Every tool returns errors as a tool result with isError set instead of crashing the server, so a failed call is visible to the client and safe to retry.