MCP tools

Every tool the cua MCP server exposes, with its permission and parameters.

cua mcp (and cua daemon mcp, the same server backed by the cua daemon) serves these tools over stdio. See MCP server for client setup.

Contract version 0.9.0; MCP protocol revision 2025-06-18.

Spaces tools#

The Spaces contract: register, claim and release Spaces, run commands, move files, stream, run agents and teleport.

These tools are the Spaces contract, with the same names and schemas on every surface. Each links to its entry there (parameters, result, errors, providers, metering); cua mcp gates each one behind the permission spaces:<tool>.

Space lifecycle#

Full entries: Space lifecycle.

Tool	Description
`add_space`	Add an existing computer as a Space by address and token.
`remove_space`	Forget a registered Space without touching it.
`list_spaces`	List the Spaces this connection can see.
`create_space`	Create a Space: a new sandbox on this computer, on one of your computers, or in the cloud.
`network_show`	Show a Space's network: preset, what it opens, where it is enforced, what is always blocked.
`network_log`	List what a Space tried to reach and its network blocked.
`network_set`	Tighten a Space's network: internet, none or custom lists.
`delete_space`	Delete a Space's sandbox and forget it.
`stop_space`	Turn a Space off: stop it (disk kept, memory freed) or, with suspend, suspend it (memory kept).
`resize_space`	Change a Space's vCPUs, memory or disk size.
`start_space`	Turn a Space back on: resume or boot it.

Commands and files#

Full entries: Commands and files.

Tool	Description
`space_bash`	Run a shell command inside the Space.
`space_job`	Run a long command in the Space as a background job: tail its log, cancel it, or get woken when it ends.
`space_write`	Write literal text to a path inside the Space.
`upload`	Send a local file or folder into the Space.
`send_file`	Send a host file or folder into the Space's Downloads, verified by sha256 on arrival.
`download`	Fetch a file or folder out of the Space.

Streams and display#

Full entries: Streams and display.

Tool	Description
`stream_endpoint`	Return a ticketed media endpoint for the Space's desktop or one window.
`list_space_windows`	List the windows open inside the Space.
`stream_space_window`	Show one Space window in another Space's Stream section (into=<your Space>; default the parent of space) or on the operator's desktop (into=desktop).
`show_space_pip`	Pin the Space as picture-in-picture on the operator's desktop.
`hide_space_pip`	Unpin the picture-in-picture window.
`open_space_viewer`	Open the full Space viewer on the operator's desktop.

Services#

Full entries: Services.

Tool	Description
`list_tools`	List the MCP services and tools reachable inside the Space.
`call_tool`	Call a service tool inside the Space.
`space_service`	Keep a command running in the Space: restarts, health checks, start on boot, logs.

Agents#

Full entries: Agents.

Tool	Description
`agent_start`	Start a coding agent in the Space.
`agent_message`	Send a follow-up to an agent run.
`agent_events`	Read an agent run's events after a cursor.
`agent_status`	Read an agent run's status and result.
`agent_interrupt`	Interrupt an agent run's current turn.
`agent_stop`	Stop an agent run.
`agent_list`	List agent runs in the Space.
`agent_capabilities`	Report what the agent harnesses support.

Persistent agents#

Full entries: Persistent agents.

Tool	Description
`agent_add`	Create a named agent whose memory outlives its Space.
`persistent_agent_list`	List persistent agents.
`agent_remove`	Forget a persistent agent.
`agent_send`	Give a persistent agent a turn.
`persistent_agent_save`	Save a persistent agent's home now.
`agent_pause`	Pause a persistent agent: its run, its routines and its Space.
`agent_resume`	Resume a paused persistent agent.
`agent_schedule_add`	Schedule a recurring turn for a persistent agent.
`agent_schedule_list`	List routines.
`agent_schedule_remove`	Delete a routine.
`agent_schedule_set_enabled`	Turn a routine on or off.
`notify_user`	Tell the user something in the Cua app.
`notifications_list`	Read the notifications feed.
`notifications_ack`	Mark notifications read.
`computer_access_grant`	Let a persistent agent use one of the user's computers.
`computer_access_revoke`	Take back a persistent agent's access to a computer.
`computer_access_list`	List per-agent computer access.

