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
- Read-only: runs directly for any member role (viewer and up).
- Change inside allowed folders: runs without a per-call approval for operators and up; the agent's allowed folders and read-only switch still apply. On SSH servers every change needs an approval unless the server's trust says otherwise.
- High risk: the first call returns approval_required with an approval_request_id. A person approves that exact action; the AI then repeats the same call. Exceptions: process_exec commands on the device's allowlist (standard trust), and devices on full trust.
- The safety net refuses catastrophic commands in process_exec, task_start, terminal_input and scheduled task commands on every trust level.
Discovery and workspace
Start here: what the AI can reach and with which permissions.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| devices_list | Enrolled agent devices with online state and each device's trust level, run as, root capability and safety net. | Read-only: runs directly | Workspace | none |
| targets_list | Every 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 directly | Workspace | none |
| app_errors | Recent errors reported by the WECOMMANDER apps of this workspace, newest first, with platform, build, message and stack; user folder names removed. | Read-only: runs directly | Workspace | limit (1–100) |
| get_recent_tool_calls | Paginated, sanitised history of your own recent tool calls on the selected device. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | device_id, limit, offset |
| get_usage_stats | Your tool calls by name over the past 30 days on the selected device. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | device_id |
| policy_info | The agent-enforced allowed folders, limits and switches (commands, file writes, output redaction, system logs). | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | device_id |
System, health and logs
Read the state of a machine.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| system_info | Operating system, host name and basic system information. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | device_id |
| health_snapshot | CPU usage and load, memory and swap, disks, network counters and the top processes by CPU and memory. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | device_id, top (1–20) |
| log_query | Bounded 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 directly | Agent devices; journal on Linux only | device_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.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| fs_list | List a folder. | Read-only: runs directly | Agent devices and SSH servers (Hybrid Access) | path |
| fs_stat | File or folder metadata. | Read-only: runs directly | Agent devices and SSH servers (Hybrid Access) | path |
| fs_read | Read a file as UTF-8 text or base64. | Read-only: runs directly | Agent devices and SSH servers (Hybrid Access) | path, max_bytes |
| fs_read_lines | A page of lines (zero-based offset; negative counts from the end); up to 1000 lines and 256 KiB. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, offset_lines, limit_lines |
| fs_read_multiple | Up to ten files in one call (64 KiB each, 256 KiB total), with per-file errors. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | paths, max_bytes |
| fs_tree | A bounded recursive folder tree, without following symbolic links. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, max_depth, max_entries |
| image_inspect | PNG, JPEG, GIF or WebP dimensions and metadata from the headers only. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path |
Office documents and PDF
Read Word, Excel and PDF files without running macros or loading external resources.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| pdf_read | The text layer of up to 20 PDF pages (start_page 1-based; negative counts from the end). | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, start_page, page_count |
| docx_inspect | Paragraph and table counts of a Word document. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path |
| docx_read_paragraphs | Up to 100 paragraphs as text, including text in tables. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, offset, limit |
| docx_read_table | Up to 50 rows of one table (20 cells per row). | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, table_index, offset_rows, limit_rows |
| xlsx_inspect | The worksheets of an XLSX or XLSM workbook. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path |
| xlsx_read_range | Up to 50 rows by 20 columns of one sheet; formulas are not evaluated. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, sheet, start_row, start_column, row_count, column_count |
| xlsx_find | Search cached cell values (up to 50,000 cells, 30 sheets, 100 matches). | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, query, sheet, case_sensitive, max_results |
| xlsx_write_cells | Write 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 devices | Agent 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.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| fs_write | Write 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 approval | Agent devices and SSH servers (Hybrid Access) | path, content_base64, create_parents, expected_sha256, with_undo |
| fs_append | Append to a file; with_undo keeps a snapshot. | Change inside allowed folders: runs without approval (operator role); refused by read-only devices | Agent devices (Windows, macOS, Linux) | path, content_base64, expected_sha256, with_undo |
| fs_mkdir | Create a folder. | Change inside allowed folders: runs without approval (operator role); refused by read-only devices. On SSH servers: needs approval | Agent devices and SSH servers (Hybrid Access) | path, recursive |
| fs_move | Move 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 approval | Agent devices and SSH servers (Hybrid Access) | source, destination |
| fs_replace | Exact 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 devices | Agent devices (Windows, macOS, Linux) | path, search, replace, replace_all, expected_sha256 |
| fs_delete | Delete 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 trust | Agent devices and SSH servers (Hybrid Access) | path, recursive, expected_sha256, approval_token |
| fs_versions | Up to eight undo snapshots of a file. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path |
| fs_undo | Restore 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 devices | Agent devices (Windows, macOS, Linux) | path, undo_id, expected_sha256 |
Search
Bounded searches inside the allowed folders.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| fs_search | Search file and folder names recursively. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, query, case_sensitive, max_results |
| text_search | Search literal text in UTF-8 files recursively. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, query, case_sensitive, max_results |
| code_search | The same as text_search, named for coding clients. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, query, case_sensitive, max_results |
| start_search | Start an asynchronous file-name or content search (up to 500 matches). | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path, query, search_type (files|content), case_sensitive, start_paused |
| get_more_search_results | A page of a search's results; pending until it completes. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | search_id, offset, length |
| list_searches | Your active and recent searches on the device. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | device_id |
| pause_search | Pause a running search for up to 15 seconds. | Session control: runs directly | Agent devices (Windows, macOS, Linux) | search_id |
| resume_search | Resume a paused search. | Session control: runs directly | Agent devices (Windows, macOS, Linux) | search_id |
| stop_search | Discard a search and its results. | Session control: runs directly | Agent 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.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| process_exec | Run 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 applies | Agent devices and SSH servers (Hybrid Access) | command, cwd, timeout_ms, approval_token |
| process_list | Visible processes (secrets in command lines masked). | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | device_id |
| process_kill | Terminate 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 trust | Agent devices (Windows, macOS, Linux) | pid, approval_token |
Background tasks
Long-running commands that survive AI and gateway disconnects while the agent runs.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| task_start | Start 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 applies | Agent devices (Windows, macOS, Linux) | command, cwd, timeout_ms, approval_token |
| task_status | Status and retained output of a task. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | task_id |
| task_list | Retained tasks, so a reconnected client can find its task ids. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | device_id |
| task_cancel | Cancel a task. | High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trust | Agent devices (Windows, macOS, Linux) | task_id, approval_token |
Interactive terminals
Persistent PTY sessions with up to 1 MiB of retained history.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| terminal_start | Open 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 trust | Agent devices (Windows, macOS, Linux) | shell, cwd, cols, rows, approval_token |
| terminal_input | Type 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 applies | Agent devices (Windows, macOS, Linux) | session_id, data_base64, approval_token |
| terminal_read | Read buffered output. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | session_id, max_bytes |
| terminal_read_page | Read retained history without consuming it, by byte offset. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | session_id, offset_bytes, max_bytes |
| terminal_resize | Resize a terminal. | Session control: runs directly | Agent devices (Windows, macOS, Linux) | session_id, cols, rows |
| terminal_stop | Close a terminal session. | High risk: needs a single-use human approval unless allowlisted (process_exec only, standard trust) or the device is on full trust | Agent devices (Windows, macOS, Linux) | session_id, approval_token |
| terminal_list | Open sessions with process ids and retained output sizes. | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | device_id |
Server management (Linux)
The same fixed scripts as the desktop app's server management screens.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| server_overview | Host 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 directly | Linux agent devices and SSH servers | target or device_id |
| server_disk_usage | The 40 largest folders inside a path (default /) on one disk, plus Docker's usage. | Read-only: runs directly | Linux agent devices and SSH servers | path |
| server_cleanup_scan | What can be freed safely, by category and per Docker daemon, with sizes and the exact command each runs. | Read-only: runs directly | Linux agent devices and SSH servers | target or device_id |
| server_cleanup_run | Run 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 trust | Linux agent devices and SSH servers | ids |
| server_processes | Every process and the zombies grouped by parent, with the owning container or service and whether it is protected. | Read-only: runs directly | Linux agent devices and SSH servers | target or device_id |
| server_process_signal | Send 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 trust | Linux agent devices and SSH servers | pid, name, action, confirm_database |
| server_restart_owner | Restart 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 trust | Linux agent devices | owner_kind (container|service), id |
| server_timers_list | systemd timers and cron entries, read without root. | Read-only: runs directly | Linux agent devices and SSH servers | target 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.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| docker_containers_list | Containers per daemon with id, name, image, state, status, ports and restart count. | Read-only: runs directly | Linux agent devices and SSH servers | daemon |
| docker_container_logs | The last lines of a container's logs (tail 1–2000, since, at most 256 KiB), secrets masked. | Read-only: runs directly | Linux agent devices and SSH servers | container, daemon, tail, since |
| docker_container_action | start, stop or restart one container. | High risk: approval every call unless full trust; never allowlisted; refused on read-only SSH servers | Linux agent devices and SSH servers | container, action, daemon |
Scheduled tasks
WECOMMANDER's own scheduled tasks for the workspace. Changes need the admin role.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| scheduled_tasks_list | Tasks with target, command (secrets masked), schedule, time zone, enabled, next run and the last run's status. | Read-only: runs directly | Workspace | none |
| scheduled_task_create | Create 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 applies | Agent devices | device_id, name, command, schedule, timezone, enabled, timeout_sec, notify |
| scheduled_task_update | Change the given fields of a task, or move it to another agent device. | High risk: approval unless full trust; SSH tasks always need approval | Workspace | task_id and any task field |
| scheduled_task_delete | Delete a task and its run history. | High risk: approval unless full trust; SSH tasks always need approval | Workspace | task_id |
| scheduled_task_run_now | Run a task once now, outside its schedule. | High risk: approval unless full trust; SSH tasks always need approval | Workspace | task_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.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| read_file | Read 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 directly | Agent devices (Windows, macOS, Linux) | path, offset, length |
| read_multiple_files | Read up to ten files (fs_read_multiple). | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | paths |
| write_file | Write 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 devices | Agent devices (Windows, macOS, Linux) | path, content, mode |
| list_directory | List a folder (fs_list). | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path |
| create_directory | Create a folder with its parents (fs_mkdir). | Change inside allowed folders: runs without approval (operator role); refused by read-only devices | Agent devices (Windows, macOS, Linux) | path |
| move_file | Move or rename (fs_move). | Change inside allowed folders: runs without approval (operator role); refused by read-only devices | Agent devices (Windows, macOS, Linux) | source, destination |
| get_file_info | File or folder metadata (fs_stat). | Read-only: runs directly | Agent devices (Windows, macOS, Linux) | path |
| edit_block | Replace 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 devices | Agent devices (Windows, macOS, Linux) | file_path, old_string, new_string, expected_replacements |
Web
The only tool that reaches outside your own machines.
| Tool | What it does | Risk and approval | Where | Key arguments |
|---|---|---|---|---|
| url_fetch | Fetch 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 directly | Gateway (no device) | url |
Errors the AI may see
| Error | Meaning |
|---|---|
| approval_required | A person must approve this exact action; retry the same call after approval. |
| safety_net_blocked | The command is on the safety net's list; it is refused even with an approval. |
| run_as_root_unavailable | Root was requested but the device or server no longer allows it; nothing ran as the user instead. |
| unsupported_for_target | The tool does not work on this kind of target (for example an SSH server). |
| connector_offline | The computer that reaches this SSH server is off or the app is closed. |
| monthly_tool_call_limit | The Free plan's monthly tool calls are used up; the message says when they reset. |
| browser_session_required | The action (such as changing AI permissions) needs an admin in a browser, never an AI client. |
- AI permissions: trust levels, allowed commands, root and the safety net: Set per device and per SSH server what AI may do without asking: strict, standard or full trust (time-limited or not), allowed command patterns, run as root with two keys, the safety net and autonomous mode.
- Approvals: web, e-mail and desktop notifications: How a high-risk AI action waits for a person, where approval requests arrive (dashboard, e-mail, Windows and macOS notifications, Linux Management Center) and what one approval allows.
- Hybrid Access: AI on SSH servers without an agent: Share saved SSH servers with AI clients through WECOMMANDER on your own computer (Windows, macOS, Linux): nothing installed on the server, keys never leave your computer, approvals and AI permissions apply.
- Troubleshooting: Fixes for common problems: agent offline, host key changed, approval not arriving, SSH server unreachable for AI, root not available, commands refused, updates and plan limits.