Connect your agent to Cua Driver

Connect an agent to Cua Driver through MCP or the Cua Driver skill and CLI.

Cua Driver lets a computer-use agent drive the host desktop: installed apps, signed-in browser sessions, local files opened in apps, and the current OS user session. MCP-capable agents connect through cua-driver mcp; skill-based agents such as Prime Agent call the CLI directly. Grok Bot is a separate path; it is not Grok Build and does not use stdio MCP.

Building Cua Driver into an application instead? Start with Choose a Cua Driver integration to compare MCP, the direct SDK, private workers, and app-hosted services.

This connects an agent to Cua Driver on the current machine. To create a disposable local desktop, use Cua Sandbox instead.

Before you start#

Install Cua Driver and verify it can see the host desktop:

cua-driver --version
cua-driver call list_apps

On macOS, grant Accessibility and Screen Recording before connecting an agent:

cua-driver permissions status

See Install Cua Driver and macOS permissions for setup details.

Decide the permission mode first#

Registering the server does not choose an authorization permission mode — the process that owns the driver runtime does, at launch. Every config below therefore runs in the default standard mode unless you change that process.

macOS: cua-driver mcp proxies to the CuaDriver.app daemon to keep TCC attribution with the app, so that daemon's launch flags decide the mode. Start it in the mode you want before the client connects, and use autostart to make that stick.
Windows and Linux: bare cua-driver mcp owns its own runtime and has no --permission-mode flag. Either set CUA_DRIVER_PERMISSION_MODE — plus CUA_DRIVER_CAPABILITY_MANIFEST_FILE and CUA_DRIVER_CAPABILITY_MANIFEST_APPROVED for bounded — in the client's env block, or run a cua-driver serve daemon in that mode and point the client at it with --socket.

--grant existing-profile is the one authorization flag cua-driver mcp accepts directly, and it applies only to a runtime this command launches. An agent cannot widen any of this from a tool call.

A standard-mode runtime allows input against every application on the desktop. If an agent should reach only a reviewed set of apps, origins, and directories, register it against a bounded runtime instead — see Write a capability manifest.

Generate the client config#

Use mcp-config to print the registration command or JSON for a supported client:

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

The generated reference is the source of truth for the complete roster and exact command shapes: cua-driver mcp-config.

Claude Code#

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

Claude Code can also use Cua Driver's computer-use compatibility profile. Generate the current command:

cua-driver mcp-config --client claude

That profile exposes the same driver tools under the compatibility server name. It still runs Cua Driver over MCP; Anthropic's native computer-use API is separate.

Using a local model

Claude Code can also act as the harness for a model served on the same machine. Follow Run a local model with Cua Driver for a tested Muse Glimmer setup and a smaller MCP tool surface.

Codex#

Print the Codex command:

cua-driver mcp-config --client codex

It emits a registration using the absolute installed binary path, which avoids PATH issues in app-launched Codex sessions:

codex mcp add cua-driver -- /Users/you/.local/bin/cua-driver mcp
codex mcp list

Restart Codex or open a fresh session after adding the server. For richer agent guidance, install the Cua Driver skill:

cua-driver skills install
cua-driver skills status

See Install the Cua Driver agent skill for the ClawHub and direct-install paths.

Prime Agent#

Prime Agent uses Cua Driver through its persistent IPython environment and the Cua Driver agent skill. It does not need a local MCP registration.

Install the skill pack after both tools are installed:

cua-driver skills install
cua-driver skills status

Cua Driver links the skill into ~/.prime/agent/skills/ when Prime Agent's skill directory exists. Prime Agent also scans the shared ~/.agents/skills/ directory, so an existing Codex-targeted link remains discoverable. Run /reload in Prime Agent or start a new session after installation, then ask it to use the Cua Driver skill. Use /skill:cua-driver to invoke it explicitly. See Prime Agent's skill documentation for its complete discovery and invocation behavior.

Print the same current guidance from the installed binary:

cua-driver mcp-config --client prime-agent

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"
    }
  }
}

Restart Cursor and confirm cua-driver appears in the MCP server list.

Other supported clients#

mcp-config also prints the right shape for clients that use a config file or a different add command.

Client	Generate with	Notes
Antigravity	`cua-driver mcp-config --client antigravity`	Paste into `~/.gemini/config/mcp_config.json`; `--client gemini` is a legacy alias.
OpenClaw	`cua-driver mcp-config --client openclaw`	Normal gateway-spawned MCP does not inherit OpenClaw.app's macOS permission grants; embedded hosts should use Embedding.
OpenCode	`cua-driver mcp-config --client opencode`	Configure a real MCP server so screenshots are preserved in image blocks.
Pi	`cua-driver mcp-config --client pi`	Pi does not support MCP natively; use one-shot `cua-driver call …` commands from its shell.
Qwen Code	`cua-driver mcp-config --client qwen`	Supports both a CLI add command and `~/.qwen/settings.json`.
Factory Droid	`cua-driver mcp-config --client droid`	Supports CLI and JSON config forms.
ZCode	`cua-driver mcp-config --client zcode`	Configure MCP in the GUI, or use `zai mcp add` for Z.ai's separate CLI.

Generic MCP JSON#

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

cua-driver mcp-config

It returns:

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

After saving the config, restart the client and confirm the cua-driver server is connected.

Grok Bot#

Grok Bot is not Grok Build. It has no mcp-config preset and does not use stdio MCP. See Grok Bot.

Two valid setups:

Your local Mac or Windows computer. Install Cua Driver there. Grok Bot uses local-command execution (cua-driver call …) behind its local-computer approval policy.
Grok Bot's persistent cloud Linux computer. If that machine is the desktop being driven, install Cua Driver there and call cua-driver on it.

Clients without a dedicated preset#

Some MCP clients can run Cua Driver directly even though mcp-config does not yet have a named preset for them. Resolve the absolute executable path first with command -v cua-driver, then use the client's native command:

# Grok Build (xAI coding CLI, not Grok Bot)
grok mcp add cua-driver -- /absolute/path/to/cua-driver mcp
grok mcp doctor cua-driver
 
# Kimi Code CLI
kimi mcp add cua-driver -- /absolute/path/to/cua-driver mcp
kimi mcp test cua-driver

These commands use each client's documented stdio MCP interface and the standard cua-driver mcp entry point. See the focused guides for Grok Build and Kimi Code.

T3 Code is a control plane for other coding agents rather than a separate MCP client. Configure Cua Driver in the underlying harness, then launch that harness from T3 Code.

Next steps#

Keep Cua Driver running: keep the daemon alive across reboots and sessions.
Agent action policy: behavior agent wrappers should follow for element_index, x,y, and foreground escalation.
MCP tools: inspect every exposed tool and parameter.