Space thread and members#

Full entries: Space thread and members.

Tool	Description
`thread_read`	Read a Space's thread.
`thread_post`	Post to a Space's thread.
`thread_inbox`	List an agent member's open tasks.
`thread_claim`	Claim a task.
`thread_reply`	Reply to a task and update it.
`thread_import`	Import an app's earlier conversation into a Space's thread.
`agent_members`	List a Space's agent members.
`agent_set_rights`	Choose who can task, stop and approve an agent.
`thread_join`	Set your name and icon in a Space's thread.
`thread_join_code_create`	Make a one-time code an agent joins the Space with.
`thread_join_code_list`	List a Space's join codes.
`thread_join_code_cancel`	Cancel an unused join code.
`thread_join_redeem`	Redeem a join code on this computer.
`thread_settings`	Read or change a Space's thread settings.
`thread_device_revoke`	Remove the agents connected from a computer.

Session teleport#

Full entries: Session teleport.

Tool	Description
`teleport_manifest`	Describe what a session teleport would move.
`teleport_app`	Move an app session into the Space.

Keyvault#

Full entries: Keyvault.

Tool	Description
`request_site_login`	Sign in to a site in the Space with the user's saved password.

Hotspot#

Full entries: Hotspot.

Tool	Description
`hotspot_start`	Start sharing this computer's network with a Space.
`hotspot_stop`	Stop sharing this computer's network.
`hotspot_status`	Report which Spaces are sharing this computer's network, with counters.

Cua Volume#

Full entries: Cua Volume.

Tool	Description
`volume_ls`	List a folder of the Cua Volume.
`volume_read`	Read a file from the Cua Volume.
`volume_write`	Write a file to the Cua Volume.
`volume_delete`	Delete a file from the Cua Volume.
`volume_history`	List a Cua Volume file's versions.
`volume_restore`	Restore an old version of a Cua Volume file.
`volume_grant`	Grant an agent or Space more Cua Volume access.
`volume_revoke`	Revoke a Cua Volume grant.
`volume_grants`	List Cua Volume grants.
`volume_request_access`	Ask the user for more Cua Volume access.
`volume_requests`	List Cua Volume access requests waiting for the user.
`volume_approve`	Approve a Cua Volume access request.
`volume_deny`	Decline a Cua Volume access request.
`volume_audit`	Read the Cua Volume audit log.
`volume_storage`	Show where the Cua Volume keeps its bytes.
`volume_storage_set`	Test or change where the Cua Volume keeps its bytes.
`volume_mount_status`	Show whether the Cua Volume is mounted as a volume.
`volume_mount`	Mount the Cua Volume as a volume.
`volume_unmount`	Unmount the Cua Volume volume.
`volume_sync_status`	Show the Cua Volume's sync state across devices.
`volume_sync_events`	Wait for Cua Volume sync events.
`volume_sync_resolve`	Mark a Cua Volume sync conflict as seen.
`volume_cache_stats`	Show the Cua Volume block cache.
`volume_cache_set`	Set the Cua Volume block cache's size cap.
`volume_cache_clear`	Clear the Cua Volume block cache.

Full entries: Sharing.

Tool	Description
`share_space`	Let someone in your team watch or edit a Space.
`unshare_space`	Stop sharing a Space with an account, or with everyone.
`space_shares`	List who a Space is shared with.
`relay_register_space`	Publish a Space on the relay for the account's other devices.
`relay_unregister_space`	Take a Space off the relay.

Your cloud#

Full entries: Your cloud.

