An SSH MCP server that gives AI agents structured remote-server tools for command execution, file management, log analysis, job control, health checks, audits, transfers, and TLS verification.
Run commands: execute single or batched commands over SSH with sudo support, per-command exit codes, output truncation, timeout, and detached long-running jobs.
Manage files: read text/binary files, write with atomic rename and SHA-256 verification, list directories with globs/recursion, and enforce path security.
Transfer files: upload/download files or directories binary-safely with integrity checks and fallback for legacy SCP devices.
Monitor background jobs: start detached jobs, then check status, read incremental output, list jobs, or kill whole process groups.
Inspect logs: tail multiple logs or globs, and regex-search logs with context, time windows, name-only results, and clear unreadable-file reporting.
Check server health: get snapshots of CPU, memory, disk, containers, ports, services, and recent errors in one round trip.
Audit servers: produce a baseline covering system, disk, memory, network, SSH, Docker, firewall, and updates with CRITICAL/WARNING/OK ratings.
Investigate disk usage: break down disk consumption by largest directories, Docker, journald, caches, and filesystems.
Check services: report systemd unit state, enabled status, and journal tails without misrepresenting non-systemd machines.
Verify TLS certificates: check expiry, SAN coverage, issuer, and renewal hook configuration from the server's perspective.
Manage connections: list, test, reload, stat, and close SSH profiles/connections via the monitor tool.
Protect against destructive commands: block dangerous shell chains and irreversible operations while allowing explicit confirmations.
Provides TLS certificate expiry checking and Let's Encrypt renew hook validation for domains.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SSH MCP Server show disk usage on my staging server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
It uses the OpenSSH client already on your machine: your keys, your ~/.ssh/config, your jump hosts, your agent forwarding. Nothing bundled, nothing to compile, no native bindings.
Works with Claude Code, Codex CLI, Cline, opencode, Gemini CLI, Qwen Code, Hermes and other MCP clients.
Install · Tools · Setup · Security · Roadmap · Docs · Changelog
No global installation required. npx downloads the package on first use:
npx -y @hypnosis/ssh-mcp-serverAdd it to your MCP client — Claude Code, for example — for every project:
claude mcp add ssh -s user \
-e SSH_PROFILES_FILE="$HOME/.claude/ssh-profiles.json" \
-- npx -y @hypnosis/ssh-mcp-serverOr write it by hand — the same server in the config shape most clients share:
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "@hypnosis/ssh-mcp-server"],
"env": {
"SSH_PROFILES_FILE": "~/.claude/ssh-profiles.json"
}
}
}
}Then create ~/.claude/ssh-profiles.json with at least one machine:
{
"profiles": {
"production": {
"host": "server.example.com",
"username": "admin",
"privateKeyPath": "~/.ssh/your_private_key"
}
}
}That is enough to connect.
Codex, opencode, Qwen Code and other clients are covered in Set up the SSH MCP server.
Some clients — Claude Code, for example — can take the whole thing as a plugin instead:
/plugin marketplace add hypnosis/ssh-mcp-server
/plugin install ssh-mcp-server@ssh-mcp-serverThe plugin reads ~/.claude/ssh-profiles.json unless SSH_PROFILES_FILE says otherwise, so
create that file first and the server comes up with your machines already loaded.
Node.js 18+ and a system ssh client on PATH. On Windows, use a key-based profile;
password and passphrase profiles are not currently available.
Prefer a pinned version, offline work, or one less registry check per launch:
npm install -g @hypnosis/ssh-mcp-server, then use ssh-mcp-server as the command instead
of npx.
Related MCP server: cygnus-ssh-mcp
DevOps and SREs who want faster audits, incident checks and routine server work.
Vibe coders and indie builders who ship with an AI assistant and run what they build on their own servers.
Sysadmins and platform engineers who want structured tools instead of an unrestricted raw shell.
Developers and small teams running their own VPS without a dedicated operations team.
Homelab, NAS and router owners whose useful hardware has outlived its modern protocols.
A raw shell gives an AI agent a firehose: repeated commands, ASCII tables and log dumps. It burns tokens turning that noise into a picture of the server — your money.
Purpose-built tools batch routine checks, cap noisy output and return the part that matters. The agent spends less time translating terminal output and gets to the fix sooner.
Structured answers say what was found, what could not be measured and what was truncated. That leaves the agent less room to fill gaps with a hallucination — and gives you fewer bad fixes, calmer deploys and more reliable code.
No bundled SSH implementation, no native bindings, no rebuild per platform. Commands ride the
system ssh client, so your keys, your ~/.ssh/config, your jump hosts and your agent
forwarding all keep working exactly as they do in a terminal. When supported, one shared
multiplexed connection per destination means you authenticate once, not once per command.
Send a file to a router with a modern scp and you get this:
scp app.conf router:/etc/
# scp: subsystem request failed on channel 0Nothing is broken — a current scp speaks the new protocol, and the router does not know it.
In a terminal you now go read a forum thread and come back with an extra flag. Here you do
nothing: the transfer is tried, the refusal is recognized, the old protocol is used instead,
and that machine is remembered so the next file goes straight there.
Fallbacks for older SSH clients and missing tools
Old gear gets a fallback, not a dead end. When a modern feature is missing, the server takes the older road where it can:
Your machine | What you get |
A router or NAS too small for modern file transfer | The file still lands — the old protocol is used automatically |
A server from ten years ago | The workflow still works; it just opens a fresh connection per command instead of reusing one |
A stripped-down image with no way to hash a file | The upload says "could not verify" instead of claiming a match nobody checked |
A box where a tool simply is not installed | The answer says "not measured" — never a zero that reads as "nothing there" |
Built on the official MCP SDK, TypeScript throughout, 2500+ unit tests plus a live suite that runs against real containers rather than mocks.
Situation: A deploy just went out. The server feels slow, and you do not know whether disk, memory, services, containers or errors are to blame.
Question: “Is this box healthy?”
$ uptime
10:42:17 up 18 days, 3:21, 2 users, load average: 0.42, 0.31, 0.28
$ df -hT
Filesystem Type Size Used Avail Use% Mounted on
/dev/sda1 ext4 40G 35G 5.0G 87% /
overlay overlay 40G 35G 5.0G 87% /var/lib/docker/overlay2/...
$ free -h
total used free shared buff/cache available
Mem: 7.7Gi 4.9Gi 612Mi 121Mi 2.2Gi 2.5Gi
$ systemctl --failed
UNIT LOAD ACTIVE SUB DESCRIPTION
● api-worker.service loaded failed failed API background worker
$ docker ps -a
CONTAINER ID IMAGE STATUS PORTS
8e14d0b41c2a api:latest Up 3 minutes 0.0.0.0:8080->8080/tcp
65b894af2430 worker:latest Exited (1) 2 minutes ago
$ ss -tulpn
Netid State Local Address:Port Process
tcp LISTEN 0.0.0.0:22 users:(("sshd",pid=842,fd=3))
tcp LISTEN 0.0.0.0:8080 users:(("docker-proxy",pid=1942,fd=4))
$ journalctl -p err --since -1h | tail -50
Aug 20 10:39:14 prod api-worker[22104]: database connection timed out
Aug 20 10:39:14 prod systemd[1]: api-worker.service: Failed with result 'exit-code'.That is still an abridged result. A complete check needs more commands for CPU, service
states, container counts and recent errors, each with its own output format. Worse, a box
without ss can look like it has zero listeners when the port check never ran.
ssh_snapshot({ "profile": "production" }){
"disk_pct": 87,
"mem_pct": 64,
"cpu_pct": 12,
"load": "0.42 0.31 0.28",
"containers": 7,
"ports": 14,
"services_running": 3,
"recent_errors": 21,
"unavailable": []
}Raw SSH | Structured MCP | Your gain |
Several commands and ASCII tables | Named fields in one result | One call, named fields and fewer round trips |
A missing tool can look like empty output |
| Less guessing and fewer bad fixes |
You sort through disks, services and errors | The problem signals are already surfaced | Faster debugging |
A full ssh_audit_baseline result can be longer than a handful of raw command outputs —
about 1,077 tokens versus 765 in our lab measurement. The saving comes from the complete
workflow, not from making one response shorter.
In a real troubleshooting session, purpose-built tools reduced 49 separate command calls to 4 MCP calls. Every additional call starts another model turn with the accumulated conversation. Prompt caching can reduce the cost of repeated input, but new commands and their output still consume context. Fewer round trips mean fewer tokens across the session, less repeated analysis and a faster path to the answer.
Need the whole picture rather than the pulse? ssh_audit_baseline batches system, disk,
memory, ports, sshd, failed units, Docker, firewall and updates. Findings arrive as
CRITICAL / WARNING / OK; unmeasured sections are named instead of silently reading as zero.
Situation: The API is timing out, but the same message may be in nginx, syslog, journald or an application log you cannot read with your normal user.
Question: “Where did that error come from?”
$ grep -i "timeout" /var/log/nginx/error.log
2026/08/20 10:38:54 [error] upstream timed out while reading response header
$ grep -i "timeout" /var/log/syslog
Aug 20 10:39:14 prod api-worker[22104]: database connection timed out
$ grep -i "timeout" /var/log/app/*.log 2>/dev/null
$ journalctl -u api --since "1 hour ago" | grep -i timeout
Aug 20 10:39:14 prod api[22104]: database connection timed out after 30000msThe third command looks clean, but 2>/dev/null also hid a permission error. "Nothing
matched" and "nothing was read" now look identical. A busy log can also return thousands of
lines and push the rest of the incident out of the agent's context.
ssh_log_search({ "profile": "production",
"path": ["/var/log/nginx/error.log", "/var/log/syslog", "/var/log/app/*.log"],
"query": "timeout", "context": 2, "since": "1h" }){
"matches": 34,
"lines": [
{ "file": "/var/log/nginx/error.log", "line": 4821,
"text": "upstream timed out while reading response header", "context": false },
{ "file": "/var/log/nginx/error.log", "line": 4822,
"text": "client closed connection", "context": true }
],
"files_searched": 6,
"files_unreadable": ["/var/log/app/private"],
"files_skipped": 12,
"files_undated": [],
"limited": false,
"truncated": false
}Raw SSH | Structured MCP | Your gain |
Four searches and four outputs | One search across files and globs | Fewer tokens and round trips |
Permission errors can disappear |
| No false "logs are clean" conclusion |
Output can grow without a useful ceiling |
| Safer decisions from partial results |
since uses the server's clock, namesOnly: true returns only matching paths, and
ssh_log_tail reads the last N lines from several logs in one call.
Situation: You need to replace an nginx config on a live server. A dropped connection, wrong mode or unchecked copy could leave the service with a broken file.
Question: “Can I replace this config without leaving a partial file?”
$ sudo sh -c 'cat > /etc/nginx/conf.d/api.conf' <<'EOF'
server {
listen 80;
location / { proxy_pass http://127.0.0.1:8080; }
}
EOF
$ echo $?
0Exit code zero says the shell finished. It does not prove which bytes landed, and >
truncated the old file before the first byte of the new one arrived. If the connection drops
mid-write, the service is left with a partial config.
ssh_file_write({ "profile": "production",
"files": [{ "path": "/etc/nginx/conf.d/api.conf",
"content": "server {\n listen 80;\n location / { proxy_pass http://127.0.0.1:8080; }\n}\n",
"mode": "644", "sudo": true, "verify": true }] }){
"files": [{ "path": "/etc/nginx/conf.d/api.conf", "written": true,
"verified": "verified", "reason": null, "bytes": 79 }]
}Raw SSH | Structured MCP | Your gain |
The target is truncated before the copy completes | A complete temp file replaces it with one rename | No half-written config |
Exit code only | Bytes and verification outcome are named | You know what actually landed |
Permissions live inside shell text |
| Predictable ownership and fewer quoting mistakes |
verified has three honest outcomes: verified, unavailable when the server has no hash
tool, and skipped when verification was not requested. For reads, ssh_file_read accepts a
list of paths; ssh_file_list handles globs, recursion, sizes and modes.
Situation: A deploy is ready, but nginx syntax, service state and recent errors must all be checked before traffic moves. One failed check should not disappear inside a combined dump.
Question: “Did every preflight check pass?”
$ ssh admin@server.example.com 'sudo nginx -t'
nginx: configuration file /etc/nginx/nginx.conf test is successful
$ ssh admin@server.example.com 'sudo systemctl is-active nginx'
active
$ ssh admin@server.example.com 'sudo tail -5 /var/log/nginx/error.log'
2026/08/20 10:38:54 [error] upstream timed out while reading response headerThree connections return three unrelated outputs. If the commands are joined with ;, the
shell reports only the last exit code; if they are joined with &&, later checks disappear
after the first failure.
ssh_exec({ "profile": "production",
"command": ["nginx -t", "systemctl is-active nginx",
"tail -5 /var/log/nginx/error.log"],
"sudo": true }){
"commands": [
{ "command": "nginx -t", "exit_code": 0, "truncated": false, "clipped_bytes": 0,
"stdout": "", "stderr": "nginx: configuration file /etc/nginx/nginx.conf test is successful\n" },
{ "command": "systemctl is-active nginx", "exit_code": 0, "truncated": false,
"clipped_bytes": 0, "stdout": "active\n", "stderr": "" },
{ "command": "tail -5 /var/log/nginx/error.log", "exit_code": 0, "truncated": false,
"clipped_bytes": 0, "stdout": "2026/08/21 09:14:02 [error] upstream timed out\n", "stderr": "" }
],
"job_id": null
}Raw SSH | Structured MCP | Your gain |
Three calls and unrelated outputs | One ordered command list | Fewer round trips |
A combined shell can hide intermediate status | Every command keeps its own | No missed failed check |
|
| Fewer quoting mistakes |
The destructive-command guard checks the complete list before the first command runs. If one entry is refused, every other entry is marked as not run and nothing is sent to the server.
Each command carries its own stdout and stderr. A command that ran and printed nothing
has an empty string; a command that never ran has no such field at all, so the two cannot be
confused. Output over 128 KB per command keeps both ends — the head for tables, the tail for
logs — with a seam in between naming the amount, and clipped_bytes says how much was cut.
Cutting happens on byte boundaries and steps back to the edge of a character, so a clipped
answer never carries a replacement mark.
sudo reaches the server without a terminal: the profile's answer is handed to sudo on
standard input. Which secret that is comes from sudoPassword when the profile names one and
from password otherwise — a profile that logs in by key has no login password at all, and
where a machine keeps the two apart the login one is the wrong answer. Where there is nothing
to answer with, the reply says so and names the ways out, instead of leaving sudo's own advice
about -S and askpass helpers. A command that reads its own standard input is never given the
password, which would otherwise end up mixed into the data.
Situation: A backup or migration will run longer than the agent session. The connection may close, but you still need its state, output and exit code later.
Question: “Will this job survive the conversation?”
$ ssh admin@server.example.com 'pg_dump app | gzip > /srv/backups/app.sql.gz'
client_loop: send disconnect: Broken pipeThe terminal is gone. You now have to reconnect, find the process, inspect the target file and guess whether the backup finished or stopped halfway.
ssh_exec({ "profile": "production",
"command": "pg_dump app | gzip > /srv/backups/app.sql.gz",
"detach": true }){
"commands": [{
"command": "pg_dump app | gzip > /srv/backups/app.sql.gz",
"exit_code": null,
"truncated": false,
"timed_out": false,
"blocked": false,
"blocked_reason": null,
"not_run": false,
"warning": null
}],
"job_id": "mst0f2q1-9ab3c4d5"
}Raw SSH | Structured MCP | Your gain |
The job is tied to one SSH session | The remote job has a persistent id | Safe disconnects and restarts |
Reconnecting means searching processes and files | Status and exit code have named states | No guessing whether it finished |
Reading output again repeats old text | Output continues from a byte offset | Lower token use on long jobs |
Job state lives on the remote disk, not in this server's memory. ssh_job_status distinguishes
running, finished and lost; ssh_job_output continues from the last byte offset; and
ssh_job_kill signals the whole process group instead of only its shell.
Situation: A current OpenSSH client tries SFTP, but the router or NAS only understands the classic scp protocol. The file must still arrive intact and replace its target safely.
Question: “Can this old device still receive a verified file?”
$ scp app.conf operator@router:/etc/app.conf
subsystem request failed on channel 0
scp: Connection closedThe usual next step is to remember the legacy flag, retry the copy and then run a separate hash command—if the device has a hash tool at all.
ssh_upload({ "profile": "router", "local_path": "./app.conf",
"remote_path": "/etc/app.conf", "sudo": true,
"mode": "644", "owner": "root:root", "verify": true }){
"files": [{
"path": "/etc/app.conf",
"written": true,
"verified": "verified",
"reason": null,
"bytes": 1284
}]
}Raw SSH | Structured MCP | Your gain |
Modern SFTP mode stops at the first error | Classic scp fallback is automatic and remembered | Old gear still works |
A successful copy does not prove integrity | SHA-256 verification has a named outcome | Corruption is not mistaken for success |
Direct replacement can leave a partial target | A temp file is moved into place after transfer | The working file survives interruptions |
If the device has neither sha256sum nor openssl, the result says unavailable and names
the reason instead of reporting a false match. Whole directories use recursive: true and
verify their hashes in one batch.
The guard runs locally, before a command reaches SSH. It separates operations that can be recovered from those that destroy the container holding the data, and it checks command order inside chains and batches.
A safe backup-and-replace sequence:
cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old && rm -rf /srv/appThe same operations in the wrong order:
rm -rf /srv/app && cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old
# REFUSED before the first command runsThe shell would delete the directory and only then discover that the backup source is gone.
The guard sees that later steps read a target already destroyed by an earlier step, so the
whole call stays on your machine. The same check catches
dropdb app && pg_dump app > backup.sql.
Refused — the container itself | Only warned — its contents |
|
|
|
|
| editing one job |
|
|
|
|
docker compose down -v is refused because -v removes named Docker volumes, including a database
volume. Without -v, stopping the services is not treated as the same irreversible action.
Recursive deletion of the filesystem root, a home directory or system trees such as /etc,
/var and /usr is also refused, including when a symlink leads there. An unresolved target
such as rm -rf "$DIR"/* is refused too: "could not check" is not treated as "safe".
A command that finds its target instead of naming it is not sent. The server expands it and answers with what stands behind the target:
docker kill $(docker ps -q --filter ancestor=web)
# BLOCKED — would stop:
# edge — web:latest, Up 34 days, 0.0.0.0:8443->8443/tcpFor a process the answer adds the signs that it is in use: how long it has been running,
which ports it accepts connections on, how many connections it is carrying. Named targets
cost nothing extra and go through in silence — docker kill web-1, kill 4871,
systemctl stop app.
To go ahead, name what is being stopped. The names are checked against what the command actually reaches, so a mask that has drifted onto something else is refused rather than confirmed:
docker kill $(docker ps -q --filter ancestor=web) # CONFIRMED-KILL: edgeA pattern over command lines is a case of its own. It matches the very command that carries it, so the shell running it is signalled before the target and the reply breaks off in the middle. Such a strike is not confirmed but rewritten — by number, or with one character written as a class so the pattern stops matching itself:
pkill -f relay
# BLOCKED — two ways through:
# kill 4871
# pkill -f '[r]elay' # CONFIRMED-KILL: 4871Three outcomes stay apart: targets found, the expansion reached nothing, and nothing to ask with — no engine on the machine, a clipped answer, a connection that failed. The last two are refusals as well: not knowing is not a reason to proceed.
Nothing is forbidden permanently. Add # CONFIRMED-DESTRUCTIVE to a reviewed command and it
is allowed through. When the guard refuses one entry in a batch, the complete batch stops
before execution, so the server is never left after a half-run operation.
The guard works within a single call. It cannot connect a delete in one invocation with a read in the next, or reason about tools it does not recognize. It is a seatbelt, not a policy engine: recoverable operations remain your call. Path restrictions and quoting rules are documented in docs/security.md.
18 SSH MCP tools for server operations. Full parameters and examples live in docs/tools.md.
Tool | What it does |
| Run one command or a batch, with the destructive-command guard and optional detach |
| Read one or several files, text or binary |
| Write files with atomic rename and optional SHA-256 verification |
| List a directory, with optional glob and recursion |
| Upload a file or directory over SSH, binary-safe with integrity checks; a directory replaces the target or merges into it |
| Download a file or directory over SSH, binary-safe with integrity checks |
| State of a background job: running, finished, or lost |
| Read accumulated output from a byte offset |
| List jobs, sweeping finished ones past their TTL |
| Signal a job's whole process group |
| Last N lines of one or several logs, glob supported; a container by name |
| Pattern search across logs, or through a container's log |
| One-shot health snapshot: services, resources, Docker, network, errors |
| Transport control: stats, reload, test, list, close |
| System, disk, memory, network, ssh, services, Docker, firewall, updates |
| Certificate expiry, SAN, chain and renewal hook for a domain |
| Where the disk went: |
|
|
Standard MCP annotations tell clients which tools are read-only, destructive, idempotent or open-world. See the full table.
Commands, file reads and writes, directory listings — the ordinary work on a machine, each answer already parsed.
Slow work is detached and followed instead of waited for: every look says how far it got.
Logs of files and containers, and a one-shot picture of the machine, with output capped so a tail does not eat the context window.
Binary-safe transfers with integrity checks. Details in docs/transfer.md.
For binaries and large files use
ssh_upload/ssh_download— base64 chunks and heredocs are not binary-safe or atomic.
Read-only and batched into one round trip. Details in docs/audit.md.
Windows uses compatibility mode automatically. When connection multiplexing is unavailable, the server switches to one connection per command. The same tools remain available over key-based SSH — no separate setup or Windows-specific implementation.
The destructive-command guard is covered in Destructive command protection for AI agents.
Run the package from Install in 30 seconds first, then create a profile file.
Put it wherever you like — next to your agent's own config is the usual choice. The examples below use ~/.claude/ssh-profiles.json; for other agents swap the directory (~/.codex/, ~/.qwen/, ~/.config/opencode/):
{
"profiles": {
"production": {
"host": "server.example.com",
"username": "admin",
"port": 22,
"privateKeyPath": "~/.ssh/your_private_key"
}
}
}Choose an SSH profile explicitly
There is no profile the server falls back to: each one is a different machine, and a command sent to the wrong machine is not something an error message can undo afterwards. Ask without a name and the answer lists the names to choose from:
ssh_exec({ command: "uptime" })
→ No profile specified. Name one explicitly: productionA profile the server cannot use for SSH — no host, no username, or mode: "local" — is skipped without complaint, and fields it does not recognize are left alone, so the file can be shared with other tools. A profile with a broken field is a different case: it is named along with the field and the value, and its healthy neighbors keep working.
Each profile optionally takes a pathSecurity block that whitelists or blacklists the paths file tools may touch — see docs/security.md.
A profile that logs in by key but needs sudo on the far side takes a sudoPassword — the secret sudo is answered with, which on many machines is not the login password. Keep it in the secrets file rather than here.
Prefer keys. If a password or encrypted-key passphrase is unavoidable, keep it in a separate secrets file, never in the profile itself:
{
"secretsFile": "~/.config/ssh-mcp/secrets.json",
"profiles": {
"production": {
"host": "server.example.com",
"username": "admin"
}
}
}The secrets file is keyed by profile name — see secrets.json.example:
{
"production": { "password": "..." },
"buildbox": { "sudoPassword": "..." }
}sudoPassword is what sudo is answered with on that machine. A profile logging in by key
has no login password to offer, and where the two differ the login one is the wrong answer;
without it, password is used.
The secrets file must be readable only by you (chmod 600). Relative paths resolve from the
profiles file; secrets stay out of argv and are masked in logs. See
credentials security.
Choose the client you use and point it at the same profiles file.
Claude Code
One command; -s user makes the server available in every project:
claude mcp add ssh -s user \
-e SSH_PROFILES_FILE="$HOME/.claude/ssh-profiles.json" \
-- npx -y @hypnosis/ssh-mcp-serverCodex CLI
codex mcp add ssh \
--env SSH_PROFILES_FILE="$HOME/.codex/ssh-profiles.json" \
-- npx -y @hypnosis/ssh-mcp-serveropencode
Put it in ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ssh": {
"type": "local",
"command": ["npx", "-y", "@hypnosis/ssh-mcp-server"],
"enabled": true,
"environment": {
"SSH_PROFILES_FILE": "~/.config/opencode/ssh-profiles.json"
}
}
}
}Qwen Code
One command, same as the others:
qwen mcp add ssh \
-e SSH_PROFILES_FILE="$HOME/.qwen/ssh-profiles.json" \
npx -y @hypnosis/ssh-mcp-serverOther MCP clients
Gemini CLI, Hermes, Cline, an editor plugin or your own agent work the same way. All they need is a command to run and one environment variable.
Restart the client, then run ssh_monitor({ action: "list" }) to confirm the profile loaded.
Variable | What it does | Default |
| Path to the profiles JSON — required | — |
|
|
|
| Fallback, used only when |
|
| Timestamps in log lines |
|
| Seconds a shared connection stays alive after the last command; |
|
| Where control sockets live |
|
| Profile cache TTL, ms |
|
| Reload the profiles file when it changes |
|
The shared connection outlives this process on purpose: closing it on exit would cut the channel another window on the same machine is using.
Every limit tells you the way around it. A tool that cannot do something says so and
names ssh_exec, which runs commands on the machine directly — an unsupported log driver,
a utility the machine does not have, an engine this server does not speak. You do not have
to know in advance where the tools end: the refusal says it, at the moment it matters.
Three refusals deliberately stay silent about the shell, because there it is the wrong
answer: a path your profile forbids (walking around your own rule is not a fix), a
malformed call (the fix is in the call), and a refusal from ssh_exec itself.
Cancellation: a cancelled call now stops the command on the server too, sent as a second call over the same connection. Where the server has no /proc, the command is found through ps instead. FreeBSD is not verified: correct behaviour there is not guaranteed. File transfers and ssh_snapshot do not take cancellation at all.
Atomic writes: BSD and macOS cannot pre-check cross-filesystem renames.
Full test run against macOS SSH hosts
End-to-end compatibility run on Windows
Multi-host audits — compare health across several SSH profiles in one call
Import profiles from the existing ~/.ssh/config
Resumable transfers for large files and unstable connections
Remote operation timeline — commands, transfers and guard decisions in one audit trail
Ready-made SSH troubleshooting playbooks
Container logs without dropping to the shell — DONE: ssh_log_tail and ssh_log_search take a container name, ask docker where it writes and read that file with the same machinery as any other log
A refusal that leaves you stuck — DONE: every limit now names ssh_exec as the way through, so hitting the edge of a tool costs one sentence instead of a guessing game
Answers that reach the model — DONE: command output, matched log lines, machine names and snapshot sections travel in the fields, not only in the text
Smaller MCP tool schemas — DONE: the tool list got 10% lighter, and a detached job now shows the last lines it wrote instead of being polled blind
Long work under root — DONE: a detached job runs with sudo and is followed as root, and a key-only profile answers sudo with its own sudoPassword
npm install
npm run build # tsc
npx tsc --noEmit # types, plus dead declarations
npm run test:unit # unit tests
npm run lab:up # start the two test containers
npm run test:live # live suite against those containersThe live suite runs against real containers — one BusyBox, one coreutils — because the two disagree quietly, and a mock agrees with whoever wrote it. See docs/architecture.md for the layout.
If you like the tool, give it a star on GitHub — it helps more people discover the project.
Issues and pull requests are welcome at github.com/hypnosis/ssh-mcp-server.
MIT — see LICENSE.
Reports how a machine is set up: sshd, firewall, pending updates, failed services, docker, listening ports and disk, each section marked CRITICAL, WARNING or OK. Reads only, in one round trip instead of a dozen commands. For load and health at this moment rather than settings, use ssh_snapshot.
| Name | Required | Description | Default |
|---|---|---|---|
| compact | No | Trim the long sections. false = whole, much larger answer. Default: true | |
| include | No | system, disk, mem, net, ssh, services, docker, firewall, updates. Default: all | |
| profile | Yes | Machine name. | |
| include_sudo_sections | No | Run the sections that need root as root: sshd -T for ssh, ufw and iptables rules for firewall. Without it those sections name what they could not read instead of guessing. Default: false |
| Name | Required | Description |
|---|---|---|
| os | No | |
| net | No | |
| ssh | No | |
| disk | No | |
| load | No | |
| docker | No | |
| kernel | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
| memory | No | |
| uptime | No | |
| updates | No | |
| date_utc | No | |
| firewall | No | |
| hostname | No | |
| services | No | |
| red_flags | No | |
| unavailable | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, and the description reinforces this with 'Reads only'. It adds useful behavioral context beyond the annotation by stating that sections are marked CRITICAL/WARNING/OK and that it replaces 'a dozen commands' in one round trip. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the first defines purpose and output shape, the second states safety and efficiency, and the third routes to the sibling tool. The most important scoping information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only audit tool, the description covers what it reports, how the output is categorized, why it is efficient, and which sibling to use in the alternate use case. Combined with full parameter documentation and an output schema, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every parameter documented including defaults and allowed values. The tool description contributes high-level context but does not need to compensate for missing parameter docs, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Reports how a machine is set up', then enumerates exact domains (sshd, firewall, updates, services, docker, ports, disk) and the severity marking scheme. It also distinguishes itself from ssh_snapshot, so an agent can tell it apart from the closest sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: 'For load and health at this moment rather than settings, use ssh_snapshot.' It also frames the tool as a one-round-trip setup audit, making the intended use case clear without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds what filled a disk: free space per filesystem, the largest directories under each path given, and what docker, journald and package caches hold. Reads only, nothing is deleted. For how full the disks are at all, ssh_snapshot answers in one line.
| Name | Required | Description | Default |
|---|---|---|---|
| sudo | No | Read as root. Straight away for places a plain user cannot read (/root, /var/lib/docker); otherwise retry with true when the answer names what it could not read. Default: false The cache section then reads root's home, not the profile user's. | |
| paths | No | Where to look. Naming the suspect beats walking the whole filesystem. Default: ["/"] | |
| top_n | No | Largest directories named per path. Default: 20 | |
| profile | Yes | Machine name. |
| Name | Required | Description |
|---|---|---|
| cache | No | |
| docker | No | |
| largest | No | |
| var_log | No | |
| journald | No | |
| unreadable | No | Not looked into: the sizes above leave these out |
| filesystems | No | |
| unavailable | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this with 'Reads only, nothing is deleted.' It adds useful context about what areas are inspected (docker, journald, package caches) without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences. The first explains scope and read-only behavior, and the second routes to the alternative for a different need. There is no filler or repeated schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich input schema, an output schema, and a readOnlyHint annotation, the description covers what an agent needs: what it inspects, that it is safe, and how it relates to ssh_snapshot. No critical behavioral or selection information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema, but it does relate the tool's purpose to the 'paths' concept. It neither improves nor harms parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('Finds what filled a disk') and enumerates the concrete outputs: free space per filesystem, largest directories per path, and cache contents. It also differentiates itself from ssh_snapshot by framing this as the detailed breakdown versus the one-line fullness answer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear alternative and selection rule: use ssh_snapshot when only overall disk fullness is needed, and this tool when a breakdown is required. It could be slightly more explicit about when not to use the tool, but the guidance is strong enough for an agent to make the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copies a file or directory from a server to this machine, checked by sha256 on both sides. To read a text file rather than keep it, ssh_file_read skips the disk.
| Name | Required | Description | Default |
|---|---|---|---|
| sudo | No | For /root and the like. A root copy stages in /tmp, is fetched and removed — the machine needs room. Default: false | |
| verify | No | sha256 on both sides, per file. "unavailable" = no sha256 on the machine = delivered, not broken. "mismatched" fails the call and replaces nothing. Default: true | |
| profile | Yes | Machine name. | |
| timeout | No | Milliseconds. No ceiling by default — a transfer runs as long as it takes. | |
| recursive | No | Only to force it — a directory is recognised on its own. | |
| local_path | Yes | Where it lands on this machine. | |
| remote_path | Yes | What to fetch from the server. |
| Name | Required | Description |
|---|---|---|
| files | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint and destructiveHint, and the description adds meaningful behavioral detail: 'checked by sha256 on both sides.' This goes beyond the annotations by explaining the verification mechanism. It does not explicitly state that an existing local_path may be overwritten, but the destructiveHint annotation covers the general risk, and the schema's verify parameter adds mismatch semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant wording. The core action and verification detail are front-loaded, and the sibling alternative follows in a clearly conditional form. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, output schema, and annotations, the description is complete enough for an agent to know what the tool does, when to use it, and when not to. It covers direction, verification, and the key sibling alternative, with no missing information necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all seven parameters in detail. The description adds no parameter-level meaning beyond the schema; it only restates the overall transfer and verification behavior. A baseline of 3 is appropriate since the schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Copies a file or directory from a server to this machine.' This clearly identifies the tool's direction and purpose. It also differentiates from ssh_file_read by noting the alternative is for reading text without keeping a copy, and the title 'Download from a server' reinforces the intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides an alternative and a usage condition: 'To read a text file rather than keep it, ssh_file_read skips the disk.' This tells an agent when to prefer a sibling tool instead. The copy direction is unambiguous, so there is no confusion with ssh_upload.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs one command or a list of them on a server, each with its own exit code, stdout and stderr. Work measured in minutes belongs in detach, not in a longer timeout. Reach for it last — files, logs, transfers, health and jobs each have a tool that batches the round trips and parses the answer.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory to start in, detached jobs included. Cannot be entered -> the command stops, it does not run elsewhere. | |
| sudo | No | Execute command(s) with sudo. Default: false | |
| detach | No | Background job on the server: returns an id at once, outlives this call, timeout does not apply. Follow with ssh_job_status / ssh_job_output, stop with ssh_job_kill. One command. With sudo the job runs as root and every later call follows it as root, provided the profile has a password or sudo needs none. Default: false | |
| command | Yes | One command, or a list: ["hostname", "whoami"]. Each runs in its own shell — no shared variable, no shared cd; cwd applies to all. A non-zero exit does not stop the list. | |
| profile | Yes | Machine name. | |
| timeout | No | Milliseconds, per command in a list, not for the whole list; default 30000. Work measured in minutes -> detach, not a bigger number. |
| Name | Required | Description |
|---|---|---|
| job_id | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
| commands | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds behavior: each command returns its own exit code, stdout, and stderr, and long-running work should be detached rather than given a bigger timeout. It doesn't fully warn about the arbitrary-command risk, but the annotation and phrasing imply raw execution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences carry both the core behavior and the key usage caveat. Every clause earns its place, and the most important routing guidance comes second but remains succinct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The combination of a rich schema, output schema, and a description that covers command granularity and tool routing gives an agent enough to invoke this correctly. It does not name the exact sibling tools, but the categories are identifiable from the sibling list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains every parameter. The description reinforces the detach-vs-timeout tradeoff at a high level, but adds no new parameter-specific meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: running one command or a list on a server, with per-command exit code, stdout, and stderr. It also differentiates from specialized siblings by saying files, logs, transfers, health, and jobs each have their own tool, making this the raw fallback.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not-to-use guidance: work measured in minutes belongs in detach, not a longer timeout. It also tells the agent to prefer category-specific tools because they batch round trips and parse answers, which is clear routing advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists a directory on a server: every entry with its size, mode, owner and modification time, as fields. A directory it was not allowed to enter is named rather than left out, and a listing cut short by the output limit says so. To see what is inside a file, use ssh_file_read.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Directory to list. | |
| sudo | No | List as root, for directories the profile user cannot open. Default: false | |
| pattern | No | Glob matched on the machine: "*.conf". Without it every entry comes back. | |
| profile | Yes | Machine name. | |
| recursive | No | Descend into subdirectories. A deep tree is cut at the output limit and says so. Default: false |
| Name | Required | Description |
|---|---|---|
| path | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
| entries | No | |
| truncated | No | The output limit cut the answer: the directory holds more than entries lists. |
| unreadable | No | Directories nobody was allowed to enter. Their contents are missing from entries, and a list short by the one that mattered looks complete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, it discloses useful behavioral edge cases: unreadable directories are named rather than silently omitted, and listings truncated by the output limit are explicitly flagged. This gives the agent accurate expectations for permission failures and large listings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no filler: core purpose first, then key behavioral guarantees, then the routing note to ssh_file_read. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a readOnlyHint, 100% schema parameter coverage, and an output schema present, the description covers the remaining contextual needs: result contents, error behavior, truncation signaling, and the relationship to the closest sibling. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents all five parameters. The description adds context about output fields and truncation but not new parameter-level semantics, matching the baseline for fully documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Lists a directory on a server' and names the returned fields (size, mode, owner, modification time). It distinguishes itself from ssh_file_read by explicitly directing file-content needs to that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the tool's use case (listing directories) and provides an explicit alternative for the adjacent case ('To see what is inside a file, use ssh_file_read'). No ambiguity remains about which sibling to pick for file-content access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads text files from a server, several of them in one call. A file it could not read is named with the reason, never returned empty or cut short as if that were the content. To look for something inside logs rather than read them, ssh_log_search greps on the server.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | One path, or a list: ["/etc/hosts", "/etc/resolv.conf"]. An unreadable file costs the list nothing — the others still come back. | |
| sudo | No | Read as root, for files the profile user cannot open. Default: false | |
| binary | No | Fetch over the transport, not the command channel; answer in base64. The safe way for non-text, implies encoding=base64. Default: false | |
| profile | Yes | Machine name. | |
| encoding | No | base64 keeps non-text bytes intact but still goes through the command channel and its size limit. Real binary -> binary below. Default: utf8 | utf8 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which the description does not contradict. The description adds meaningful behavioral context beyond annotations: unreadable files are reported with the reason, never returned as empty or truncated content, and multiple files can be read in one call. These are useful operational details not captured by the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The primary purpose and batch capability are front-loaded, followed by error behavior and an alternative tool reference. Every sentence earns its place and the structure is clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich schema that documents all parameters, the description covers the core behavior (batch read, error handling) and names an alternative. Since there is no output schema, the error-behavior note partially clarifies return semantics, though the exact response structure isn't specified. For a read-only tool, this is adequate and nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — every parameter (path, sudo, binary, profile, encoding) has a detailed schema description with defaults and enums where applicable. The tool description itself adds no additional parameter semantics beyond the schema, so this dimension sits at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb ('reads') and resource ('text files from a server') and highlights the batch capability ('several of them in one call'). It explicitly distinguishes itself from ssh_log_search, but does not address other siblings like ssh_file_list or ssh_file_write, so differentiation is partial.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit alternative: 'To look for something inside logs rather than read them, ssh_log_search greps on the server.' This is clear when-not-to-use guidance for one specific scenario, but it does not mention when to use ssh_file_list or other file tools, so coverage is limited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes text files on a server, several in one call, each with its own path, permissions, owner and sudo. A file is replaced whole and never appears half-written; there is no append. For something that already exists on this machine, use ssh_upload.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | One file, or a list — mode and sudo decided per file, not per call. | |
| profile | Yes | Machine name. |
| Name | Required | Description |
|---|---|---|
| files | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotent and destructive hints, the description discloses that files are replaced whole, atomically, and never appended to. This adds useful behavioral context that the annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all high-signal: the core action, the atomic/replace behavior, and the sibling alternative. No filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, annotations, and output schema, the description covers the essential behavioral semantics and alternative routing. Nothing critical is missing for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains each parameter thoroughly. The description contributes the multi-file and per-file ownership/sudo framing, but most parameter-level meaning is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: writes files on a server. It also differentiates itself from the closest sibling by saying anything already on this machine should use ssh_upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names ssh_upload as the alternative for files that already exist locally, and clarifies the tool supports multiple files in one call. The no-append note also sets an important boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stops a detached job and everything it started — the signal reaches the whole process group. A job that had already finished is reported as gone, not as a refusal.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Job id returned by ssh_exec with detach: true. A job started with sudo is reached as root from the id alone — nothing extra to pass. | |
| signal | No | KILL only when TERM was already ignored. | TERM |
| profile | Yes | Machine name. |
| Name | Required | Description |
|---|---|---|
| id | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
| reason | No | |
| signal | No | What was actually sent, which is not always what was asked for. |
| outcome | No | signalled — the signal reached the process group of the job; gone — the job had already ended, so there was nothing to stop; nopid — the job recorded no pid, so there was nothing to signal; missing — the server knows no job under this id; no-answer — the server did not answer the stop request, so the job state is unknown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint and idempotentHint. The description adds valuable context: the signal reaches the whole process group, and already-finished jobs are reported as 'gone' rather than a refusal. This goes beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the primary action and then clarify an edge case. No redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a destructive operation with an output schema. It explains the scope of destruction (process group) and the idempotent edge case. Combined with schema documentation for parameters and annotation hints, an agent has what it needs to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions, so baseline is 3. The tool description itself does not add any parameter-specific meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Stops), resource (detached job), and clarifies it reaches the entire process group. Distinguishes from sibling tools like ssh_job_list and ssh_job_status which are non-destructive. Also clarifies behavior for already-finished jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for stopping detached background jobs, but does not explicitly mention alternatives or conditions when not to use. It clarifies that it targets detached jobs, giving scope, but lacks explicit when-not guidance or reference to alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the detached jobs on a machine with their state, jobs started with sudo included — for when an id was not kept. Ids and states only; for what a job printed, use ssh_job_output.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | Yes | Machine name. |
| Name | Required | Description |
|---|---|---|
| jobs | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral detail beyond that: it lists detached jobs including sudo-started ones, and clarifies that only IDs and states are returned. This goes beyond the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core purpose is front-loaded, followed by a scope caveat and a pointer to an alternative. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only tool with an output schema, the description is complete. It explains scope, inclusion of sudo jobs, return content, and when to use it, while relying on annotations and the output schema for the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because the only parameter, 'profile', is documented as 'Machine name.' The description does not add parameter-level meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Lists') and resource ('detached jobs on a machine with their state'), and adds a distinguishing constraint ('jobs started with sudo included'). It also explicitly differentiates itself from ssh_job_output by limiting scope to 'Ids and states only', so an agent can select it correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'for when an id was not kept'. It also names the alternative for related needs: 'for what a job printed, use ssh_job_output'. This directly helps an agent choose between sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns what a detached job has written so far, stdout and stderr together, from a byte offset you choose. For whether the job is still running rather than what it printed, ssh_job_status answers in one line.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Job id returned by ssh_exec with detach: true. A job started with sudo is reached as root from the id alone — nothing extra to pass. | |
| offset | No | Byte offset to read from; the answer names the next one. | |
| profile | Yes | Machine name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which covers safety, and the description adds meaningful behavioral context: reads only output produced 'so far' (non-blocking), merges stdout and stderr, and supports reading from a chosen byte offset with the next offset returned. This goes beyond annotation data without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry the full purpose, the key behavioral detail, and the alternative-tool routing. The most important information is front-loaded, and there is no filler or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only streaming tool with a complete schema, the description is largely sufficient: it conveys non-blocking behavior, combined streams, byte-offset seeking, and the cursor semantics. There is no output schema, so a bit more detail about the exact return shape would push this to 5, but nothing essential to invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The tool description itself does not add new parameter-level meaning beyond what the schema says; it merely restates the offset concept. This meets the baseline for full schema coverage but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Returns what a detached job has written so far', and clarifies that stdout and stderr are combined. It also distinguishes this from ssh_job_status by explicitly contrasting output content with run-state. This leaves no ambiguity about the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives clear routing guidance: if an agent cares whether the job is still running, use ssh_job_status instead. This is an explicit condition that selects between two closely related siblings, which is exactly what an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports the state of a detached job, with the last lines it wrote so you can see where it got to. lost means no exit code was left behind, not that the work failed — ssh_job_output still has the output.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Job id returned by ssh_exec with detach: true. A job started with sudo is reached as root from the id alone — nothing extra to pass. | |
| profile | Yes | Machine name. |
| Name | Required | Description |
|---|---|---|
| jobs | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, so the description adds value by explaining the 'lost' status semantics and clarifying that 'lost' does not mean the work failed. It also discloses that the output remains available via ssh_job_output, which is useful behavioral context beyond what the annotations state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences convey the core purpose, the extra output detail, and the important 'lost' edge-case semantics. Every phrase carries meaning, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only status tool with complete schema descriptions and an output schema present, the description covers all essential context. The 'lost' clarification removes a likely source of confusion, and the readOnlyHint addresses safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter coverage with descriptive text for both 'id' and 'profile', including the note about sudo. The tool description itself adds no additional parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Reports') and a specific resource ('the state of a detached job'), and also states it includes the last lines written for progress visibility. This distinguishes it from sibling tools like ssh_job_output (which retrieves full output) and ssh_job_list (which lists jobs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear when to use this tool: to check the state of a detached job and see where it got to via its last lines. It also gives an implicit when-not by pointing to ssh_job_output for cases where the job is 'lost' but output still exists. It does not explicitly contrast with ssh_job_list, but the single-job framing is enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Greps log files on the server and returns the matching lines with their paths, or the paths alone when line bodies are not wanted. An empty answer means no match, never a failed search — files that could not be read are listed apart. For the tail of a file rather than a search through it, ssh_log_tail is cheaper. A container is searched by name instead of by path.
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | Which end maxMatches keeps: "end" newest (scans the whole file), "start" oldest (stops reading at the cap). Default: end | end |
| path | No | One path, a list, or a glob in the file name: "/var/log/*.log". Expanded by the server's find, not a shell — a name with a space or a newline stays one name. A glob in the directory part is refused. | |
| sudo | No | Read as root. Straight away for places a plain user cannot read (/root, /var/lib/docker); otherwise retry with true when the answer names what it could not read. Default: false | |
| query | Yes | Regex, grep -E dialect. | |
| since | No | Window: "today" | "2026-08-19" | "2h" | "3d", the day taken from the server. Skips files untouched in it (count reported). A window of a day or more then keeps only lines dated inside — 2026-08-19, Aug 19, 19/Aug/2026; a shorter one filters files and leaves their lines alone. Undated file: searched whole and named. | |
| context | No | Lines around each match, as grep -C. Excluded by namesOnly. Default: 0 | |
| profile | Yes | Machine name. | |
| timeout | No | Milliseconds per file, default 30000. Raise for multi-gigabyte files with from: "end". | |
| container | No | Read this container's output instead of a file: docker is asked where it writes, and the answer names the file it read. Whatever cannot be read this way — a driver that keeps no file, an engine that is not docker, a name nothing answers to — comes back said aloud, naming ssh_exec as the way through. The file belongs to root, so sudo: true. Give this or path, never both. | |
| namesOnly | No | Answer = matching paths, no line bodies. One command for the whole list; maxMatches and context do not apply. Default: false | |
| recursive | No | Walk the whole tree, not one level. With a glob: "/etc/nginx/*.conf" reaches those at any depth. Symlinked files are searched, symlinked dirs not descended. Default: false | |
| maxMatches | No | Cap per file; reaching it is reported. Default: 200 | |
| caseSensitive | No | false = case ignored. Default: false |
| Name | Required | Description |
|---|---|---|
| files | No | Matching file names, for namesOnly. |
| lines | No | The matching lines. context:true marks a neighbour shown alongside, not a match. |
| source | No | Named only when container was asked: the engine, the driver and the file the lines were read from. |
| limited | No | maxMatches was reached — more exist than are shown. |
| matches | No | Lines in the answer — matches plus any context lines; with namesOnly, matching files. |
| truncated | No | Output was cut mid-answer: incomplete, not empty. |
| files_skipped | No | Left unread by the since window. |
| files_undated | No | No recognisable timestamp: searched whole, the window was not applied. |
| files_searched | No | |
| files_unreadable | No | Opened with an error — not proof the text is absent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral clarity beyond the readOnlyHint annotation: an empty answer means no match, never a failed search, and unreadable files are listed apart. This prevents an agent from misinterpreting an empty result as an error. The readOnly annotation already covers mutation safety, so the added semantics are above baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two dense sentences with no wasted words. The core purpose, output distinction, no-match semantics, failure handling, sibling alternative, and container usage are all packed in efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full input schema and an output schema present, the description covers the non-obvious behavioral gotchas an agent needs: empty-result semantics, unreadable-file reporting, and the tail alternative. It could have mentioned the output structure explicitly, but the output schema already supplies that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter thoroughly. The description reinforces the container-by-name notion and the line-bodies-versus-paths choice, but it does not add meaning beyond what the parameter descriptions already supply. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb and object: 'Greps log files on the server and returns the matching lines with their paths.' It also distinguishes the paths-only mode and immediately contrasts itself with ssh_log_tail, so an agent can disambiguate it from the closest sibling without inspecting the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names when a sibling is cheaper: 'For the tail of a file rather than a search through it, ssh_log_tail is cheaper.' It also conveys the container-vs-path usage pattern. It does not enumerate all alternatives among the many siblings, but the relevant distinction is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the last lines of one or more log files, whatever their size — nothing is shipped here to be trimmed locally. A container is read by name instead of by path, through the file its driver writes. To look for something rather than read the end, use ssh_log_search.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | One path, a list, or a glob in the file name: "/var/log/*.log". Expanded by the server's find, not a shell — a name with a space or a newline stays one name. A glob in the directory part is refused. | |
| sudo | No | Read as root. Straight away for places a plain user cannot read (/root, /var/lib/docker); otherwise retry with true when the answer names what it could not read. Default: false | |
| lines | No | How many lines from the end. Default: 100 | |
| profile | Yes | Machine name. | |
| container | No | Read this container's output instead of a file: docker is asked where it writes, and the answer names the file it read. Whatever cannot be read this way — a driver that keeps no file, an engine that is not docker, a name nothing answers to — comes back said aloud, naming ssh_exec as the way through. The file belongs to root, so sudo: true. Give this or path, never both. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds behavioral context: 'whatever their size — nothing is shipped here to be trimmed locally' and explains container resolution 'through the file its driver writes.' These clarify how the tool behaves without contradicting the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three purposeful sentences: core behavior and scope come first, container nuance follows, and the sibling alternative closes. No filler, no repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tail tool, the description plus fully described schema covers file paths, globs, container mode, sudo behavior, and search routing. It does not describe the return format, but that is reasonably inferable from 'returns the last lines' and no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter descriptions already carry the meaning. The main description adds tailing/container framing but does not materially extend individual parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Returns the last lines of one or more log files'. It also distinguishes itself from the sibling ssh_log_search by explicitly contrasting tailing with searching for something.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: 'To look for something rather than read the end, use ssh_log_search.' It also clarifies the container-read path vs ordinary file paths, giving concrete context for when each mode applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Looks after the SSH connections themselves, not the machines behind them: lists the configured profiles, tests one, reports pool statistics, closes a connection or reloads the profile file. Start here on a machine you have not used yet — test names the state before anything else runs.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Which of the five to do. close and reload drop live connections; the other three only read. | |
| profile | No | Which machine. Required for stats, test and close; list and reload take none. |
| Name | Required | Description |
|---|---|---|
| state | No | ready — logged in, commands run; limited — logged in and commands run, but the shell is not POSIX; no-route — the server was never reached; rejected — the server was reached and refused the login. null — nothing was checked: only the test action reaches the server. |
| action | No | |
| broken | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
| profile | No | |
| profiles | No | |
| exit_code | No | |
| latency_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals important behavioral nuance beyond the annotations: close and reload drop live connections while the other actions only read. Annotations already signal idempotent and non-destructive, so this is additive rather than repetitive, and it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core scope and followed by practical guidance. Every phrase earns its place; there is no redundant filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two parameters, an output schema, and strong annotations, the description covers the essential usage guidance, side-effect differences, and conceptual scope. It could explicitly enumerate which action to use in which scenario, but the existing context is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters already well described in the schema. The description adds a high-level summary of actions but does not materially improve on the schema's per-parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb-and-resource purpose: managing SSH connections themselves, listing profiles, testing, reporting pool stats, closing, and reloading. It explicitly distinguishes itself from tools that operate on machines behind the connections, which differentiates it from the many ssh_ sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete usage context: 'Start here on a machine you have not used yet' and recommends that 'test names the state before anything else runs.' It does not explicitly name which sibling tools to use instead, but its scope exclusion ('not the machines behind them') makes the appropriate context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports one systemd unit: whether it is loaded, active and enabled, with the tail of its journal. A machine without systemd comes back as NOT CHECKED, never as a stopped service — that would read as an outage which is not there. For every failed unit at once, ssh_audit_baseline names them.
| Name | Required | Description | Default |
|---|---|---|---|
| sudo | No | Read as root. Straight away for places a plain user cannot read (/root, /var/lib/docker); otherwise retry with true when the answer names what it could not read. Default: false Without it the journal comes back trimmed to what the profile user may see. | |
| unit | Yes | Unit name, e.g. "nginx" or "nginx.service". | |
| since | No | Journal window, as journalctl reads it: "1h ago", "today", "2026-08-19". | |
| profile | Yes | Machine name. | |
| log_lines | No | Journal lines returned. Default: 50 |
| Name | Required | Description |
|---|---|---|
| unit | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
| enabled | No | |
| outcome | No | checked — systemd answered, and the fields below carry its measurement; no_systemd — there was nobody to ask on this server, so the service was not measured; no_unit — systemd knows no such unit, which is not the same as a unit that is stopped. |
| restart | No | |
| sub_state | No | |
| recent_log | No | |
| status_head | No | |
| active_state | No | |
| restart_after | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, the safety profile is already known, so the description adds valuable behavioral context beyond annotations: the NOT CHECKED distinction for non-systemd machines and the journal-tail behavior. This prevents a false outage conclusion and clarifies return semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler. The main purpose is front-loaded, and each subsequent sentence contributes either a behavioral caveat or a sibling alternative. Nothing is repeated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the input schema fully documents parameters, the description covers the essential agent-facing context: single-unit scope, journal tail, systemd-absence semantics, and the relevant sibling tool. No critical gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all five parameters well. The description does not materially add parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Reports one systemd unit: whether it is loaded, active and enabled, with the tail of its journal.' It also differentiates from ssh_audit_baseline by noting that sibling names failed units at once, making the tool's single-unit scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit alternative and condition: 'For every failed unit at once, ssh_audit_baseline names them.' It also provides a crucial usage caveat—machines without systemd return NOT CHECKED, not stopped—so an agent knows when not to interpret the result as an outage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports how a machine is doing right now: cpu, memory, disk, containers, listening ports, services and recent errors, in one round trip. Whatever could not be measured comes back null and marked unavailable, never as a zero that reads like an idle machine. For how the machine is set up rather than how it is running, use ssh_audit_baseline.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | Yes | Machine name. |
| Name | Required | Description |
|---|---|---|
| load | No | |
| ports | No | |
| cpu_pct | No | |
| mem_pct | No | |
| disk_pct | No | |
| services | No | |
| listening | No | |
| containers | No | |
| error_lines | No | |
| unavailable | No | |
| recent_errors | No | |
| services_running | No | |
| containers_running | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context: unmeasured values return null and are marked unavailable rather than zero, preventing misinterpretation. This goes beyond annotations by defining output semantics, so a 4 is justified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the core purpose, adds the critical null-behavior detail, and ends with the alternative. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (which explains return structure) and the description covers what it measures, the round-trip efficiency, and the null unavailable convention, nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'profile' is already fully described in the schema as 'Machine name.' (100% coverage). The description does not add any further detail about the parameter, so baseline 3 applies—the schema carries the full semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports current machine health (cpu, memory, disk, containers, listening ports, services, recent errors) in one round trip, and explicitly contrasts it with ssh_audit_baseline for setup vs. running state. This makes its purpose unambiguous and distinguishes it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: for current operational status, and when not to (for configuration use ssh_audit_baseline). This directly names the alternative and the condition, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks the TLS certificate a domain serves — days left, whether the name matches a SAN, the issuer and whether renewal is configured — with the handshake made from the server itself, so it sees what that machine sees, including hosts closed to the outside. A null field means the check could not run, not that the certificate is bad. Run it per domain, once ssh_audit_baseline has named the sites.
| Name | Required | Description | Default |
|---|---|---|---|
| port | No | Default: 443 | |
| sudo | No | Read the renewal config as root. Without it "no hook configured" only means "could not look". Default: false | |
| domain | Yes | The name to ask for, e.g. "example.com". | |
| profile | Yes | Machine name. | |
| check_renew_hook | No | Also look for the renewal config. Default: true |
| Name | Required | Description |
|---|---|---|
| port | No | |
| domain | No | |
| issuer | No | |
| san_text | No | |
| not_after | No | |
| days_until_expiry | No | |
| renew_hook_evidence | No | |
| renew_hook_configured | No | |
| san_includes_hostname | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description reveals that the handshake is made from the server itself, so it sees hosts closed to the outside, and clarifies that null fields mean the check could not run rather than certificate failure. This is meaningful behavioral context the annotation does not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and front-loads the core purpose, then adds null semantics and usage sequencing. The first sentence is a bit long with several em-dash interruptions, but every clause adds signal and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations declaring read-only behavior, an output schema present, and 100% parameter coverage, the description adds the remaining needed context: what the check sees, how to interpret nulls, and when to run it relative to ssh_audit_baseline. Nothing critical is missing for an agent to select and call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all five parameters. The tool description adds useful context around domains and null results, but it does not add new parameter-level meaning beyond what the schema provides, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Checks') and resource ('the TLS certificate a domain serves'), and enumerates the concrete outputs: days left, SAN match, issuer, renewal configuration. This clearly differentiates it from sibling SSH tools like ssh_exec or ssh_audit_baseline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to 'Run it per domain, once ssh_audit_baseline has named the sites,' giving a clear prerequisite and invocation pattern. It does not enumerate when not to use it or name alternatives, but the sequencing guidance is actionable and specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copies a local file or directory to a server, checked by sha256 on both sides and never left half-written at the target. A directory replaces the target whole — whatever was there and is not in the source is gone with it; merge: true keeps it instead. For text you can paste, ssh_file_write is cheaper; piping base64 through ssh_exec truncates silently.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Octal, one value for every file sent. Omit to keep local permissions. | |
| sudo | No | For /etc, /opt and the like, and for setting an owner. Data stages in /tmp first — the machine needs room for a second copy. Default: false | |
| merge | No | Directories only. true = what the target holds and the source does not stays — uploads, .env, logs; same-named files are taken from the source. The tree is still put in place whole, by one rename. mode and owner then cover the kept files too. Default: false | |
| owner | No | "root:root", every file and directory sent. Needs sudo; without it the answer says it was not applied. | |
| verify | No | sha256 on both sides, per file. "unavailable" = no sha256 on the machine = delivered, not broken. "mismatched" fails the call and replaces nothing. Default: true | |
| profile | Yes | Machine name. | |
| timeout | No | Milliseconds. No ceiling by default — a transfer runs as long as it takes. | |
| overwrite | No | false = refuse rather than replace, including when the target cannot be checked. A directory is judged whole, not per file. Default: true | |
| recursive | No | Only to force it — a directory is recognised on its own. | |
| local_path | Yes | A file or a directory on this machine. | |
| remote_path | Yes | Where it goes on the server. A sent directory becomes this path itself and replaces it whole, not file by file — with merge: true what the source lacks stays. |
| Name | Required | Description |
|---|---|---|
| files | No | |
| legend | No | What the words in this answer mean. A key names the field before the value — "state=limited", "jobs[].state=lost" — and only the values this answer actually used are listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint and destructiveHint annotations, the description discloses the critical behavior: sha256 verification on both sides, atomic writes that are never half-left, and full replacement of the target directory unless merge:true is set. This is substantive behavioral detail, not just a restatement of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first states the action and key guarantees, the second clarifies the destructive directory behavior, and the third routes to an alternative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich parameter schema, the output schema, and annotations, the description covers the essential operational invariants: atomicity, verification, destructive replacement, and the relevant alternative. Nothing needed to correctly invoke the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all 11 parameters richly, so the baseline is 3. The description adds cross-cutting meaning not obvious from individual parameters: the transfer is atomic, directories replace the target whole, and verification is built in. This is useful, but the per-parameter semantic burden is largely carried by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Copies a local file or directory to a server.' It also distinguishes itself from siblings by noting that ssh_file_write is cheaper for pasteable text, making the tool's role clear against the other SSH tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly gives a decision rule: for text you can paste, use ssh_file_write instead, and warns that piping base64 through ssh_exec truncates silently. This tells an agent when not to use this tool and which sibling to prefer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.3.3ssh_audit_baseline4 fields changedInput schema / properties / include_sudo_sections / descriptionPrevious value: -"Read sshd config as sshd sees it (sshd -T), needs root. Without it the ssh section says so instead of guessing from the file. Default: false"New value: +"Run the sections that need root as root: sshd -T for ssh, ufw and iptables rules for firewall. Without it those sections name what they could not read instead of guessing. Default: false"Output schema / properties / firewall / properties / iptables / properties / status / descriptionAdded value: +"not_installed — the tool is absent from the server, so it filters nothing here; no_access — the tool is there, but reading its rules needs root: what it allows is unknown; read — the rules were read, and the fields beside this one come from them."Output schema / properties / firewall / properties / ufw / properties / status / descriptionAdded value: +"not_installed — the tool is absent from the server, so it filters nothing here; no_access — the tool is there, but reading its rules needs root: what it allows is unknown; read — the rules were read, and the fields beside this one come from them."Output schema / properties / legendAdded value: +{
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed.",
+ "type": "object"
+}ssh_download4 fields changedInput schema / properties / verify / descriptionPrevious value: -"sha256 on both sides, per file. \"unavailable\" = no sha256 on the machine = delivered, not broken. Default: true"New value: +"sha256 on both sides, per file. \"unavailable\" = no sha256 on the machine = delivered, not broken. \"mismatched\" fails the call and replaces nothing. Default: true"Output schema / properties / files / items / properties / verified / descriptionAdded value: +"How the sha256 check ended, not whether the data landed — written says that. verified — sha256 was compared after the write and matched; mismatched — sha256 was compared and differed: nothing was replaced, and the path still holds what it held before; unavailable — the check had nothing to work with, and reason says what was missing; skipped — no comparison ran: none was asked for, or nothing landed to compare."Output schema / properties / files / items / properties / verified / enumPrevious value: -[
- "verified",
- "unavailable",
- "skipped"
-]New value: +[
+ "verified",
+ "mismatched",
+ "unavailable",
+ "skipped"
+]Output schema / properties / files / items / properties / written / descriptionAdded value: +"Whether the data reached the path. Permissions and owner are a separate matter: one that did not apply is named in reason, and written stays true."ssh_file_list1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "entries": {
+ "items": {
+ "properties": {
+ "group": {
+ "type": "string"
+ },
+ "mode": {
+ "description": "Octal, as chmod takes it: \"644\", \"4755\" — not the rwx letters ls prints.",
+ "type": "string"
+ },
+ "mtime": {
+ "description": "Seconds since epoch, UTC.",
+ "type": "number"
+ },
+ "name": {
+ "description": "Name inside the listed directory; with recursive, the path below it. Never a full path, so it reads the same either way.",
+ "type": "string"
+ },
+ "owner": {
+ "type": "string"
+ },
+ "size": {
+ "type": "number"
+ },
+ "target": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "What the entry is, which decides what size means for it. file — a regular file, and size is its bytes; dir — a directory: size is the directory entry itself, never the sum of what it holds; symlink — a symbolic link — target says where it points, and size is the length of that path; other — a socket, fifo or device node: there is no content to read here.",
+ "enum": [
+ "file",
+ "dir",
+ "symlink",
+ "other"
+ ],
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "legend": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed.",
+ "type": "object"
+ },
+ "path": {
+ "type": "string"
+ },
+ "truncated": {
+ "description": "The output limit cut the answer: the directory holds more than entries lists.",
+ "type": "boolean"
+ },
+ "unreadable": {
+ "description": "Directories nobody was allowed to enter. Their contents are missing from entries, and a list short by the one that mattered looks complete.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+}ssh_file_write4 fields changedInput schema / properties / files / oneOfPrevious value: -[
- {
- "properties": {
- "binary": {
- "description": "content is base64, decoded before writing. Default: false",
- "type": "boolean"
- },
- "content": {
- "description": "The whole new content, written byte for byte. Replaces the file, never extends it; no trailing newline is added.",
- "type": "string"
- },
- "mode": {
- "description": "Octal string, \"644\". Applied before the file takes its place.",
- "type": "string"
- },
- "path": {
- "description": "Where the file goes.",
- "type": "string"
- },
- "sudo": {
- "description": "Write as root — /etc and anywhere the profile user cannot write. Default: false",
- "type": "boolean"
- },
- "verify": {
- "description": "Compare sha256 before the file takes its place. Default: false",
- "type": "boolean"
- }
- },
- "required": [
- "path",
- "content"
- ],
- "type": "object"
- },
- {
- "items": {
- "properties": {
- "binary": {
- "description": "content is base64, decoded before writing. Default: false",
- "type": "boolean"
- },
- "content": {
- "description": "The whole new content, written byte for byte. Replaces the file, never extends it; no trailing newline is added.",
- "type": "string"
- },
- "mode": {
- "description": "Octal string, \"644\". Applied before the file takes its place.",
- "type": "string"
- },
- "path": {
- "description": "Where the file goes.",
- "type": "string"
- },
- "sudo": {
- "description": "Write as root — /etc and anywhere the profile user cannot write. Default: false",
- "type": "boolean"
- },
- "verify": {
- "description": "Compare sha256 before the file takes its place. Default: false",
- "type": "boolean"
- }
- },
- "required": [
- "path",
- "content"
- ],
- "type": "object"
- },
- "type": "array"
- }
-]New value: +[
+ {
+ "properties": {
+ "binary": {
+ "description": "content is base64, decoded before writing. Default: false",
+ "type": "boolean"
+ },
+ "content": {
+ "description": "The whole new content, written byte for byte. Replaces the file, never extends it; no trailing newline is added.",
+ "type": "string"
+ },
+ "mode": {
+ "description": "Octal string, \"644\", for this file alone. Applied before the file takes its place.",
+ "type": "string"
+ },
+ "owner": {
+ "description": "\"root:root\", for this file alone. Set before the file takes its place. Needs sudo; without it the answer says it was not applied.",
+ "type": "string"
+ },
+ "path": {
+ "description": "Where the file goes.",
+ "type": "string"
+ },
+ "sudo": {
+ "description": "Write as root, for this file alone — /etc and anywhere the profile user cannot write. Default: false",
+ "type": "boolean"
+ },
+ "verify": {
+ "description": "Compare sha256 before the file takes its place. A mismatch fails the call and leaves the path as it was. Default: true",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "path",
+ "content"
+ ],
+ "type": "object"
+ },
+ {
+ "items": {
+ "properties": {
+ "binary": {
+ "description": "content is base64, decoded before writing. Default: false",
+ "type": "boolean"
+ },
+ "content": {
+ "description": "The whole new content, written byte for byte. Replaces the file, never extends it; no trailing newline is added.",
+ "type": "string"
+ },
+ "mode": {
+ "description": "Octal string, \"644\", for this file alone. Applied before the file takes its place.",
+ "type": "string"
+ },
+ "owner": {
+ "description": "\"root:root\", for this file alone. Set before the file takes its place. Needs sudo; without it the answer says it was not applied.",
+ "type": "string"
+ },
+ "path": {
+ "description": "Where the file goes.",
+ "type": "string"
+ },
+ "sudo": {
+ "description": "Write as root, for this file alone — /etc and anywhere the profile user cannot write. Default: false",
+ "type": "boolean"
+ },
+ "verify": {
+ "description": "Compare sha256 before the file takes its place. A mismatch fails the call and leaves the path as it was. Default: true",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "path",
+ "content"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+]Output schema / properties / files / items / properties / verified / descriptionAdded value: +"How the sha256 check ended, not whether the data landed — written says that. verified — sha256 was compared after the write and matched; mismatched — sha256 was compared and differed: nothing was replaced, and the path still holds what it held before; unavailable — the check had nothing to work with, and reason says what was missing; skipped — no comparison ran: none was asked for, or nothing landed to compare."Output schema / properties / files / items / properties / verified / enumPrevious value: -[
- "verified",
- "unavailable",
- "skipped"
-]New value: +[
+ "verified",
+ "mismatched",
+ "unavailable",
+ "skipped"
+]Output schema / properties / files / items / properties / written / descriptionAdded value: +"Whether the data reached the path. Permissions and owner are a separate matter: one that did not apply is named in reason, and written stays true."ssh_job_kill2 fields changedOutput schema / properties / outcome / descriptionAdded value: +"signalled — the signal reached the process group of the job; gone — the job had already ended, so there was nothing to stop; nopid — the job recorded no pid, so there was nothing to signal; missing — the server knows no job under this id; no-answer — the server did not answer the stop request, so the job state is unknown."Output schema / properties / signal / descriptionAdded value: +"What was actually sent, which is not always what was asked for."ssh_job_list2 fields changedOutput schema / properties / jobs / items / properties / started_at / descriptionAdded value: +"Seconds since the epoch; null — the server did not record it."Output schema / properties / jobs / items / properties / state / descriptionAdded value: +"running — started and still running: this is not the outcome, come back later; finished — the job ended and reported its exit code; lost — the job is gone and left no exit code behind; missing — the server knows no job under this id."ssh_job_status2 fields changedOutput schema / properties / jobs / items / properties / started_at / descriptionAdded value: +"Seconds since the epoch; null — the server did not record it."Output schema / properties / jobs / items / properties / state / descriptionAdded value: +"running — started and still running: this is not the outcome, come back later; finished — the job ended and reported its exit code; lost — the job is gone and left no exit code behind; missing — the server knows no job under this id."ssh_log_search4 fields changedInput schema / properties / containerAdded value: +{
+ "description": "Read this container's output instead of a file: docker is asked where it writes, and the answer names the file it read. Whatever cannot be read this way — a driver that keeps no file, an engine that is not docker, a name nothing answers to — comes back said aloud, naming ssh_exec as the way through. The file belongs to root, so sudo: true. Give this or path, never both.",
+ "type": "string"
+}Input schema / properties / since / descriptionPrevious value: -"Window: \"today\" | \"2026-08-19\" | \"2h\" | \"3d\", the day taken from the server. Skips files untouched in it (count reported), then keeps only lines dated inside — 2026-08-19, Aug 19, 19/Aug/2026. Undated file: searched whole and named. Under a day filters files, not lines."New value: +"Window: \"today\" | \"2026-08-19\" | \"2h\" | \"3d\", the day taken from the server. Skips files untouched in it (count reported). A window of a day or more then keeps only lines dated inside — 2026-08-19, Aug 19, 19/Aug/2026; a shorter one filters files and leaves their lines alone. Undated file: searched whole and named."Input schema / requiredPrevious value: -[
- "profile",
- "path",
- "query"
-]New value: +[
+ "profile",
+ "query"
+]Output schema / properties / sourceAdded value: +{
+ "description": "Named only when container was asked: the engine, the driver and the file the lines were read from.",
+ "type": "string"
+}ssh_log_tail2 fields changedInput schema / properties / containerAdded value: +{
+ "description": "Read this container's output instead of a file: docker is asked where it writes, and the answer names the file it read. Whatever cannot be read this way — a driver that keeps no file, an engine that is not docker, a name nothing answers to — comes back said aloud, naming ssh_exec as the way through. The file belongs to root, so sudo: true. Give this or path, never both.",
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "profile",
- "path"
-]New value: +[
+ "profile"
+]ssh_monitor2 fields changedInput schema / properties / action / descriptionPrevious value: -"Which of the five to do."New value: +"Which of the five to do. close and reload drop live connections; the other three only read."Output schema / properties / state / descriptionAdded value: +"ready — logged in, commands run; limited — logged in and commands run, but the shell is not POSIX; no-route — the server was never reached; rejected — the server was reached and refused the login. null — nothing was checked: only the test action reaches the server."ssh_service_status2 fields changedOutput schema / properties / legendAdded value: +{
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed.",
+ "type": "object"
+}Output schema / properties / outcome / descriptionAdded value: +"checked — systemd answered, and the fields below carry its measurement; no_systemd — there was nobody to ask on this server, so the service was not measured; no_unit — systemd knows no such unit, which is not the same as a unit that is stopped."ssh_upload8 fields changedInput schema / properties / mergeAdded value: +{
+ "default": false,
+ "description": "Directories only. true = what the target holds and the source does not stays — uploads, .env, logs; same-named files are taken from the source. The tree is still put in place whole, by one rename. mode and owner then cover the kept files too. Default: false",
+ "type": "boolean"
+}Input schema / properties / owner / descriptionPrevious value: -"\"root:root\", every file sent. Needs sudo; without it the answer says it was not applied."New value: +"\"root:root\", every file and directory sent. Needs sudo; without it the answer says it was not applied."Input schema / properties / remote_path / descriptionPrevious value: -"Where it goes on the server. A sent directory becomes this path itself and replaces it whole, not file by file."New value: +"Where it goes on the server. A sent directory becomes this path itself and replaces it whole, not file by file — with merge: true what the source lacks stays."Input schema / properties / sudo / descriptionPrevious value: -"For /etc, /opt and the like. Data stages in /tmp first — the machine needs room for a second copy. Default: false"New value: +"For /etc, /opt and the like, and for setting an owner. Data stages in /tmp first — the machine needs room for a second copy. Default: false"Input schema / properties / verify / descriptionPrevious value: -"sha256 on both sides, per file. \"unavailable\" = no sha256 on the machine = delivered, not broken. Default: true"New value: +"sha256 on both sides, per file. \"unavailable\" = no sha256 on the machine = delivered, not broken. \"mismatched\" fails the call and replaces nothing. Default: true"Output schema / properties / files / items / properties / verified / descriptionAdded value: +"How the sha256 check ended, not whether the data landed — written says that. verified — sha256 was compared after the write and matched; mismatched — sha256 was compared and differed: nothing was replaced, and the path still holds what it held before; unavailable — the check had nothing to work with, and reason says what was missing; skipped — no comparison ran: none was asked for, or nothing landed to compare."Output schema / properties / files / items / properties / verified / enumPrevious value: -[
- "verified",
- "unavailable",
- "skipped"
-]New value: +[
+ "verified",
+ "mismatched",
+ "unavailable",
+ "skipped"
+]Output schema / properties / files / items / properties / written / descriptionAdded value: +"Whether the data reached the path. Permissions and owner are a separate matter: one that did not apply is named in reason, and written stays true."v2.3.0ssh_download1 field changedOutput schema / properties / legend / descriptionAdded value: +"What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed."ssh_exec2 fields changedInput schema / properties / detach / descriptionPrevious value: -"Background job on the server: returns an id at once, outlives this call, timeout does not apply. Follow with ssh_job_status / ssh_job_output, stop with ssh_job_kill. One command, no sudo. Default: false"New value: +"Background job on the server: returns an id at once, outlives this call, timeout does not apply. Follow with ssh_job_status / ssh_job_output, stop with ssh_job_kill. One command. With sudo the job runs as root and every later call follows it as root, provided the profile has a password or sudo needs none. Default: false"Output schema / properties / legend / descriptionAdded value: +"What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed."ssh_file_write1 field changedOutput schema / properties / legend / descriptionAdded value: +"What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed."ssh_job_kill2 fields changedInput schema / properties / id / descriptionPrevious value: -"Job id returned by ssh_exec with detach: true"New value: +"Job id returned by ssh_exec with detach: true. A job started with sudo is reached as root from the id alone — nothing extra to pass."Output schema / properties / legend / descriptionAdded value: +"What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed."ssh_job_list1 field changedOutput schema / properties / legend / descriptionAdded value: +"What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed."ssh_job_output1 field changedInput schema / properties / id / descriptionPrevious value: -"Job id returned by ssh_exec with detach: true"New value: +"Job id returned by ssh_exec with detach: true. A job started with sudo is reached as root from the id alone — nothing extra to pass."ssh_job_status2 fields changedInput schema / properties / id / descriptionPrevious value: -"Job id returned by ssh_exec with detach: true"New value: +"Job id returned by ssh_exec with detach: true. A job started with sudo is reached as root from the id alone — nothing extra to pass."Output schema / properties / legend / descriptionAdded value: +"What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed."ssh_monitor1 field changedOutput schema / properties / legend / descriptionAdded value: +"What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed."ssh_upload1 field changedOutput schema / properties / legend / descriptionAdded value: +"What the words in this answer mean. A key names the field before the value — \"state=limited\", \"jobs[].state=lost\" — and only the values this answer actually used are listed."v1.0.0ssh_audit_baselinessh_disk_breakdownssh_downloadssh_execssh_file_listssh_file_readssh_file_writessh_job_killssh_job_listssh_job_outputssh_job_statusssh_log_searchssh_log_tailssh_monitorssh_service_statusssh_snapshotssh_tls_checkssh_uploadEach tool targets a distinct operation with detailed descriptions that explicitly differentiate overlaps (e.g., ssh_snapshot vs ssh_audit_baseline, ssh_log_tail vs ssh_log_search). No two tools appear to perform the same task, and cross-references guide correct selection.
All tool names follow a consistent pattern: the 'ssh_' prefix plus snake_case, with descriptive verbs or nouns (e.g., ssh_exec, ssh_file_read, ssh_job_status, ssh_log_tail). The naming is uniform and predictable, with no mixed conventions.
18 tools is slightly above the ideal 3-15 range, but the breadth of functionality (file operations, job control, logs, health checks, TLS, connection monitoring) justifies the count. Each tool has a clear role and none feel redundant, though the overall number demands careful organization.
The tool set covers the full spectrum of SSH operations: file transfer (upload/download), file management (read/write/list), execution (exec and detached jobs), log analysis (tail/search), system state (snapshot, audit, disk breakdown, service status), TLS validation, and connection management. There are no obvious gaps, and cross-references ensure workflows are not dead-ended.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/hypnosis/ssh-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
