MCP and agents
The server exposes an MCP endpoint over Streamable HTTP at /mcp/ on the API port. Tools call the same actions as POST / and wait for the same request lock.
Connect a client
Claude Code:
claude mcp add --transport http desk http://localhost:8080/mcp/
With AUTH_TOKEN set:
claude mcp add --transport http desk http://localhost:8080/mcp/ \
--header "Authorization: Bearer change-me"
Other clients take the same URL and header in their HTTP MCP server config.
Tools
Each tool runs the action of the same name with the same parameters, except where the table says otherwise, and returns the action’s JSON response as text.
| Tool | Action and differences |
|---|---|
screenshot | desktop_screenshot with width, height, whLargest. Returns the PNG as an image, not JSON. Pass whLargest=512 to save tokens. |
get_resolution | get_resolution |
system_click, system_double_click, system_right_click | Same parameters as the actions. |
mouse_move | mouse_move |
system_drag | system_drag |
scroll | scroll, amount defaults to -3. |
human_pause | human_pause |
paste_text | paste_text, the default way to enter text. |
system_type | system_type. Giving typo_rate turns typos on. |
send_key | send_key |
desktop_list_windows, desktop_focus_window, desktop_move_resize_window, desktop_set_window_state, desktop_close_window, desktop_keybindings | The window actions. |
launch_app, kill_launched, run_command | The program actions. |
list_launched | list_launched with output only. |
set_clipboard | set_clipboard with text only. |
set_clipboard_data | set_clipboard with format and text (HTML), content_base64 (PNG) or files. |
get_clipboard | get_clipboard |
get_events, wait_for_event, begin_handoff, handoff_status, end_handoff | The event and handoff actions. |
run_script | run_script with steps, name (default mcp_script) and on_error. The whole script runs under one request lock, so no other request runs in between. Steps that already ran are not undone when a later one fails. |
desk_action | Any action by name with a params object, for actions without their own tool: system_hover, mouse_click, system_mouse_down, system_mouse_up, start_recording, stop_recording, recording_status, list_actions, ping, sleep, close, and plugin actions. |
The actions reference documents every parameter, default and return field.
The server is named auto-linux-desk. Its MCP instructions tell agents that coordinates are screen pixels from the top-left corner, to pass whLargest=512 to screenshots, to call desktop_list_windows before clicking into windows, to call desktop_keybindings once and press the shortcuts with send_key, to enter text with paste_text and keep system_type for a few characters, never to pass instant to send_key, and to use run_script for multi-step work.
Plugins can add, replace or remove tools and change the instructions. A plugin can also switch the server to script-only mode, where run_script is the only tool; see plugins.