Cua Docs

Use Cua Driver with Claude Agent SDK

Choose same-process native callbacks or the MCP agent boundary in Python and TypeScript.

Claude Agent SDK supports both Cua Driver integration routes:

  • Use native callbacks when your application already owns the agent loop, driver runtime, permissions, and session lifecycle.
  • Use MCP when Claude is an external agent or should discover the complete Cua Driver tool catalog.

The native callbacks are packaged by Claude Agent SDK as an in-process SDK MCP server. Despite that helper's name, it does not start a subprocess or use a socket; each callback calls CuaDriver.create() in the application process.

Install the executable examples#

From libs/cua-driver/examples/agent-sdks:

python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt

Authenticate Claude Agent SDK using its normal local login or ANTHROPIC_API_KEY. Set CLAUDE_MODEL only when you need to override its default model.

Run the native callback route#

.venv/bin/python claude_agent.py --route native \
  "Inspect the fixture, enter a short value, submit it, and verify the result"

The examples expose only observe_desktop, click_desktop, type_text, and press_key. Their handlers call the same-process Python or TypeScript SDK. Every mutation returns a fresh desktop observation. If a call times out, the handler labels its outcome unknown and tells the model to inspect before any retry.

The complete executables live at libs/cua-driver/examples/agent-sdks/claude_agent.py and libs/cua-driver/examples/agent-sdks/claude_agent.ts in the Cua repository.

Run the MCP route#

Install Cua Driver so cua-driver is on PATH, then run:

.venv/bin/python claude_agent.py --route mcp \
  "Inspect the active app and summarize what is visible"

The host supplies one long-lived cua-driver mcp transport to Claude. The first admitted stateful call creates its implicit session, later unnamed calls reuse it, and transport shutdown runs lifecycle cleanup. Claude discovers the full live MCP surface; the generated Cua language packages are not acting as MCP clients.

Use only trusted tasks with these examples. They remove interactive approval prompts and deliberately exclude Claude Code's built-in shell and file tools.