Desktop MCP server setup and tools

Connect an agent

The installer already ran this for you. Run it again after installing a new agent, or pass client names to pick which ones to register:

$ agentpc mcp-install
$ agentpc mcp-install claude claude-desktop codex cursor gemini vscode

Supported: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI and VS Code. Restart Claude Desktop after registering. For Codex it also raises the MCP timeouts so slow builds and boots don't trip them. agentpc mcp-uninstall removes the registration again.

Claude plugin

In Claude Code, the plugin bundles the MCP server with a skill that teaches Claude when and how to use the VMs. It runs the installed agentpc binary, so install that first.

/plugin marketplace add pawanpaudel93/agentpc
/plugin install agentpc@agentpc

Client configs

For any other MCP client, add the server by hand. The standard shape:

{
  "mcpServers": {
    "agentpc": { "command": "agentpc", "args": ["mcp"] }
  }
}

Codex

A first create_vm can take minutes while the image downloads, so the server needs longer timeouts than Codex's defaults. agentpc mcp-install codex adds these for you:

[mcp_servers.agentpc]
command = "agentpc"
args = ["mcp"]
startup_timeout_sec = 60
tool_timeout_sec = 900

VS Code

{
  "servers": {
    "agentpc": { "type": "stdio", "command": "agentpc", "args": ["mcp"] }
  }
}

The agentpc repository ships these as project configs (.mcp.json, .codex/config.toml, .cursor/mcp.json, .gemini/settings.json, .vscode/mcp.json), so an agent opened in a clone picks the server up automatically.

Tools

VMs

Checkpoints

Shell, files and ports

Screen and desktop

Desktop control

All three guests (Windows, Ubuntu, Arch) run cua-driver and are 1280×800. Work in a loop: look (take_screenshot or a snapshot tool, through inspect_desktop when you only need to look), act (use_desktop_tool), then look again to verify. Prefer run_command for anything a shell can do.

Open Notepad on Windows and type into it, as three use_desktop_tool calls. The pid and window_id come from launch_app; the snapshot_id and element_index from get_window_state:

{ "name": "windows-1", "tool": "launch_app", "arguments": { "name": "notepad" } }
{ "name": "windows-1", "tool": "get_window_state", "arguments": { "pid": 4120, "window_id": 65812 } }
{ "name": "windows-1", "tool": "type_text", "arguments": {
    "pid": 4120, "window_id": 65812, "snapshot_id": "s1a2b3c4d",
    "element_index": 7, "text": "Hello from the agent" } }

If a reply starts with a reconnect note (the VM or its driver restarted), earlier snapshot ids and browser sessions are gone: take a new snapshot and run browser_prepare again.

Guest tips

All guests are ARM64. On Windows, x64/x86 apps run through Prism (~2–4× slower; no x64 drivers). For x86_64 and i386 Linux programs, create ubuntu or arch with version: "x86apps": they run through FEX, about 2× slower (Node 6–7×). Go programs work; amd64 containers run with docker run --platform linux/amd64 (install Docker first: sudo apt install docker.io on Ubuntu, sudo pacman -Syu --noconfirm docker && sudo systemctl start docker on Arch); x86 Electron/Chromium apps need --no-sandbox. On Ubuntu, a missing x86 library installs with sudo apt install libfoo:amd64 and an x86 app's .deb with sudo apt install ./app_amd64.deb; on Arch (no multiarch) x86 programs use the image's x86 Arch Linux tree, and sudo fex-pacman -Sy --noconfirm --needed <pkg> installs more x86 packages into it. x86 systemd services run too, hardened ones included (a unit that runs its x86 program through a script needs sudo fex-unit <unit>). list_vms shows x86_tso: hardware (needs macOS 15+) or emulated.

Typical session

Test an install script on a clean machine, keeping a checkpoint to retry from:

create_vm        { "os": "ubuntu", "name": "install-test" }
upload_file      { "name": "install-test", "host_path": "./install.sh", "guest_path": "/tmp/" }
checkpoint_vm    { "name": "install-test", "label": "before-install" }
run_command      { "name": "install-test", "command": "bash /tmp/install.sh" }
take_screenshot  { "name": "install-test" }
restore_vm       { "name": "install-test", "label": "before-install" }  # retry from the same state
delete_vm        { "name": "install-test" }

Some prompts to try:

• "Create an Ubuntu VM, open a terminal and run uname -a."
• "Reset ubuntu-1 and check that my install script works on a clean machine."
• "Open Notepad on windows-1, type a short note and show me a screenshot."

Long jobs and servers

A foreground run_command ends when the command returns, and is given an attempted stop at its timeout. Start builds, servers and GUI apps with background: true, then poll:

