MCP tool reference

This is the complete list of tools an AI client gets from https://wecommander.app/mcp. Tools that act on a machine take device_id (agent devices) or target (a target_id from targets_list, which can also be a shared SSH server). Every tool carries standard MCP annotations (read-only, destructive, idempotent, open-world) so clients can show them.

How to read the risk column

Discovery and workspace

Start here: what the AI can reach and with which permissions.

ToolWhat it doesRisk and approvalWhereKey arguments
devices_listEnrolled agent devices with online state and each device's trust level, run as, root capability and safety net.Read-only: runs directlyWorkspacenone
targets_listEvery place the AI can act on: agent devices and shared SSH servers, with target_id, kind, online, capabilities, preset, sudo, trust, run as and safety net. Pass target_id as target to other tools.Read-only: runs directlyWorkspacenone
app_errorsRecent errors reported by the WECOMMANDER apps of this workspace, newest first, with platform, build, message and stack; user folder names removed.Read-only: runs directlyWorkspacelimit (1–100)
get_recent_tool_callsPaginated, sanitised history of your own recent tool calls on the selected device.Read-only: runs directlyAgent devices (Windows, macOS, Linux)device_id, limit, offset
get_usage_statsYour tool calls by name over the past 30 days on the selected device.Read-only: runs directlyAgent devices (Windows, macOS, Linux)device_id
policy_infoThe agent-enforced allowed folders, limits and switches (commands, file writes, output redaction, system logs).Read-only: runs directlyAgent devices (Windows, macOS, Linux)device_id

System, health and logs

Read the state of a machine.

ToolWhat it doesRisk and approvalWhereKey arguments
system_infoOperating system, host name and basic system information.Read-only: runs directlyAgent devices (Windows, macOS, Linux)device_id
health_snapshotCPU usage and load, memory and swap, disks, network counters and the top processes by CPU and memory.Read-only: runs directlyAgent devices (Windows, macOS, Linux)device_id, top (1–20)
log_queryBounded log search, newest first: the systemd journal (Linux; window, unit, level) or the tail of a log file inside the allowed folders. Repeated messages grouped; secrets masked.Read-only: runs directlyAgent devices; journal on Linux onlydevice_id, source (journal|file), path, unit, since_minutes, level, pattern, limit

Files: reading

All file tools stay inside the device's allowed folders on agents; on SSH servers they run over SFTP with the SSH user's rights.

ToolWhat it doesRisk and approvalWhereKey arguments
fs_listList a folder.Read-only: runs directlyAgent devices and SSH servers (Hybrid Access)path
fs_statFile or folder metadata.Read-only: runs directlyAgent devices and SSH servers (Hybrid Access)path
fs_readRead a file as UTF-8 text or base64.Read-only: runs directlyAgent devices and SSH servers (Hybrid Access)path, max_bytes
fs_read_linesA page of lines (zero-based offset; negative counts from the end); up to 1000 lines and 256 KiB.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, offset_lines, limit_lines
fs_read_multipleUp to ten files in one call (64 KiB each, 256 KiB total), with per-file errors.Read-only: runs directlyAgent devices (Windows, macOS, Linux)paths, max_bytes
fs_treeA bounded recursive folder tree, without following symbolic links.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, max_depth, max_entries
image_inspectPNG, JPEG, GIF or WebP dimensions and metadata from the headers only.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path

Office documents and PDF

Read Word, Excel and PDF files without running macros or loading external resources.

ToolWhat it doesRisk and approvalWhereKey arguments
pdf_readThe text layer of up to 20 PDF pages (start_page 1-based; negative counts from the end).Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, start_page, page_count
docx_inspectParagraph and table counts of a Word document.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path
docx_read_paragraphsUp to 100 paragraphs as text, including text in tables.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, offset, limit
docx_read_tableUp to 50 rows of one table (20 cells per row).Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, table_index, offset_rows, limit_rows
xlsx_inspectThe worksheets of an XLSX or XLSM workbook.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path
xlsx_read_rangeUp to 50 rows by 20 columns of one sheet; formulas are not evaluated.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, sheet, start_row, start_column, row_count, column_count
xlsx_findSearch cached cell values (up to 50,000 cells, 30 sheets, 100 matches).Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, query, sheet, case_sensitive, max_results
xlsx_write_cellsWrite up to 100 cells to a new XLSX file; the original is never overwritten.Change inside allowed folders: runs without approval (operator role); refused by read-only devicesAgent devices (Windows, macOS, Linux)path, output_path, sheet, updates, expected_sha256

