MCP quickstart

Collimate ships a hosted MCP endpoint so an MCP-capable agent — Claude Code, Cursor, or your own client — can create sandboxes, run commands, write files, and fork a running sandbox as native tool calls. No SDK, no glue code.

• Endpoint: https://mcp.collimate.ai
• Transport: streamable HTTP
• Auth: Authorization: Bearer <your col_ key> — the same API key you use for REST.

The MCP server is a thin, stateless protocol adapter: it authenticates your key and calls the gateway REST on your behalf, scoped to your tenant. Sandbox lineage lives server-side, keyed to your tenant — there is no shared local state file.

Add it to your agent

Claude Code

Add the endpoint with the Claude Code CLI:

claude mcp add --transport http collimate https://mcp.collimate.ai \
  --header "Authorization: Bearer $COLLIMATE_API_KEY"

Then in a session:

> Create a python sandbox, install pandas, and fork it 4 ways.

Cursor

Add to your ~/.cursor/mcp.json (or the project .cursor/mcp.json):

{
  "mcpServers": {
    "collimate": {
      "url": "https://mcp.collimate.ai",
      "headers": {
        "Authorization": "Bearer col_pro_a1b2c3d4e5f60718_..."
      }
    }
  }
}

Reload Cursor; the Collimate tools appear in the MCP tool list.

Raw config

Any MCP client that speaks streamable HTTP works. Point it at the URL and set the Authorization header:

{
  "url": "https://mcp.collimate.ai",
  "transport": "http",
  "headers": { "Authorization": "Bearer col_pro_a1b2c3d4e5f60718_..." }
}

Keep the key out of shared config

The header carries your key. Prefer an environment variable ($COLLIMATE_API_KEY) and a per-user config file; never commit a config with a literal key. Revoke and rotate from the console if one leaks.

The tools

Tool	What it does
sandbox_create(template, label?)	Fork a fresh sandbox from a template.
sandbox_exec(sandbox_id, command, timeout_s?)	Run a command in a sandbox; returns captured output (capped).
sandbox_write_file(sandbox_id, path, content)	Write a file into the guest.
sandbox_fork(sandbox_id, count, labels?)	Live-fork a running sandbox into count children.
sandbox_suspend(sandbox_id)	Suspend to disk — stops the meter.
sandbox_resume(sandbox_id)	Resume a suspended sandbox.
sandbox_list()	List your live sandboxes.
sandbox_delete(sandbox_id)	Destroy a sandbox.
health()	Endpoint liveness.

Fork count and exec timeout are bounded server-side, sandbox ids are opaque, and exec output is capped before it returns to the model — so a tool call can't run away with your quota or flood the context window.

Next steps

• Live fork — why sandbox_fork is the interesting one.
• Skills for coding agents — a drop-in skill file that teaches an agent this workflow.
• Sandboxes quickstart — the same operations over REST.