mait.sh1.69.2

Private beta: features and content may change. No warranty; use at your own risk.

Docs / Agent tools (MCP)

MCP VNC

Observe and operate a reachable VNC desktop, with screenshots and recordings to review the task.

For gUI test automation, remote Mac workflows, and systems without a browser-native interface.

Read from the top for the basics; the later sections go deeper.

Beta
All components

What it doesBasics

  • Reusable named connections
  • Keyboard, pointer, and clipboard control
  • Screenshots and WebM recording
  • Keep-awake support
  • Change-aware condensed recordings

First useBasics

  1. Inspect one desktop, perform a harmless action and check the resulting screen.
  2. Capture the current frame before acting.
  3. Drive one input, then verify with another screenshot; settled notifications are an explicit beta recording opt-in.

Everyday tasksEveryday use

Drive a remote graphical test

An agent must validate an application on a VNC-accessible desktop.

  1. Create a named connection with the target-specific template and capture the initial framebuffer.
  2. Drive one pointer or keyboard action.
  3. Capture and inspect the final state, then drop the connection.

What you getThe graphical workflow completes with explicit before-and-after evidence.

How to check: Initial and final screenshots document what the agent observed.

Condense a long GUI run

A long interaction needs a shorter review artifact without losing the original by default.

  1. Choose a capture rate and compatible analysis rate.
  2. Start recording with a documented condense profile.
  3. Stop recording and export needed resources before session end.

What you getActive periods are assembled into a condensed recording with event metadata.

How to check: The video resource, events index, tuning provenance, and optional retained original support review.

Settings to decideAdvanced

Default target or profiles
Use VNC_* variables for one target; use VNC_PROFILES_PATH and explicit IDs for several reviewed desktops.
Target template and encoding
Choose default or mac for raw, full-frame, reliably paced input; choose libvirt for ZRLE, incremental frames, and faster guest input. auto uses raw. Template defaults are overridden by profile/environment settings, then explicit call fields.
Recording and condensing
Keep condense.analysisFps at or below capture fps and decide whether the default retained original fits storage policy.
Artifact lifetime
Consume session URIs during the same MCP session and export important artifacts to an independent path before session end.

CommandsAdvanced

$ vnc_connection_create({"connectionId":"qa","template":"default"})
$ vnc_screenshot({"connectionId":"qa","inlineImage":true})
$ vnc_pointer({"connectionId":"qa","action":"click","x":500,"y":300})
$ vnc_screenshot({"connectionId":"qa","inlineImage":true})
$ vnc_connection_drop({"connectionId":"qa"})
$ mcp-vnc cli screenshot --output ./screen.png

Problems and fixesHelp

What you seeCheckFix
Connection fails or a profile cannot load.Validate host, credentials, encoding, profile path, and JSON shape.Correct the target or profile and recreate the named connection.
A successful screenshot or video URI no longer resolves.Confirm whether the reading client is still in the session that created it and whether its path was durable.Read or export resources during the producing session; after it ends, use a retained filesystem path if one exists.
Recording start fails or a whole-session recording remains false.Check for an active recording, framebuffer dimensions, filename validation, fps/analysis settings, and writable storage.Stop the conflicting recording or repair the named setting, then retry after confirming a real screenshot can be captured.
What you see
Connection fails or a profile cannot load.
Check
Validate host, credentials, encoding, profile path, and JSON shape.
Fix
Correct the target or profile and recreate the named connection.
What you see
A successful screenshot or video URI no longer resolves.
Check
Confirm whether the reading client is still in the session that created it and whether its path was durable.
Fix
Read or export resources during the producing session; after it ends, use a retained filesystem path if one exists.
What you see
Recording start fails or a whole-session recording remains false.
Check
Check for an active recording, framebuffer dimensions, filename validation, fps/analysis settings, and writable storage.
Fix
Stop the conflicting recording or repair the named setting, then retry after confirming a real screenshot can be captured.

All MCP VNC problems and fixes →

Good to knowHelp

  • VNC carries screen pixels and input.
  • Use one client per HTTP server process, or the stdio and Unix transports for per-connection isolation.
  • Use clipboard plus paste when exact text matters, and take a screenshot after input.