Twelve tools for operating a desktop.
Six of the twelve tools have command-line equivalents; the connection and recording tools, and typing several lines at once, exist only as tools. Every tool except the three that manage connections accepts an optional connectionId; leave it out and the call goes to the implicit default connection, which is filled from the service's environment. A named connection is safer, because every call then says which desktop it means.
Open, list and close named connections.
| Tool | Use it to | Parameters |
|---|---|---|
vnc_connection_create | Open a named connection to a VNC desktop and connect at once. A misspelled field or an invalid recording setting fails the call with no connection made, whereas a recording that cannot start does not fail the connection. | connectionId, template, host, port, password, username, profile, name, tags, vncEncoding, saveVideo (all optional) |
vnc_connection_list | List the connections of this session, without their credentials. It does not check that a desktop is reachable. | none |
vnc_connection_drop | Close a connection and publish its recording. It also stops any keep-awake task on the connection, and it does not undo anything done on the desktop. | connectionId (required) |
Why: name every desktop, so a later call cannot land on the wrong one. Fields merge in a fixed order: the template, the service's own defaults, the named profile, then the fields of the call, which always win. A call with a field the tool does not know fails, and names the field.
Pick the template for the kind of target:
| Template | Use it for | Typing | Encoding |
|---|---|---|---|
default | An unknown VNC server | Slow: about 270 ms a character, at most 166 plain characters per call | raw |
mac | macOS Screen Sharing, with username and password | The same slow pacing | raw |
libvirt | A virtual machine console on a fast network | Fast: about 6 ms a character, at most 7500 characters per call | zrle |
Capture what is on screen.
| Tool | Use it to | Parameters |
|---|---|---|
vnc_screenshot | Capture the screen and publish it as a file you can fetch. The reply carries the file, not the picture, unless you ask for it inline, and the picture's size is the coordinate space for every pointer action. | delay (0 to 45000 ms), colorDepth (0, 8, 16, 24, 32; default 8), imageFormat (png, jpeg, webp), quality, filename, inlineImage |
Why: look before and after every change. The default colour depth is 8 bits, so ask for 24 when colour matters, and ask for inlineImage only when your client can afford the image in the answer.
Move the mouse, type and press keys.
| Tool | Use it to | Parameters |
|---|---|---|
vnc_pointer | Click, drag, scroll or move the mouse, chosen by the action. A click is one uninterruptible gesture, so no other pointer input can land inside it, and a position outside the screen is refused. | action (required), x, y, button, double, start_x, start_y, end_x, end_y, direction, clicks |
vnc_type | Type one line, optionally followed by Enter, or several lines. Text is typed as on a US keyboard, so a character with no key there fails the call before anything is typed. | action (required), text, enter, lines |
vnc_key_press | Press a key or a combination of keys, such as Ctrl+Alt+Delete. | key (required) |
vnc_clipboard_receive | Read text from the desktop's clipboard. It waits about three seconds, so copy on the desktop while the call waits. To enter text, use vnc_type; clipboard send is not available in this release. | none |
Why: the tools return when the input has been sent, not when the desktop has reacted. Take a screenshot to confirm every change. Typing is paced for the target and a call that would take more than 45 seconds is refused before anything is typed, so split a long text across calls. A call interrupted by a dropped connection can be retried from its first character and type the text twice, so look at the field before you type again.
Record the screen to video.
| Tool | Use it to | Parameters |
|---|---|---|
vnc_start_video | Record the connection to a WebM video until you stop it. The recording has no sound, because VNC carries none. | quality (economy, standard, fidelity), fps (1 to 60), codec (vp9, vp8), filename, maxDurationSecs, condense |
vnc_stop_video | Stop the recording and publish the video. The result reports the duration, the frames encoded and dropped, and why the recording stopped. | none |
The quality presets are 5 frames a second for economy, 10 for standard (the default) and 15 for fidelity. A connection can also record for its whole lifetime: pass saveVideo to vnc_connection_create with the same options. With condense the recording is shortened to what changed and, if you opt in, the agent is told when the screen settles or will not settle. A condensed recording shortens review time, not necessarily file size.
Why: a plain recording is the evidence, and a settled notification lets the agent wait without taking a screenshot every few seconds. Stop a recording before you start another: a condensed start is refused while any recording runs, and a plain start while another plain one runs.
Stop the display from sleeping.
| Tool | Use it to | Parameters |
|---|---|---|
vnc_keep_awake | Start or stop a background task that nudges the pointer now and then to keep the display from sleeping. It needs a known pointer position, so move or click the pointer once first, and after a reconnect start it again. | enabled, intervalMs (default 60000), pixels (default 1) |
The task stops by itself when the connection is dropped. Its tick count proves the task is running, not that the machine stayed awake.
What to expect when a call fails.
A tool failure comes back as a tool error with a message, not as a protocol error. The limits that matter:
| Limit | Value |
|---|---|
| Calls | 30 per minute across the vnc_ tools |
| One call | 60 seconds |
| Connections | 16 per session by default |
| Screenshot delay | up to 45000 ms |
| One typing call | planned pacing of at most 45 seconds: 166 plain characters on default and mac, 7500 on libvirt |
| Coordinates | inside the current screen, from the top left corner |
| Audio | none: VNC carries no sound, and recordings are video only |
| Sessions | end after 30 idle minutes by default, which disconnects the desktop and ends the links to its pictures and videos |
Screenshots and videos are written on the machine that runs MCP VNC and are readable only in the session that took them, so save what you need through your client. See Troubleshooting.