run_command     { "name": "ubuntu-1", "command": "npm run dev", "background": true }  # → job id 1
get_job_status  { "name": "ubuntu-1", "id": 1, "tail_lines": 40 }
stop_job        { "name": "ubuntu-1", "id": 1 }  # when done: the server and its children
forward_port    { "name": "ubuntu-1", "guest_port": 3000 }  # → 127.0.0.1:<port> on the Mac

get_job_status without wait_seconds or cursor answers at once, as it always has. To follow a job without polling in a loop, wait and read from a cursor:

get_job_status  { "name": "ubuntu-1", "id": 1, "cursor": "start", "wait_seconds": 10 }  # → output, next_cursor
get_job_status  { "name": "ubuntu-1", "id": 1, "cursor": "<next_cursor>", "wait_seconds": 30 }  # new output only

Reboots (some installers) drop SSH. Call start_vm on the same VM, which waits until the desktop is ready again even if it's already running, then rerun the command. If its reply was connection_lost with effect_unknown: true, check what it did first with get_job_status and its job_id.

Results and recovery

run_command, get_job_status, list_jobs and wait_for_service declare an outputSchema and return matching structuredContent (schema_version 1) next to the readable text scripts have always parsed (exit code: N, STATE: …). The text is a single block, not a JSON copy, so a client that joins text blocks sees no extra output. Read the typed fields and isError.

run_command