Tool	Description
`cloud_status`	List your clouds (AWS, Google Cloud, Hetzner, Modal): found credentials, the connected account and region, what each can run at what hourly cost, and what Cua created there.
`cloud_connect`	Connect a cloud account Spaces can be created in.
`cloud_test`	Check a cloud account without creating anything.
`cloud_disconnect`	Forget a connected cloud account (deleting what Cua created there first, with delete=true).
`cloud_sweep`	Find and delete what Cua left in your clouds.
`cloud_plan`	Show (or apply) the elastic pool's plan for some Spaces: where they go, which machines it adds, and the cost.
`cloud_hosts`	List the hosts the elastic pool added in your clouds.
`cloud_add_host`	Add hosts to your pool in a linked cloud.
`cloud_remove_host`	Remove hosts this home added to your pool.
`cloud_budget`	Read or set the elastic pool's budget and autoscale switch.
`cloud_reconcile`	Run the elastic pool's scale-in pass now.
`prewarm`	Keep Spaces of one shape ready where the elastic pool puts them, so the next creates start in a fraction of a second.
`prewarm_list`	List the prewarms and how many Spaces each keeps ready.
`prewarm_remove`	End a prewarm: its ready Spaces go.
`cloud_audit`	Read the log of what Cua did in your clouds.
`cloud_cost`	Estimate what Cua's machines in your clouds cost, by Space, agent, day or cloud.

Image tools#

`images_list`#

List the sandbox image catalog (the images the docs list): ref, OS, container or VM, local runtime, whether it ships cua-spacesd and which browsers, its other variants, and the command that creates it. browser_tools=true means the in-sandbox cua-driver browser tools can drive its browser. Call this first to choose an image.

Permission: images:list.

Parameter	Type	Description
`all`	`boolean`	Include unpublished entries (benchmark images).
`browser`	`boolean`	Only images whose browser the cua-driver browser tools drive.
`os`	`string`	Only this OS: linux, windows or macos.

Sandbox tools#

`sandbox_list`#

List sandboxes: local and direct ones by default, each row with location (local or direct). Pass location to list only one kind. When the user is signed in and has other machines, a note after the rows names them and the route to use: a machine's own desktop is the Space relay:<id> (computer tools and space_bash take it as space), and new Spaces go to one with create_space on="host:<name>".

Permission: sandbox:list.

Parameter	Type	Default	Description
`location`	`"local" \| "direct"`		Only sandboxes in this location: local or direct (default: all).

`sandbox_create`#

Create a sandbox from any image. on says where (local, the default unless the user configured another with cua config set default.on), kind what (auto, container, vm, microvm) and runtime which engine (auto, or gvisor, runc, qemu, lume, firecracker, vz, containerization); an impossible combination fails and lists the valid values. To browse the web, pass browser=true (and optionally url): it starts the canonical Linux image, registers it as a Space, launches Chromium with a throwaway profile inside it and returns the space, session, target_id and tab_id to pass to call_tool with the in-sandbox browser tools (browser_navigate, get_browser_state, browser_click, browser_type). Pass command, env and services to run a server in it, for example an MCP server: services {"mcp": 8765}. Without browser=true it does not register a Space: to reach its MCP server with list_tools/call_tool (service="mcp"), use create_space instead (same arguments), or add this one with add_space (address local:<name>).

Permission: sandbox:create.