Files: changing

Writes can carry expected_sha256 so a file changed in the meantime is never overwritten.

ToolWhat it doesRisk and approvalWhereKey arguments
fs_writeWrite a file (base64 content); with_undo keeps a snapshot of the previous content (up to 4 MiB). As root, a file the service user cannot write is written as root (no snapshot then).Change inside allowed folders: runs without approval (operator role); refused by read-only devices. On SSH servers: needs approvalAgent devices and SSH servers (Hybrid Access)path, content_base64, create_parents, expected_sha256, with_undo
fs_appendAppend to a file; with_undo keeps a snapshot.Change inside allowed folders: runs without approval (operator role); refused by read-only devicesAgent devices (Windows, macOS, Linux)path, content_base64, expected_sha256, with_undo
fs_mkdirCreate a folder.Change inside allowed folders: runs without approval (operator role); refused by read-only devices. On SSH servers: needs approvalAgent devices and SSH servers (Hybrid Access)path, recursive
fs_moveMove or rename; the destination must not exist.Change inside allowed folders: runs without approval (operator role); refused by read-only devices. On SSH servers: needs approvalAgent devices and SSH servers (Hybrid Access)source, destination
fs_replaceExact search-and-replace edit; by default the text must match exactly once. Keeps an undo snapshot.Change inside allowed folders: runs without approval (operator role); refused by read-only devicesAgent devices (Windows, macOS, Linux)path, search, replace, replace_all, expected_sha256
fs_deleteDelete a file or folder; expected_sha256 deletes a file only if unchanged.High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trustAgent devices and SSH servers (Hybrid Access)path, recursive, expected_sha256, approval_token
fs_versionsUp to eight undo snapshots of a file.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path
fs_undoRestore a snapshot, only if the file's current SHA-256 matches; the snapshot is used up.Change inside allowed folders: runs without approval (operator role); refused by read-only devicesAgent devices (Windows, macOS, Linux)path, undo_id, expected_sha256

Bounded searches inside the allowed folders.

ToolWhat it doesRisk and approvalWhereKey arguments
fs_searchSearch file and folder names recursively.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, query, case_sensitive, max_results
text_searchSearch literal text in UTF-8 files recursively.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, query, case_sensitive, max_results
code_searchThe same as text_search, named for coding clients.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, query, case_sensitive, max_results
start_searchStart an asynchronous file-name or content search (up to 500 matches).Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, query, search_type (files|content), case_sensitive, start_paused
get_more_search_resultsA page of a search's results; pending until it completes.Read-only: runs directlyAgent devices (Windows, macOS, Linux)search_id, offset, length
list_searchesYour active and recent searches on the device.Read-only: runs directlyAgent devices (Windows, macOS, Linux)device_id
pause_searchPause a running search for up to 15 seconds.Session control: runs directlyAgent devices (Windows, macOS, Linux)search_id
resume_searchResume a paused search.Session control: runs directlyAgent devices (Windows, macOS, Linux)search_id
stop_searchDiscard a search and its results.Session control: runs directlyAgent devices (Windows, macOS, Linux)search_id

Commands and processes

Commands run as the agent's service user, or as root when the device's run as is root (Linux only). The safety net refuses catastrophic commands even with an approval.

ToolWhat it doesRisk and approvalWhereKey arguments
process_execRun a shell command with an optional working folder and time limit. On SSH servers it runs as the SSH user, or through sudo -n as root when allowed.High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trust. Safety net appliesAgent devices and SSH servers (Hybrid Access)command, cwd, timeout_ms, approval_token
process_listVisible processes (secrets in command lines masked).Read-only: runs directlyAgent devices (Windows, macOS, Linux)device_id
process_killTerminate a process by PID.High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trustAgent devices (Windows, macOS, Linux)pid, approval_token