isError is true for every nonzero exit, every timeout (even when the command's own exit code is known to be 0), every cancelled request, and every run that didn't start or lost its connection. It is false only for exit 0 and a background start. Commands are never retried automatically.

Timeouts

• At timeout, agentpc attempts to stop the command and what it started, and keeps the partial stdout and stderr. The reply usually follows within a few seconds; the cleanup is bounded, about 50 seconds beyond the timeout at most.
• termination_confirmed: true means agentpc verified that none of the processes it identified is left. On Linux those are the command's transient systemd user scope when the guest's user manager is available, the processes marked with its execution id and their descendants (all that is checked without a user manager, where a process that clears its environment and detaches can be missed), and its verified root. On Windows it is the verified process tree, best effort: a process whose launcher had already exited can be missed. It is not a sandbox guarantee. System services, other systemd units, and Windows services, scheduled tasks and WMI-created processes are not covered.
• With termination_confirmed: false, or connection_lost with effect_unknown: true, the command may still be running. (A connection_lost with effect_unknown: false carries the VM's recorded exit_code and no job_id: it finished, and only its output may be incomplete.) Use the job_id with get_job_status and stop_job, and don't rerun it before you know. A process is only signalled after its pid and start time are proven to be the command's.
• A command whose exit code the VM recorded but whose run had not ended by the timeout (a child it left may have held its output, or it ended right at the deadline) returns that exit code with timed_out: true, after cleanup verified that none of the processes agentpc identified remains. Start servers with background: true.
• A Linux foreground command is limited to 92 KiB (94,208 UTF-8 bytes) of text. agentpc checks that before sending anything: a bigger one comes back not_started with no recovery_action. For a bigger script, upload_file it and run the file.

Cancellation

• A foreground run_command is stopped in the VM, as at a timeout (bounded, identity-checked, never retried), when its request is cancelled (notifications/cancelled), the client disconnects or the MCP session ends; request_cancelled is then true and the call is an error.
• cancelled with termination_confirmed: true: stopped and verified. exited with its code: it had already finished. not_started with no recovery_action: it never began. cancelled with termination_confirmed: false, effect_unknown: true and recovery_action: stop_job: it may still be running; use the job_id and don't rerun it before you know.
• A client that cancelled usually never receives that reply. Find the run with list_jobs; get_job_status then shows stopped with stop_reason: request_cancelled, or not_started.
• A background: true start is detached on purpose: cancelling its request, disconnecting or ending the session does not stop the job. End it with stop_job. AGENTPC_KEEP_RUNNING=1 keeps VMs, not foreground commands, and a hard kill of the MCP server cleans up nothing: the job records stay in the VM.

get_job_status

• state: queued, running, exited, stopped, ended, not_started, missing or unknown (the VM couldn't be read: an error, never reported as ended). An exited job reports its own exit code even if it left a child running.
• wait_seconds (0 to 30, default 0) waits for the job to leave running, or with a cursor for new output. If nothing happens it returns the current state with wait_timed_out: true. A wait only waits and never stops the job. It can run about 2 seconds past the wait on a slow VM; to wait longer, call again with the last next_cursor.
• cursor (a next_cursor, or "start") returns at most 16 KiB from that byte position and advances by exactly the bytes it returned, so output is neither repeated nor skipped (has_more says call again). UTF-8 characters are never split across reads, invalid bytes become U+FFFD (invalid_utf8), and a byte-order mark is consumed unseen.
• A cursor that no longer matches (VM reset or restored, guest reboot, log replaced, shortened, rewritten or removed) comes back with cursor_reset: true and a cursor_reset_reason, restarted at the log's beginning: discard what you assumed. Detection is best effort; it can miss a guest clock step, a Windows log recreated within the file system's tunneling window, and a log rewritten with the same first 64 bytes.
• missing means nothing has recorded itself under that id yet. That doesn't prove the command never started, so don't blindly retry it.
• A foreground job_id has status only (exited with its code, stopped at its timeout, or not started); its output went to the run_command reply, so there is no log to replay.

list_jobs

• Read-only, metadata only: per job job_id, kind, state, exit_code, stop_reason (timeout, stop_job, request_cancelled), log_available, records, recorded_at and finished_at. Never a command, environment, output, log text or path. Newest id first; limit is 1 to 100 (default 20).
• When has_more is true, pass next_cursor as cursor: the next page continues below the last job shown within the VM as the first page saw it, so jobs created meanwhile don't shift it.
• A cursor from before a VM reset, restore or recreation is cursor_stale: the VM's generation changed, so its records may differ from what the earlier pages listed (a restored checkpoint can keep some) and the listing cannot safely continue. Call again without a cursor. A malformed cursor, or one of another VM, is invalid_cursor.
• Best effort, not an immutable history: records age out, and a huge job directory keeps only its first entries (scan_truncated), so jobs may be missing. A queued, missing or unknown entry is unresolved, not proof the command never started. Cancelling the call abandons only the listing.

wait_for_service

• Looks only at the VM's own IPv4 127.0.0.1 (never another host, a URL or a proxy). protocol: "tcp" (default) is ready when a connection is accepted; "http" is ready when one GET path (/ by default; a path, not a URL) answers expected_status (default 200). path and expected_status are HTTP-only and refused with tcp. Redirects are not followed, and no body, header or guest text is returned. Don't put credentials in path: it is echoed back and visible in the VM's process list.
• timeout_seconds is 1 to 120 (default 30) and bounds the waiting, not the wall clock: a call can run about 5 s past it while a last probe finishes.
• state is ready, timed_out, job_failed, cancelled or error, with the last tcp or http_outcome (status_matched, redirect, status_mismatched, no_response, malformed) and http_status. Anything but ready is an error and timed_out keeps the last observation. probe_unsupported means the guest's bash has no /dev/tcp or it has no timeout command.
• With job_id the wait ends early (job_failed) only for a proven failure: a nonzero exit, a stopped job, or one that never started. A job that exited 0 (a server may outlive its wrapper), is queued, running, ended without a code, missing or unreadable is not failure.
• Ready describes the endpoint, not a process: nothing checks who owns the port, so it doesn't prove the job started it. Waiting never stops or restarts the service or the job; cancelling it only stops probing. Each probe makes short-lived connections (and one GET), so it can consume a one-shot listener.

inspect_desktop

Before each dispatch, inspect_desktop asks the VM's driver for the tool's annotations and runs only a tool it explicitly marks readOnlyHint: true (list_desktop_tools shows [read-only]). A tool marked otherwise, unmarked or unknown is refused before it is dispatched, with nothing run (looking up the annotations does ask the VM's driver). After a dropped call the driver is asked again on the new connection; the call is re-sent only if the old connection had listed the tool read-only and the new one still does. The marking is the driver's own claim: a guard against mistakes, not a guarantee against a mislabelling driver or guest. For compact observation, get_window_state with include_screenshot: false returns the element tree without a screenshot, and its query argument narrows what comes back. use_desktop_tool is unchanged.

Session lifecycle

• VMs a session created, started, reset or restored are stopped, never deleted, when the session ends. Set AGENTPC_KEEP_RUNNING=1 to keep them running.
• list_vms shows each VM's owner. Agents should create their own uniquely named VM per task, and never reset, restore or delete one they didn't create. A VM whose session ended without stopping it (its server was killed) is stopped by the next MCP server and shows owner_running: false; create_vm with its name and image hands it back to the agent that made it.
• Each running VM takes 4 GB (Ubuntu, Arch) or 8 GB (Windows) of RAM, so delete VMs when done.
• The guest login is agent / agent (desktop and sudo; SSH takes only agentpc's key).

Approval prompts

Every desktop action goes through use_desktop_tool, which is marked destructive, so clients that confirm tool calls ask before each click or keystroke. inspect_desktop is marked read-only and only runs tools the driver marks read-only. To approve agentpc's tools up front:

That approves every agentpc tool, including upload_file and download_file, which read and write files on your Mac. The VMs themselves are throwaway: reset_vm undoes anything done inside one.

Tools also carry MCP annotations, which some clients use to decide what to confirm: list_vms, take_screenshot, list_desktop_tools, inspect_desktop, get_job_status, list_jobs, wait_for_service, list_forwards and read_vm_log are read-only. Tools that discard or overwrite state are marked destructive, including download_file, which writes to your Mac. start_vm, stop_vm and stop_job are idempotent.