Parameter	Type	Description
`browser`	`boolean`	Start a browser in it, ready for the cua-driver browser tools (default image: the canonical Linux image).
`command`	`string[]`	Entrypoint override (argv), for example ["python", "-m", "my_mcp"].
`env`	`object`	Environment variables (string values).
`image`	`string`	Image reference, any registry (overrides os_type).
`kind`	`"auto" \| "container" \| "vm" \| "microvm"`	What kind of computer: auto (default; from the image), container, vm or microvm.
`name`	`string`	Sandbox name.
`on`	`string`	Where it runs: local (default: the user's default location, else local).
`os_type`	`string`	linux (default) or macos.
`pool`	`string`	Create from this pool (sandbox_pool_create): takes one of its ready sandboxes in about 0.1 s (on this computer).
`runtime`	`string`	Which engine: auto (default) or one the location offers for the kind (gvisor, runc, qemu, lume, firecracker).
`services`	`object`	Named services: name to guest port, for example {"mcp": 8765}; each is probed for readiness.
`url`	`string`	With browser=true: open this URL first.

`sandbox_pool_list`#

List the pools: sandboxes of one image kept ready on this machine (min always, up to max while creates come fast), each with how many are ready and why.

Permission: sandbox:list.

No parameters.

`sandbox_pool_create`#

Create a pool (or update the pool of that name): sandboxes of one image kept ready on this machine, min at all times (refilled right after each create from it) and up to max while creates come faster than sandboxes start. sandbox_create with pool=<name> then takes one in about 0.1 s. Use it before creating many sandboxes of one kind (an agent loop, a batch); without pools, ready sandboxes are kept only where repeated creates pay for it.

Permission: sandbox:pools.

Parameter	Type	Default	Description
`cpus`	`integer`		vCPUs of each sandbox.
`env`	`object`		Environment variables (string values).
`idle_seconds`	`integer`		After this long without a create from the pool it keeps none ready until the next one (default: never).
`image`	`string`	required	Image its sandboxes run (for example linux).
`kind`	`string`		auto (default), container, vm or microvm.
`max`	`integer`		Most kept ready, not counting those created from the pool (default: min).
`memory_mb`	`integer`		Memory (MiB) of each sandbox.
`min`	`integer`		Sandboxes kept ready at all times (default 1).
`name`	`string`		Pool name (lower-case letters, digits, '-'; default: a new one).
`runtime`	`string`		auto (default) or an engine (gvisor, runc, qemu, ...).

Example arguments

{"image":"<image>"}

`sandbox_pool_delete`#

Delete a pool. Its ready sandboxes go; sandboxes created from it stay.

Permission: sandbox:pools.

Parameter	Type	Default	Description
`name`	`string`	required	Pool name.

Example arguments

{"name":"<name>"}

`sandbox_get`#

Get details for a sandbox.

Permission: sandbox:get.

Parameter	Type	Default	Description
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.

Example arguments

{"name":"<name>"}

`sandbox_start`#

Start (resume) a sandbox.

Permission: sandbox:start.

Parameter	Type	Default	Description
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.

Example arguments

{"name":"<name>"}

`sandbox_stop`#

Stop (suspend) a sandbox.

Permission: sandbox:stop.

Parameter	Type	Default	Description
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.

Example arguments

{"name":"<name>"}

`sandbox_restart`#

Restart a sandbox.

Permission: sandbox:restart.

Parameter	Type	Default	Description
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.

Example arguments

{"name":"<name>"}

`sandbox_suspend`#

Suspend a sandbox.

Permission: sandbox:suspend.

Parameter	Type	Default	Description
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.

Example arguments

{"name":"<name>"}

`sandbox_delete`#

Delete a sandbox.

Permission: sandbox:delete.

Parameter	Type	Default	Description
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.

Example arguments

{"name":"<name>"}

`sandbox_view`#

Get a browser link to the sandbox desktop in the cua-spacesd HTML5 viewer (video, audio, input, clipboard, files). The link expires after an hour.

Permission: sandbox:view.

Parameter	Type	Default	Description
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.

Example arguments

{"name":"<name>"}

`sandbox_vnc`#

Deprecated: use sandbox_view. Returns the same viewer link.

Permission: sandbox:view.

Parameter	Type	Default	Description
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.

Example arguments

{"name":"<name>"}

`sandbox_open_browser`#

Launch Chromium with a fresh throwaway profile inside an existing sandbox (an image with cua-spacesd and Chromium, see images_list), bind it and optionally open a URL. Returns the space, session, target_id and tab_id for call_tool with the in-sandbox browser tools. sandbox_create with browser=true already does this.

Permission: sandbox:browser.

Parameter	Type	Default	Description
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.
`session`	`string`		cua-driver session label to use on every later browser call (default: browse).
`url`	`string`		Open this URL first.

Example arguments

{"name":"<name>"}

Teleport tools#

`teleport_browser_session`#

Teleport the user's signed-in session for specific sites (for example github.com) from their Firefox or Chrome into a sandbox, through the Cua Keyvault. Name each site: nothing is selected by default and there is no all-sessions option. The first call moves nothing: it files a Keyvault request and returns consent_required, a summary and a request_id. Show the summary to the user; they approve it in Cua (Touch ID or password). Then call again with the request_id to move exactly those sites. Use it only when the user asks to browse as themselves.

Permission: teleport:browser.

Parameter	Type	Default	Description
`browser`	`"firefox" \| "chrome"`	required	firefox or chrome (chromium, brave and edge profiles use chrome).
`duration_minutes`	`integer`		How long the sandbox may keep them (default 15, at most 1440).
`name`	`string`	required	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations.
`reason`	`string`		Why, in a few words; shown to the user as unverified.
`request_id`	`string`		The request_id from the first call, after the user approved it in Cua.
`sites`	`string[]`	required	The exact sites to teleport, for example ["github.com"].

Example arguments

{"name":"<name>","browser":"firefox","sites":["<site>"]}

Computer tools#

Computer tools act on a sandbox desktop through its cua-spacesd. Coordinates are in the pixel space of the last computer_screenshot of that sandbox.

`computer_screenshot`#

Take a screenshot (long edge at most 1200 px). Later coordinates are in its pixel space.

Permission: computer:screenshot.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

`computer_click`#

Click at screenshot coordinates.

Permission: computer:click.

Parameter	Type	Default	Description
`button`	`string`		left (default), right or middle.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_double_click`#

Double-click at screenshot coordinates.

Permission: computer:click.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_move_cursor`#

Move the cursor.

Permission: computer:click.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_mouse_down`#

Press a mouse button.

Permission: computer:click.

Parameter	Type	Default	Description
`button`	`string`		left, right or middle.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_mouse_up`#

Release a mouse button.

Permission: computer:click.

Parameter	Type	Default	Description
`button`	`string`		left, right or middle.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`x`	`integer`	required	X in screenshot pixels.
`y`	`integer`	required	Y in screenshot pixels.

Example arguments

{"x":100,"y":200}

`computer_type`#

Type text.

Permission: computer:type.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`text`	`string`	required	Text.

Example arguments

{"text":"<text>"}

`computer_key`#

Press a key (enter, escape, tab, a, ...).

Permission: computer:key.

Parameter	Type	Default	Description
`key`	`string`	required	Key.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"key":"<key>"}

