capy-fleet

An MCP server for Capy. Lets Claude Code, Cursor, Codex, or any other MCP client delegate work to Capy's cloud agents and wait for the results without you leaving the editor.

Your local agent is smart, but there's only one of it. This gives it a workforce.

you:  here are 8 bugs, farm them out
      -> capy_delegate x8
      -> capy_wait (all 8)
      -> capy_diff on each
      8 diffs come back, you review them in one place

Not affiliated with Capy. I built it because I wanted it.

Install

Not on npm yet. For now, clone and build:

git clone https://github.com/Takumixbt/capy-fleet.git
cd capy-fleet
npm install
npm run build

You'll need an API token from capy.ai/settings/tokens. It starts with capy_.

Claude Code

claude mcp add capy-fleet --env CAPY_API_KEY=capy_xxx -- node /absolute/path/to/capy-fleet/dist/index.js

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "capy-fleet": {
      "command": "node",
      "args": ["/absolute/path/to/capy-fleet/dist/index.js"],
      "env": {
        "CAPY_API_KEY": "capy_xxx",
        "CAPY_PROJECT_ID": "proj_xxx"
      }
    }
  }
}

Windsurf uses the same shape in ~/.codeium/windsurf/mcp_config.json.

Codex

~/.codex/config.toml:

[mcp_servers.capy-fleet]
command = "node"
args = ["/absolute/path/to/capy-fleet/dist/index.js"]
env = { CAPY_API_KEY = "capy_xxx", CAPY_PROJECT_ID = "proj_xxx" }

Setting CAPY_PROJECT_ID is optional but saves you passing a project id on every call. Run capy_projects once to find yours.

Related MCP server: agent-comm

Tools

Things that will confuse you if nobody tells you

Threads spawn tasks, and diffs belong to tasks. You delegate to a thread and get back a thread id, but capy_diff wants a task id. Task ids show up in the thread's task list, which capy_status and capy_wait both print. This mirrors how Capy's API actually works rather than papering over it.

There is no PR endpoint. Capy's API can't open a pull request directly. capy_open_pr sends the agent a message asking it to do it, which means the PR shows up a bit after the call returns, not during it. Run capy_wait after and read the URL off the result.

No streaming, no webhooks. The API is poll-only, so capy_wait polls with backoff (3s, growing to 15s). It returns early if a thread gets blocked on an auth or permission gate, because sitting there waiting on something that needs a human is useless. If it times out, nothing is lost. The agents keep running on Capy's side and you just call capy_wait again with the same ids.

Tasks are read-only over the API. Older unofficial Capy wrappers used POST /tasks endpoints that no longer work. Everything here goes through threads, which is the supported path.

Not burning your credits by accident

Delegating spends real money, and an LLM in a loop can delegate a lot.

• CAPY_FLEET_MAX_DELEGATIONS caps how many threads one server process will start. Defaults to 25. Set it to 0 if you really want it uncapped.

• CAPY_FLEET_READONLY=1 registers only the read tools. Handy if you want an agent that can watch the fleet but not spend anything.

• capy_diff truncates to a byte budget instead of dumping a 40k-line patch into your context. Use stats_only first, then pull specific paths.

Config reference

Development

npm run build     # compile
npm run watch     # compile on change
npm run smoke     # start the server over stdio, check every tool registers

The smoke test uses a deliberately invalid token, so the only network call it makes is one that's supposed to come back 401. It's checking that the tools register and that errors come back readable, not that your account works.

Types in src/types.ts are transcribed from Capy's published OpenAPI document. If Capy ships changes, that's the file to update first.

License

MIT