MCP

Burrowbox speaks the Model Context Protocol over Streamable HTTP. There are two kinds of endpoint.

#Platform MCP

POST /mcp with your API key. Lets an agent manage machines itself.

Tool	What it does
`machines_list`	Your machines, with status, expiry and MCP URL; filter by `external_id` and `labels`
`machine_create`	Create and boot a machine (`name`, `size`, `screen`, `ttl_minutes`, `on_expire`, `external_id`, `labels`)
`machine_get`	Details, including `mcpUrl` and `mcpToken`
`machine_start` / `machine_stop`	Turn a machine on or off; state is kept
`machine_set_ttl`	Change how long it stays on (`null` = always on)
`vpn_locations`, `machine_set_vpn`, `machine_vpn_status`	VPN locations: browse from a residential IP in a chosen country
`machine_resize`	Change the size (`tiny`…`large`) without recreating; a running machine restarts once (~20 s)
`machine_update`	Update the machine's agent to the latest release (live when possible) — see Updates
`machine_set_browser`	Switch the browser: `light` (fast, no WebGL) or `full` (Chromium with WebGL) — see Browser mode
`machine_set_tags`	Set `external_id` (your customer's id) and `labels`
`pools_list`, `pool_create`, `pool_update`, `pool_delete`, `pool_claim`	Warm pools: keep machines booted and hand one to a customer instantly
`usage_by_customer`	Spend per `external_id` or per machine (Billing)
`event_webhooks_list`, `event_webhook_create`, `event_webhook_test`, `event_webhook_delete`	Event webhooks: get notified when machines change state
`machine_destroy`	Delete a machine permanently (its disk, vault, snapshots, schedules and webhooks)
`machine_schedule_`, `machine_webhook_`, `machine_job_runs`	Scheduled jobs and webhooks; see Scheduled jobs & webhooks
`machine_live_view`	A link to watch or take over the machine, ready for an `<iframe>` (Embed the live view)
`machine_call_tool`	Call any machine tool without a second connection
`account_balance`	Balance, burn rate and runway

claude mcp add --transport http burrowbox https://burrowbox.dev/mcp \
  --header "Authorization: Bearer $BURROWBOX_KEY"

#Machine MCP

POST /api/machines/{id}/mcp with the machine's mcpToken (or your API key). This is what an agent uses to operate the computer.

#Browser

The machine's persistent browser. Cookies, local storage and tabs survive restarts, and you can watch it live.

Tool	Arguments
`browser_navigate`	`url`
`browser_snapshot`	`max_chars` — URL, title, text and interactive elements tagged `[ref]`
`browser_click`	`target` — a ref from the snapshot, or a CSS selector
`browser_fill`	`target`, `value`, `submit`
`browser_type` / `browser_press_key`	`text` / `key`
`browser_evaluate`	`expression`
`browser_screenshot`	—
`browser_tabs`	`action`: `list`, `new`, `switch`, `close`
`browser_login`	`credential` (optional; matched by URL) — fills and submits a login form from the vault
`human_solve_captcha`	`kind`, `sitekey`, `url`, `timeoutSeconds`, `tokenOnly` — solves the verification challenge on the current page (Cloudflare verification pages, Turnstile, reCAPTCHA v2, hCaptcha). Billed per use

#Desktop

Tool	Arguments
`screenshot`, `desktop_screenshot`	Capture the screen
`get_app_state`	Accessibility tree + screenshot of one app
`list_windows`, `focused_window`, `activate_window`	Window management
`click`, `drag`, `scroll`, `type_text`, `press_key`	Input, by element index, selector or coordinates
`perform_action`, `set_value`	Accessibility actions

#Apps, shell and files

Tool	Arguments
`apps_list`	`query`
`apps_install`	`kind`: `apt` (`packages`), `deb` (`url`), `appimage` (`url`, `name`), `flatpak` (`ref`), `script`
`apps_launch`	`app` or `command` — waits for the window
`shell_run`	`command`, `cwd`, `timeout_seconds`, `background`
`browser_capabilities`	The browser engine (`light`/`full`) and whether pages get WebGL/WebGL2
`network_info`	Public IP, country and network the machine browses from, and whether a VPN location is set
`file_read` / `file_write`	`path` / `path`, `content`

#Vault

Tool	Arguments
`vault_list`	Names, URLs and usernames — never secrets
`vault_set`	`name`, `url`, `username`, `password`, `totp_secret`
`vault_type_secret`	`name`, `field` (`username`/`password`/`totp`) — types into the focused app
`vault_delete`	`name`

#Automations

Added by the platform, scoped to this machine: schedule_create, schedule_list, schedule_update, schedule_delete, schedule_run, webhook_create, webhook_list, webhook_rotate, webhook_delete, job_runs. An agent can schedule its own work ("check this dashboard every morning at 9") or give another system a URL that triggers it. See Scheduled jobs & webhooks.

#Session

Tool
`session_save`	Record open windows and tabs now (also happens every 20 s)
`machine_info`	What's running and how the tools fit together