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.

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.

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.

Protocol and embedded skill compatibility#

Cua Driver 0.28.0 and later supports the MCP 2026-07-28 revision over stdio. MCP protocol revisions use dates, so 2026-07-28 is the revision name.

Modern clients can discover Cua Driver without initialize and can list and read its embedded skill://cua-driver/ resources. Legacy clients continue to negotiate 2025-06-18 through initialize and receive the same Driver tools. The embedded skill does not grant desktop permissions or approve actions.

Client support for MCP resources also does not guarantee native skill activation. Use the client notes below and Install the Cua Driver agent skill when a filesystem skill is required.

Claude Code#

Register the plain stdio server:

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.

As of Claude Code 2.1.268, it can list and read the embedded Cua Driver resources when asked, but it does not add the remote skill to its native startup skill catalog. Install the filesystem skill when you want Claude Code to activate it as a skill.

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.

As of Codex 0.154.0, it can list and read Cua Driver's embedded skill through the MCP resource APIs. The filesystem install remains useful for older clients and for explicit local skill discovery.

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.

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:

1. 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.
2. 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 have a named preset for them. After completing the installation and permission steps on this page, use the client-specific registration and verification steps:

• Grok Build, xAI's coding CLI, uses stdio MCP. Grok Bot is a separate local-command integration.
• Kimi Code uses stdio MCP through its native CLI or configuration file.

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.