Cua Docs

Connect your agent

Register Cua Driver as an MCP server with Claude Code, Codex, Cursor, Antigravity, OpenClaw, OpenCode, Hermes, and Pi.

cua-driver mcp runs as a stdio MCP server. Register it with an MCP-capable agent when you want that agent to control the host desktop through cua-driver.

This verb wires the agent to Cua Driver, which is control of the HOST machine ONLY. It does NOT connect an agent to a cua sandbox. Sandbox access is a separate, SDK-first path: use the Computer SDK, or the separate cua-agent MCP server. Do not imply that mcp-config gives sandbox access.

Grant the required permissions before you connect an agent. On macOS, grant Accessibility and Screen Recording. Verify them with cua-driver call check_permissions.

The helper command prints the exact registration snippet for each supported client:

cua-driver mcp-config --client <client>

The claude client can register a computer-use compatibility surface through --claude-code-computer-use-compat. Every client gets the same driver tools. There is no standalone screenshot tool, so window capture comes from get_window_state (set capture_mode to vision for a screenshot).

Claude Code

Register the plain stdio server:

claude mcp add --transport stdio cua-driver -- cua-driver mcp

Verify:

claude mcp list
# cua-driver: cua-driver mcp (stdio) - connected

Claude Code also supports a computer-use compatibility mode. Generate the command:

cua-driver mcp-config --client claude

It emits:

claude mcp add-json cua-computer-use '{"command":"cua-driver","args":["mcp","--claude-code-computer-use-compat"]}'

This registers the server under the key cua-computer-use and passes --claude-code-computer-use-compat. The flag selects the Claude Code compat surface. The compat screenshot tool was removed in #1692, so the flag has no tool-surface effect today; the wiring stays in place for any future compat-gated tool. Capture the target window with get_window_state (set capture_mode to vision for a screenshot).

This is NOT Anthropic's native computer-use API. It is Cua Driver's MCP compatibility mode for Claude Code. Start with launch_app or list_windows, then capture the target window with get_window_state.

Codex

Register the stdio server:

codex mcp add cua-driver -- cua-driver mcp

Verify:

codex mcp list

Cursor

Generate the Cursor snippet:

cua-driver mcp-config --client cursor

Paste the JSON into ~/.cursor/mcp.json, or .cursor/mcp.json for project scope:

{
  "mcpServers": {
    "cua-driver": {
      "command": "cua-driver",
      "args": ["mcp"],
      "type": "stdio"
    }
  }
}

Verify: restart Cursor and confirm cua-driver appears in the MCP server list.

Antigravity

Generate the Antigravity snippet:

cua-driver mcp-config --client antigravity

Antigravity CLI, the agy binary and successor to Gemini CLI, has no agy mcp add subcommand. Paste the printed JSON into ~/.gemini/config/mcp_config.json, merging it under the top-level mcpServers object. On Windows, use %USERPROFILE%\.gemini\config\mcp_config.json. Restart agy after saving. The same file is shared with the Antigravity IDE. --client gemini is a legacy alias.

{
  "mcpServers": {
    "cua-driver": {
      "command": "cua-driver",
      "args": ["mcp"]
    }
  }
}

Verify: restart agy or the Antigravity IDE and confirm cua-driver is listed as an MCP server.

OpenClaw

Register the stdio server:

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'

Verify: restart OpenClaw and confirm cua-driver is available in the MCP server list.

OpenCode

Generate the OpenCode snippet:

cua-driver mcp-config --client opencode

Paste it under mcp in opencode.json, or in ~/.config/opencode/config.json for global config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cua-driver": {
      "type": "local",
      "command": ["cua-driver", "mcp"],
      "enabled": true
    }
  }
}

Configure it as a real MCP server. If MCP is not configured, OpenCode runs Cua Driver as a shell subprocess, the screenshot image block is dropped, and the model gets only the AX tree with no visual context.

Verify: restart OpenCode and confirm cua-driver appears under MCP servers.

Hermes

Generate the Hermes snippet:

cua-driver mcp-config --client hermes

Paste it under mcp_servers in ~/.hermes/config.yaml:

mcp_servers:
  cua-driver:
    command: "cua-driver"
    args: ["mcp"]

Reload MCP servers inside Hermes:

/reload-mcp

Verify: confirm Hermes reports cua-driver after /reload-mcp.

Pi

Pi, badlogic/pi-mono, does not support MCP natively. The author has stated MCP support will not be added for context-budget reasons, so this client is an honest caveat rather than an MCP registration path.

Run:

cua-driver mcp-config --client pi

The output tells you to use Cua Driver as a plain CLI from inside Pi instead:

cua-driver list_apps
cua-driver click '{"pid": 1234, "x": 100, "y": 200}'
cua-driver --help        # full tool catalog

Each call is one-shot and returns JSON or text on stdout, which is the shape Pi is built around.

Verify: run cua-driver --help from the same Pi shell context.

Any other client

For any client that accepts the standard mcpServers shape, print the generic config:

cua-driver mcp-config

Output:

{
  "mcpServers": {
    "cua-driver": {
      "command": "cua-driver",
      "args": ["mcp"]
    }
  }
}

Verify: restart the client and confirm cua-driver appears in its MCP server list.

Next steps