Background tasks

Long-running commands that survive AI and gateway disconnects while the agent runs.

ToolWhat it doesRisk and approvalWhereKey arguments
task_startStart a persistent background command.High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trust. Safety net appliesAgent devices (Windows, macOS, Linux)command, cwd, timeout_ms, approval_token
task_statusStatus and retained output of a task.Read-only: runs directlyAgent devices (Windows, macOS, Linux)task_id
task_listRetained tasks, so a reconnected client can find its task ids.Read-only: runs directlyAgent devices (Windows, macOS, Linux)device_id
task_cancelCancel a task.High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trustAgent devices (Windows, macOS, Linux)task_id, approval_token

Interactive terminals

Persistent PTY sessions with up to 1 MiB of retained history.

ToolWhat it doesRisk and approvalWhereKey arguments
terminal_startOpen a terminal session with a shell, folder and size.High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trustAgent devices (Windows, macOS, Linux)shell, cwd, cols, rows, approval_token
terminal_inputType up to 256 KiB into a terminal. Each exact input needs approval, because it runs in the shell.High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trust. Safety net appliesAgent devices (Windows, macOS, Linux)session_id, data_base64, approval_token
terminal_readRead buffered output.Read-only: runs directlyAgent devices (Windows, macOS, Linux)session_id, max_bytes
terminal_read_pageRead retained history without consuming it, by byte offset.Read-only: runs directlyAgent devices (Windows, macOS, Linux)session_id, offset_bytes, max_bytes
terminal_resizeResize a terminal.Session control: runs directlyAgent devices (Windows, macOS, Linux)session_id, cols, rows
terminal_stopClose a terminal session.High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trustAgent devices (Windows, macOS, Linux)session_id, approval_token
terminal_listOpen sessions with process ids and retained output sizes.Read-only: runs directlyAgent devices (Windows, macOS, Linux)device_id

Server management (Linux)

The same fixed scripts as the desktop app's server management screens.

ToolWhat it doesRisk and approvalWhereKey arguments
server_overviewHost name, OS, kernel, uptime, load, CPU, memory, swap, disks, reboot required, pending updates, process and zombie counts, and whether root is available.Read-only: runs directlyLinux agent devices and SSH serverstarget or device_id
server_disk_usageThe 40 largest folders inside a path (default /) on one disk, plus Docker's usage.Read-only: runs directlyLinux agent devices and SSH serverspath
server_cleanup_scanWhat can be freed safely, by category and per Docker daemon, with sizes and the exact command each runs.Read-only: runs directlyLinux agent devices and SSH serverstarget or device_id
server_cleanup_runRun the cleanup of the given category ids as root (Docker through its own prune). Never touches application data, databases, containers or volumes.High risk: needs approval of this exact call unless full trustLinux agent devices and SSH serversids
server_processesEvery process and the zombies grouped by parent, with the owning container or service and whether it is protected.Read-only: runs directlyLinux agent devices and SSH serverstarget or device_id
server_process_signalSend reap (SIGCHLD), term or kill to one process; the name must still match; protected processes refused; databases need confirm_database.High risk: needs approval of this exact call unless full trustLinux agent devices and SSH serverspid, name, action, confirm_database
server_restart_ownerRestart the container or systemd service a process runs in. SSH, Docker, containerd, journald, logind, D-Bus and WECOMMANDER are refused.High risk: needs approval of this exact call unless full trustLinux agent devicesowner_kind (container|service), id
server_timers_listsystemd timers and cron entries, read without root.Read-only: runs directlyLinux agent devices and SSH serverstarget or device_id

Docker

Per daemon: system, or u<uid> for a user's rootless Docker. Never removes or prunes; WECOMMANDER's own containers are never stopped.

