Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(cua-driver): document modern MCP client compatibility (#3741)

Francesco Bonacci5d33b7bffedc
diff --git a/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx b/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx
index 38f9647504..ca0d9b3f8a 100644
--- a/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx
+++ b/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx
@@ -73,6 +73,21 @@ 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`](/reference/cua-driver/cli-reference#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](/how-to-guides/driver/install-agent-skill) when a filesystem skill is
+required.
+
## Claude Code
Register the plain stdio server:
@@ -90,6 +105,11 @@ 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.
+
<Callout type="info" title="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](/how-to-guides/driver/run-with-local-model) for a tested Muse Glimmer
@@ -120,6 +140,10 @@ cua-driver skills status
See [Install the Cua Driver agent skill](/how-to-guides/driver/install-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
diff --git a/docs/content/docs/how-to-guides/driver/install-agent-skill.mdx b/docs/content/docs/how-to-guides/driver/install-agent-skill.mdx
index 4ca83c6681..3a084a2c0e 100644
--- a/docs/content/docs/how-to-guides/driver/install-agent-skill.mdx
+++ b/docs/content/docs/how-to-guides/driver/install-agent-skill.mdx
@@ -11,6 +11,10 @@ The Cua Driver agent skill teaches an agent how to choose tools, address windows
The skill contains agent instructions. It does not install the `cua-driver` executable. [Install Cua Driver](/how-to-guides/driver/install) on the same machine first.
</Callout>
+<Callout type="info" title="Embedded skill over MCP">
+ Cua Driver 0.28.0 and later also serves this release-matched skill from its stdio MCP endpoint. A client that supports MCP resources can read it without a filesystem install, but the client still decides whether reading a resource activates a skill. The direct install on this page remains the compatible path for native filesystem skill discovery.
+</Callout>
+
## Install from ClawHub
Run the command from your OpenClaw workspace:
@@ -69,6 +73,25 @@ cua-driver skills install
cua-driver skills status
```
+With Cua Driver 0.28.0, fresh Codex and Claude Code installs may not create
+their skill directories until the first skill is installed. If `skills status`
+reports the relevant agent directory as absent, create only that client's
+parent directory and run the installer again:
+
+```bash
+# Codex
+mkdir -p ~/.agents/skills
+
+# Claude Code
+mkdir -p ~/.claude/skills
+
+cua-driver skills install
+```
+
+In Windows PowerShell, use `New-Item -ItemType Directory -Force
+"$HOME\.agents\skills"` for Codex or `New-Item -ItemType Directory -Force
+"$HOME\.claude\skills"` for Claude Code, then rerun `cua-driver skills install`.
+
Direct installation keeps only the current host's OS guide by default. Pass `--all-platforms` when the same skill directory must cover macOS, Windows, and Linux:
```bash
diff --git a/docs/content/docs/use-cua-with/claude-code.mdx b/docs/content/docs/use-cua-with/claude-code.mdx
index d6f6aeb855..0c99f0cce8 100644
--- a/docs/content/docs/use-cua-with/claude-code.mdx
+++ b/docs/content/docs/use-cua-with/claude-code.mdx
@@ -19,6 +19,20 @@ cua-driver mcp-config --client claude
Restart Claude Code or open a fresh session after adding the server. On macOS, the Cua Driver app identity that owns the runtime needs Accessibility and Screen Recording permission.
+Cua Driver 0.28.0 serves a release-matched skill through MCP resources. As of
+Claude Code 2.1.268, it can list and read those resources explicitly, but
+it does not add the remote skill to its native startup skill catalog. Install
+the filesystem skill when you want native Claude Code skill activation:
+
+```bash
+mkdir -p ~/.claude/skills
+cua-driver skills install
+cua-driver skills status
+```
+
+Claude Code's MCP permission policy remains separate from Cua Driver's
+permission mode. Both layers must allow a mutating desktop action.
+
Continue with [Connect your agent to Cua Driver](/how-to-guides/driver/connect-your-agent#claude-code) for permission modes, the computer-use compatibility profile, and local-model setup.
<VideoDemo
diff --git a/docs/content/docs/use-cua-with/codex.mdx b/docs/content/docs/use-cua-with/codex.mdx
index 557c84416c..7f86aaca00 100644
--- a/docs/content/docs/use-cua-with/codex.mdx
+++ b/docs/content/docs/use-cua-with/codex.mdx
@@ -24,6 +24,16 @@ cua-driver skills install
cua-driver skills status
```
+Cua Driver 0.28.0 serves the same release-matched skill through its stdio MCP
+endpoint. As of Codex 0.154.0, it can list and read those resources in a fresh
+session. Install the filesystem skill for older Codex versions or when you want
+an explicit local skill entry.
+
+Codex applies its own approval policy to MCP calls. Registration and remote
+skill discovery do not approve mutating actions; allow the requested Driver
+action in Codex when prompted or configure an appropriate Codex policy for the
+test environment.
+
Continue with [Connect your agent to Cua Driver](/how-to-guides/driver/connect-your-agent#codex) and [Install the Cua Driver agent skill](/how-to-guides/driver/install-agent-skill).
Then try a complete workflow: [build a map](/how-to-guides/recipes/build-and-inspect-a-map),
diff --git a/libs/cua-driver/docs/mcp-protocol-and-skills.md b/libs/cua-driver/docs/mcp-protocol-and-skills.md
index 904ccece93..3852474e02 100644
--- a/libs/cua-driver/docs/mcp-protocol-and-skills.md
+++ b/libs/cua-driver/docs/mcp-protocol-and-skills.md
@@ -4,8 +4,10 @@ The Rust `cua-driver mcp` endpoint supports modern MCP `2026-07-28` over stdio
and retains the legacy `initialize` flow with version `2025-06-18`. Direct and
daemon-backed stdio use the same protocol and skill catalog.
-This document describes the implementation in PR #3609. It is not a claim
-that an existing installed release contains these changes.
+This implementation shipped in Cua Driver 0.28.0 through PR #3609. MCP uses
+date-based protocol revisions: `2026-07-28` is the modern revision implemented
+here. The JSON-RPC `2.0` envelope and MCP SDK 2.x package versions are separate
+version numbers, so “MCP 2.0” is not a precise protocol revision name.
## Connect
@@ -87,6 +89,22 @@ using it. Reading a resource does not activate a skill. The host owns skill
selection, content-bound consent, and any execution approval. A base MCP client
may support tools and resource reads without supporting native skill loading.
+## Verified client behavior
+
+A clean macOS VM test with the released Cua Driver 0.28.0 established these
+client boundaries:
+
+- Codex 0.154.0 discovered and read the embedded skill through its MCP resource
+ APIs with the filesystem skill link absent, then used the Driver tools.
+- Claude Code 2.1.268 listed and read the embedded resources explicitly with
+ the filesystem skill link absent. It did not include the remote skill in its
+ native startup skill catalog, so filesystem installation remains the native
+ activation path for that client version.
+
+Both clients completed a background Calculator action while another app stayed
+active. Those runs verify client interoperability and resource access. They do
+not change the host-owned activation, consent, or action-approval boundaries.
+
The Skills extension follows accepted SEP-2640 at
`d6b31a03504c15677d49b922b6b6ace0ef65728d`; its upstream publication is still
pending. In particular, cache metadata for `skills/get` is unresolved upstream,