MCP tools
The two MCP servers ALE exposes over the sandbox, tool by tool. Both are thin wrappers over the cua computer-server: vm_mcp_server is the CLI / system surface, cua_mcp_server is the GUI / desktop surface. An out-of-sandbox agent drives the machine through both; an in-sandbox agent has a native shell and takes only the GUI one. (See Agents & executor for how they're consumed.)
vm_mcp_server: CLI & system
One-shot shell, file I/O, clipboard, and persistent PTY sessions. A thin set of primitives: agents build their own higher-level tools on top.
| Tool | Parameters | Returns |
|---|---|---|
run_command | command; timeout? (s) | {exit_code, stdout, stderr} (text + structured). Blocking; no shell state persists between calls. |
read_text | path | The file's full UTF-8 contents. |
write_text | path, content | "Wrote N bytes to {path}" (overwrites). |
read_bytes | path; offset?=0, length? | Base64 of the bytes (range-readable). |
write_bytes | path, content_b64; append?=false | "Wrote bytes to {path}". |
read_clipboard | (none) | The clipboard's text. |
write_clipboard | text | "Set clipboard (N bytes)". |
pty_start | command? (default bash), cwd?, env?, cols?=80, rows?=24 | "pid: N …", opens a persistent PTY that buffers output. |
pty_input | pid, data (incl. \n, ctrl chars) | "Sent N bytes to pid {pid}". |
pty_read | pid; timeout_ms?=2000 | Buffered raw output since last read, tagged [running] or [exited, code N]. |
pty_resize | pid, cols, rows | "Resized pid {pid} to {cols}x{rows}". |
pty_kill | pid | "Killed pid {pid}". |
cua_mcp_server: GUI & desktop
Mouse, keyboard, scroll, and screen capture. Coordinates are
normalized to [0, 1000] on both axes (the
server scales to real pixels). Every action returns a one-line confirmation:
take a screenshot to observe the result.
| Tool | Parameters | Returns |
|---|---|---|
key | keys[] (e.g. ["ctrl","c"]) | "Pressed: ctrl+c", press & release. |
key_down | keys[] | "Key down: …", hold (pair with key_up). |
key_up | keys[] | "Key up: …". |
hold_key | keys[], duration (s) | "Held … for Ns". |
type | text | "Typed: \"…\"", into the focused field. |
mouse_move | coordinate [x,y] | "Moved cursor to [x, y]". |
click | coordinate?; button?=left, clicks?=1 (1–3) | "Clicked (left, 1x) at [x, y]". |
drag | coordinate (end); start_coordinate?, button?=left | "Dragged (left) from … to [x, y]". |
mouse_down | button?=left | "Mouse down: left". |
mouse_up | button?=left | "Mouse up: left". |
scroll | direction, amount; coordinate? | "Scrolled down 3 at [x, y]". |
wait | duration (s) | "Waited Ns". |
screenshot | save_path? | Text + an image content block (PNG base64); optionally also saved to save_path on the VM. |
cursor_position | (none) | "Cursor at [x, y]" (normalized). |
get_screen_size | (none) | {width, height} in real pixels (text + structured). |