Cua Docs

Use Cua Driver with Codex SDK

Configure Cua Driver MCP for the Python and TypeScript Codex SDKs.

Codex SDK supports MCP servers but does not expose application-owned custom tool callbacks. Use cua-driver mcp as its Cua Driver boundary. Do not build a second tool loop that translates the native SDK back into an ad hoc protocol.

Install the executable examples#

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

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

This installs openai-codex and imports it as openai_codex.

Install Cua Driver so cua-driver is on PATH, or set CUA_DRIVER_BIN to its absolute path.

Run a desktop task#

.venv/bin/python codex_agent.py \
  "Inspect the active app and summarize what is visible without changing it"

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

Both scripts:

  1. create one required, long-lived Cua MCP transport;
  2. let the first admitted stateful call create its implicit session;
  3. run Codex in a read-only filesystem sandbox;
  4. instruct Codex to use only Cua tools for desktop work; and
  5. rely on transport shutdown to run session cleanup.

The filesystem sandbox does not sandbox the separate desktop MCP server. Restrict the task itself, choose an exact window or desktop target for each Cua action, apply the appropriate authorization policy, and never blindly retry a mutation after a timeout or disconnect.