ToolWhat it doesRisk and approvalWhereKey arguments
docker_containers_listContainers per daemon with id, name, image, state, status, ports and restart count.Read-only: runs directlyLinux agent devices and SSH serversdaemon
docker_container_logsThe last lines of a container's logs (tail 1–2000, since, at most 256 KiB), secrets masked.Read-only: runs directlyLinux agent devices and SSH serverscontainer, daemon, tail, since
docker_container_actionstart, stop or restart one container.High risk: approval every call unless full trust; never allowlisted; refused on read-only SSH serversLinux agent devices and SSH serverscontainer, action, daemon

Scheduled tasks

WECOMMANDER's own scheduled tasks for the workspace. Changes need the admin role.

ToolWhat it doesRisk and approvalWhereKey arguments
scheduled_tasks_listTasks with target, command (secrets masked), schedule, time zone, enabled, next run and the last run's status.Read-only: runs directlyWorkspacenone
scheduled_task_createCreate a task on an agent device with a cron, interval or one-time schedule.High risk: approval of the exact change unless the device is on full trust; safety net appliesAgent devicesdevice_id, name, command, schedule, timezone, enabled, timeout_sec, notify
scheduled_task_updateChange the given fields of a task, or move it to another agent device.High risk: approval unless full trust; SSH tasks always need approvalWorkspacetask_id and any task field
scheduled_task_deleteDelete a task and its run history.High risk: approval unless full trust; SSH tasks always need approvalWorkspacetask_id
scheduled_task_run_nowRun a task once now, outside its schedule.High risk: approval unless full trust; SSH tasks always need approvalWorkspacetask_id

Desktop Commander-compatible names

Aliases so prompts written for Desktop Commander keep working. They map to the tools above, so roles, approvals, device limits and the audit log apply unchanged. device_id is optional when exactly one device is online.

ToolWhat it doesRisk and approvalWhereKey arguments
read_fileRead a text file; with offset and length a line range; for PDF files, pages (up to 20). Maps to fs_read, fs_read_lines or pdf_read.Read-only: runs directlyAgent devices (Windows, macOS, Linux)path, offset, length
read_multiple_filesRead up to ten files (fs_read_multiple).Read-only: runs directlyAgent devices (Windows, macOS, Linux)paths
write_fileWrite UTF-8 text; mode rewrite (default) or append (fs_write or fs_append).Change inside allowed folders: runs without approval (operator role); refused by read-only devicesAgent devices (Windows, macOS, Linux)path, content, mode
list_directoryList a folder (fs_list).Read-only: runs directlyAgent devices (Windows, macOS, Linux)path
create_directoryCreate a folder with its parents (fs_mkdir).Change inside allowed folders: runs without approval (operator role); refused by read-only devicesAgent devices (Windows, macOS, Linux)path
move_fileMove or rename (fs_move).Change inside allowed folders: runs without approval (operator role); refused by read-only devicesAgent devices (Windows, macOS, Linux)source, destination
get_file_infoFile or folder metadata (fs_stat).Read-only: runs directlyAgent devices (Windows, macOS, Linux)path
edit_blockReplace old_string with new_string: exact match first, then a unique whitespace-tolerant match; expected_replacements must equal the matches. Guarded by the file's SHA-256.Change inside allowed folders: runs without approval (operator role); refused by read-only devicesAgent devices (Windows, macOS, Linux)file_path, old_string, new_string, expected_replacements

Web

The only tool that reaches outside your own machines.

ToolWhat it doesRisk and approvalWhereKey arguments
url_fetchFetch an http(s) URL from the WECOMMANDER gateway and return its text (up to 1 MiB, 15 seconds). Private, loopback and link-local addresses are refused.Read-only: runs directlyGateway (no device)url

Errors the AI may see

ErrorMeaning
approval_requiredA person must approve this exact action; retry the same call after approval.
safety_net_blockedThe command is on the safety net's list; it is refused even with an approval.
run_as_root_unavailableRoot was requested but the device or server no longer allows it; nothing ran as the user instead.
unsupported_for_targetThe tool does not work on this kind of target (for example an SSH server).
connector_offlineThe computer that reaches this SSH server is off or the app is closed.
monthly_tool_call_limitThe Free plan's monthly tool calls are used up; the message says when they reset.
browser_session_requiredThe action (such as changing AI permissions) needs an admin in a browser, never an AI client.