`computer_key_down`#

Hold a key.

Permission: computer:key.

Parameter	Type	Default	Description
`key`	`string`	required	Key.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"key":"<key>"}

`computer_key_up`#

Release a key.

Permission: computer:key.

Parameter	Type	Default	Description
`key`	`string`	required	Key.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"key":"<key>"}

`computer_hotkey`#

Press a shortcut such as ctrl+c or cmd+shift+s.

Permission: computer:hotkey.

Parameter	Type	Default	Description
`keys`	`string`	required	Keys joined by +.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"keys":"<keys>"}

`computer_scroll`#

Scroll up, down, left or right.

Permission: computer:scroll.

Parameter	Type	Description
`amount`	`integer`	Lines (default 3).
`direction`	`string`	down (default), up, left, right.
`sandbox`	`string`	Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

`computer_drag`#

Drag between two points.

Permission: computer:drag.

Parameter	Type	Default	Description
`end_x`	`integer`	required	End X.
`end_y`	`integer`	required	End Y.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`start_x`	`integer`	required	Start X.
`start_y`	`integer`	required	Start Y.

Example arguments

{"start_x":100,"start_y":200,"end_x":100,"end_y":200}

`computer_clipboard_get`#

Read clipboard text.

Permission: computer:clipboard.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

`computer_clipboard_set`#

Set clipboard text.

Permission: computer:clipboard.

Parameter	Type	Default	Description
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).
`text`	`string`	required	Text.

Example arguments

{"text":"<text>"}

`computer_file_read`#

Read a text file.

Permission: computer:file.

Parameter	Type	Default	Description
`path`	`string`	required	Path.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"path":"<path>"}

`computer_file_write`#

Write a text file (the Spaces space_write implementation, on this sandbox).

Permission: computer:file.

Parameter	Type	Default	Description
`content`	`string`	required	Content.
`path`	`string`	required	Path.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"path":"<path>","content":"<content>"}

`computer_file_list`#

List a directory.

Permission: computer:file.

Parameter	Type	Default	Description
`path`	`string`		Path (default .).
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

`computer_shell`#

Run a shell command (sh -c, 120 s timeout; the Spaces space_bash implementation, on this sandbox).

Permission: computer:shell.

Parameter	Type	Default	Description
`command`	`string`	required	Command line.
`sandbox`	`string`		Sandbox ref (local:<name>, direct:<host:port>) or a name unique across locations (default: --sandbox / CUA_SANDBOX).

Example arguments

{"command":"<command>"}