MCP Tool Notes
Cross-cutting MCP tool contracts: shared parameters, required-parameter rules, platform-specific parameters, and the action response shape.
These notes are hand-maintained companions to the auto-generated MCP Tools reference. They document the cross-cutting parameter contract and response shape that span multiple tools and are not derivable from any single tool's schema.
Common parameters#
Several parameters are a shared cross-platform contract: the same JSON shape on Windows, macOS, and Linux, composed from canonical schema fragments and enforced by a CI consistency gate so the three platforms cannot drift. Tools accept them uniformly.
| Parameter | Where | Notes |
|---|---|---|
session | every action and cursor tool | Optional public run label. For multi-call work, prefer a short label and repeat it on every call that accepts it; it is not sticky. When this field is absent, the call uses the authenticated transport's private implicit session. A public label is never caller identity or authorization evidence. Accepted on all three platforms. |
target | move_cursor, click, drag, scroll, type_text, press_key, hotkey | Preferred tagged per-call target: {kind:"window", pid, window_id} or {kind:"desktop", display_id:"primary"}. It cannot be combined with legacy scope, pid, or window_id fields. |
delivery_mode | the input family (click, double_click, right_click, drag, scroll, type_text, press_key, hotkey) | "background" (default) tries to inject without fronting or raising the target. See Best-effort background. "foreground" briefly fronts the target, acts, then restores the prior frontmost. Use it when a background attempt did not land. Legacy "auto" is removed; omitted or unknown values fall back to "background" for safety. |
capture_mode | get_window_state | Deprecated and ignored. Still accepted for back-compat so old callers do not error, but it has no effect. get_window_state always returns both the accessibility tree and a screenshot by default. There is no ax/vision/som capture choice; the modality (ax vs px) is chosen at action time by how you address the target. |
include_screenshot | get_window_state | Boolean, default true (returns the tree and a screenshot). Set false to skip the screenshot grab and return the tree only when re-indexing before an element-ax action. |
modifier, button, element_index, element_token | pointer and element tools | Held modifier keys, mouse button, and the two element-addressing handles. |
Required parameters#
The required set is uniform across platforms: click requires nothing,
scroll requires direction, and zoom requires window_id plus
x1/y1/x2/y2. The preferred target makes the modality explicit.
Legacy flat calls still validate pid conditionally: a window action needs it,
while a desktop action omits it.
The first admitted stateful call creates the transport's implicit lifecycle session. Repeated unnamed clicks on the same MCP connection belong to that one session; they do not create one session per click. The default idle TTL is five minutes, separate from the cursor's visibility timeout. Transport close, explicit end, or idle expiry runs the same cleanup path.
PID-only window targets#
A window-scoped action may omit window_id only when its pid owns exactly one eligible top-level window. The driver resolves that unique window before dispatch. When the PID owns multiple windows, it sends no input and returns code: "ambiguous_window_target", effect: "refused", and candidate metadata. Select a candidate from that result or list_windows({pid}), then retry with the exact window_id. A PID with no eligible windows returns window_target_not_found. Explicit (pid, window_id) and element_token targets keep their exact resolution behavior.
Platform-specific parameters#
A few parameters are platform-specific by design and are intentionally NOT part of the shared contract:
| Parameter or tool | Platform | Why |
|---|---|---|
launch_app identifiers | macOS: bundle_id, urls. Windows: aumid, launch_path, path, start_minimized. | App launch is OS-native. name is the portable fallback that works on both. |
debug_window_info | Windows only | A window-handle / class / rect / z-order debug tool with no macOS or Linux counterpart. |
check_permissions.prompt | macOS only | Public tool calls are read-only by default. prompt:true is refused before platform dispatch; use the human-run cua-driver permissions grant setup command, which launches the installed app through LaunchServices. There is no Windows or Linux equivalent of TCC. |
| Per-call window or desktop target | all three platforms | target has the same tagged shape on each platform. display_id:"primary" is the portable desktop target in this release; unsupported display IDs fail explicitly. Legacy scope/config fields remain only for compatibility. |
modifier on a background click | honored on macOS and Linux; dropped on a Windows background click | A Windows background click goes through UIA Invoke / PostMessage, which carry no live keyboard state, so modifier takes effect only on the delivery_mode:"foreground" (SendInput) rung there. |
Action response shape#
Action tools (click, double_click, right_click, drag, scroll, type_text, press_key, hotkey, set_value) return these structured fields:
| Field | Type | Meaning | Value set / presence |
|---|---|---|---|
path | string | Delivery rung that ran. | "ax", "cgevent", "cgevent_fg", "key_events", "key_events_fg", "pixel", "x11_atspi", "x11_pixel", "x11_pixel_fg", "msaa". |
verified | boolean or absent | AX read-back verification result. true means the driver read the effect back through AX; false means the action ran but is unconfirmed; absent means the tool does not carry this field. | true, false, or absent. |
effect | string | Action confidence signal. | "confirmed", "unverifiable", "suspected_noop". |
escalation | object or absent | Machine-readable next-rung recommendation. Present only when the driver recommends climbing the ladder. | { recommended: "px" | "foreground" | "page", reason: string }, or absent. |
Per-tool notes#
get_window_state degraded results#
On Linux (and macOS/Windows), the structured result may include degraded: true alongside a degraded_reason string when the accessibility walk completed but found no actionable elements. This distinguishes "a11y bridge not up, daemon not on the session D-Bus, or non-AX surface" from a window that genuinely has no controls. Treat elements: [] as incomplete when degraded: true is set, and act by px off the screenshot returned in the same response.
page platform support#
get_text, query_dom, click_element, and execute_javascript work cross-platform (macOS, Windows, Linux). insert_text and type_keystrokes are implemented on macOS only for now; Windows and Linux return a clear "not implemented" error rather than a silent no-op. Tracked in trycua/cua#2084.