An MCP server that makes SSH work for AI tools by managing the local SSH environment, diagnosing and fixing SSH failures, and providing remote command/file operations over SSH and SFTP.
SSH environment management: ensure ssh-agent is running (ssh_agent_ensure), list and load keys (ssh_key_list, ssh_key_load), resolve effective SSH config (ssh_config_lookup), fix stale host keys (ssh_known_hosts_fix), and test Git-over-SSH auth (ssh_git_check).
Diagnostics: full environment diagnosis (ssh_diagnose) and quick connectivity checks (ssh_test), with actionable fix commands and auto-diagnostics attached to remote-operation failures.
Remote command execution: run shell commands on one host (ssh_exec) or many hosts in parallel (ssh_multi_exec), with per-call env vars, timeouts, and optional command whitelist/blacklist policy.
Remote file operations via SFTP: read/write files, upload/download, list directories, stat, mkdir (including recursive), and delete files/empty directories.
Higher-level operations: structured file search (ssh_find), tail logs with grep filtering (ssh_tail), and systemd service status checks (ssh_service_status).
Connection pooling: automatic connection reuse with a configurable pool cap and graceful waiting when slots are full.
SSH config support: respects ~/.ssh/config aliases, custom ports, users, identity files, and ProxyJump/bastion hosts.
Host key verification: verifies against known_hosts, rejects key changes, supports strict mode, and provides a tool to refresh stale entries.
Windows support: uses the OpenSSH agent named pipe automatically when SSH_AUTH_SOCK is not set.
Programmatic usage: exports a Node.js API for connecting, executing, diagnosing, managing agents/keys, and using the connection pool directly.
Facilitates Ansible deployments by managing SSH keys, agent, and connectivity, resolving host key issues and ensuring reliable SSH access to target hosts.
Ensures Git-over-SSH authentication to Bitbucket by managing SSH keys, diagnosing permission errors, and fixing known host key issues so that git pull/push/clone works.
Enables Composer to install packages from private repositories over SSH by loading the correct SSH keys into the agent and diagnosing authentication failures.
Supports SSH access to DigitalOcean droplets by managing SSH keys, host keys, and providing diagnostics to resolve connection issues.
Resolves Git-over-SSH authentication failures for clone, pull, push, and other operations by managing the SSH agent, keys, and known hosts.
Ensures Git-over-SSH authentication to GitHub by managing SSH keys, diagnosing permission errors, and fixing known host key issues.
Ensures Git-over-SSH authentication to GitLab by managing SSH keys, diagnosing permission errors, and fixing known host key issues.
Enables npm to install packages from private registries over SSH by managing SSH agent, keys, and resolving authentication failures.
Facilitates Terraform operations on remote hosts by managing SSH keys, agent, and connectivity diagnostics to ensure secure and reliable access.
Click on "Deploy 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 run df -h on my production 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.
Make SSH work for AI tools. MCP server that manages your SSH environment, diagnoses what's broken, fixes it, and gives your agent remote access to anything.
Built and maintained by Yaw Labs.
One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.
AI CLI tools run in subprocesses where SSH is constantly broken. The agent tries to git pull and gets Permission denied (publickey). It tries to SSH into a server and the agent socket is stale. It tries to deploy and the host key changed because the instance was recreated. Every time, the AI has no idea what's wrong and spirals.
This happens across every situation that needs SSH keys:
Git — clone, pull, push, fetch, submodules, LFS
Package managers — npm install, pip install, go get, cargo, composer from private repos
Server access — SSH, SCP, SFTP, rsync
Tunneling — port forwarding to databases, SOCKS proxies
Deployment — Ansible, Terraform, Capistrano, deploy scripts
Cloud — AWS EC2, GCP, Azure, DigitalOcean, any VPS
ssh-mcp fixes this. It manages the SSH agent, loads keys, diagnoses failures with actionable fix commands, and provides remote operations — all as MCP tools your AI agent can call.
Related MCP server: Scout MCP
Add to your MCP client config:
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "@yawlabs/ssh-mcp@latest"]
}
}
}On Windows wrap with cmd /c since Node 20+ can't spawn .cmd files directly:
{
"mcpServers": {
"ssh": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@yawlabs/ssh-mcp@latest"]
}
}
}The @latest tag makes npx re-resolve against the registry on every spawn, so each MCP session uses the newest published version. Or install globally if you'd rather pin (no auto-update):
npm install -g @yawlabs/ssh-mcp
# then in client config: "command": "ssh-mcp"Tools that fix your local SSH setup so everything else — git, deploys, tunnels — stops breaking.
Tool | Description |
| Ensure ssh-agent is running. Starts one if needed and sets env vars for the session. |
| List all SSH keys in ~/.ssh/ with type, fingerprint, and agent status. |
| Load a key into the running agent. Ensures the agent is started first. |
| Resolve the effective SSH config for a host (hostname, user, port, proxy, identity files). |
| Remove a stale host key and re-scan. Fixes "host key verification failed" errors. |
| Test Git-over-SSH auth to GitHub, GitLab, Bitbucket, etc. |
| Quick connectivity test with timing and actionable error details. |
Tool | Description |
| Full SSH environment diagnostic. Checks agent, keys, config, known_hosts, and connectivity. Returns exact fix commands for every failure. |
Tool | Description |
| Execute a command on a remote host. Returns stdout, stderr, and exit code (or |
| Read a file from a remote host via SFTP. |
| Write content to a file on a remote host via SFTP. |
| Upload a local file to a remote host via SFTP. |
| Download a file from a remote host to local filesystem. |
| List files in a directory on a remote host. |
| Get metadata for a file or directory (size, mode in octal, uid/gid, mtime/atime, isFile/isDirectory/isSymbolicLink). Use instead of parsing |
| Create a directory via SFTP. Set |
| Delete a file or empty directory via SFTP. Auto-dispatches unlink vs rmdir based on the path's own type ( |
Tools that wrap common patterns agents build with ssh_exec — faster and less error-prone.
Tool | Description |
| Run a command on multiple hosts in parallel. Returns results per host. Optional |
| Search for files remotely with structured parameters ( |
| Read the last N lines of a file, optionally filtered by a grep pattern. |
| Check systemd service status (active, PID, uptime, description). Flags |
When any remote operation fails, ssh-mcp automatically runs diagnostics and includes the results in the error response. Your agent doesn't need to call ssh_diagnose separately — it gets told what's wrong and how to fix it right in the error message.
Remote operations reuse SSH connections automatically. When your agent makes multiple calls to the same host, the first call opens a connection and subsequent calls reuse it. Connections are kept alive for 60 seconds after the last use, then closed automatically.
The pool caps at 100 connections by default, and a connection still being dialed counts against the cap. When the cap is reached the pool closes an idle connection to make room. If every slot is in use or dialing, a tool call waits for one instead of failing:
A single-host remote tool (ssh_exec, the SFTP tools, ssh_find, ssh_tail, ssh_service_status) waits up to its timeout (30s for the SFTP tools, which have no timeout parameter) and is next in line for the first slot that frees, so an ssh_exec arriving in the middle of a wide ssh_multi_exec runs between two of its hosts rather than being refused for the whole run. It reports Connection pool is full only if it never won a slot in that time.
ssh_multi_exec runs at most SSH_MCP_MAX_POOL_SIZE hosts at once (default 100) and works through a longer list as slots free up, so raising the cap raises its parallelism; timeout is per host, not a bound on the whole call. When the pool is full it waits, and gives up only when none of its own hosts holds a slot and a full timeout has passed with none of them starting or finishing. The hosts waiting at that point (up to one per parallel slot) and every host still queued then report Connection pool is full; the queued ones are never attempted.
A call reaches Connection pool is full only when other calls — a long ssh_exec, a concurrent ssh_multi_exec — kept every slot from it for a full timeout; a fan-out wider than the cap that has the pool to itself never does, however long it runs. If you see it, rerun once those calls finish (for ssh_multi_exec, the hosts that reported it), or raise the cap with SSH_MCP_MAX_POOL_SIZE=<n> in the server's environment. The error names the variable.
The library's acquire() / withConnection() do not wait by default: they reject at once with a PoolFullError (code: "ERR_SSH_MCP_POOL_FULL", isPoolFullError()) unless you pass { waitForCapacityMs } — see Programmatic usage.
All connections respect your ~/.ssh/config. Host aliases, custom ports, usernames, identity files, and ProxyJump settings are used automatically. If you have Host myserver configured in your SSH config, just pass host: "myserver" — ssh-mcp resolves everything.
ProxyJump / bastion hosts are supported automatically. If your SSH config has ProxyJump bastion for a host, ssh-mcp connects through the bastion transparently. Chained proxies work too.
All remote operations verify the server's host key against ~/.ssh/known_hosts:
Known host, key matches — accept.
Known host, key changed — reject (MITM protection). The rejection message distinguishes a genuine key mismatch from "the server offered a key type your known_hosts entry doesn't cover", so a missing ed25519 line doesn't read as an attack.
Unknown host — accept, unless SSH_MCP_STRICT_HOST_KEY=1.
That last branch is trust-always, not TOFU. Real trust-on-first-use pins the key it saw the first time and rejects a change afterwards. The connection path never writes to known_hosts — no tool adds an entry as a side effect of connecting — so connecting pins nothing: every connection to a host absent from known_hosts is a "first" use and is accepted, including one where an attacker swapped the key since your last call. Only hosts put into known_hosts out of band get mismatch protection — by you, by ssh-keyscan, or by ssh_known_hosts_fix, the one tool here that does write the file. Call it explicitly to add an entry so future changes are caught.
For stricter environments, set SSH_MCP_STRICT_HOST_KEY=1 to reject unknown hosts. Add them explicitly with ssh_known_hosts_fix first.
The diagnostic tools (ssh_test, ssh_diagnose) use StrictHostKeyChecking=no for their probe commands. Those probes only run echo SSH_OK — no credentials or data pass through — so the relaxed setting is safe for connectivity testing. Real operations always go through the hostVerifier.
ssh_exec and ssh_multi_exec accept free-form shell commands from the agent. For security-conscious deployments, you can restrict which commands run via two env vars, each accepting a comma-separated list of regex patterns:
SSH_MCP_COMMAND_WHITELIST — if set, the command must match at least one pattern, else it's blocked.
SSH_MCP_COMMAND_BLACKLIST — if set, the command must not match any pattern, else it's blocked.
When both are set, the command must pass both checks (whitelist first, then blacklist). When neither is set (the default), all commands are allowed.
Patterns are JavaScript regexes. Use ^ and $ for anchored matches; otherwise patterns are treated as substring matches. Commas are the delimiter, so a literal comma in a pattern needs to be expressed as \x2c or via a character class.
# Read-only allowlist: only ls / df / cat / find / tail
SSH_MCP_COMMAND_WHITELIST="^ls( .*)?,^df( .*)?,^cat ,^find ,^tail "
# Block destructive ops even if your agent goes off-script
SSH_MCP_COMMAND_BLACKLIST="^rm ,^shutdown,^reboot,^mkfs,^dd if=,>\s*/dev/"Blocked commands surface as a clear error mentioning which pattern (or which env var) rejected the call, so the agent can adapt rather than guess. Policy is enforced before the SSH connection opens — no remote process is started for a blocked command.
ssh_exec and ssh_multi_exec onlyEvery other tool runs unchecked. That splits into two very different cases.
The structured read tools are all exempt, but for two different reasons — they don't reach the remote the same way.
ssh_find, ssh_tail and ssh_service_status do build a shell command (find, tail, systemctl), but from typed parameters with every interpolated value shell-quoted, never from free-form agent input. They're exempt for ergonomics: a tight ^ls whitelist would otherwise force you to allow ^find , ^tail , ^systemctl just to keep those tools working — defeating the point of a tight whitelist.
ssh_ls, ssh_stat, ssh_read_file and ssh_download build no command at all. They're pure SFTP (readdir, stat, readFile, fastGet), so — exactly like the mutating SFTP tools below — there is no command string for a regex to match, and these env vars could not gate them even if you wanted them to. They're grouped with the reads rather than flagged as a gap because they don't mutate remote state. One caveat: ssh_download is non-mutating on the remote only — it writes to whatever local path it's handed, and these env vars don't constrain that either.
The SFTP tools that mutate remote state are also unchecked, and that is a genuine gap — not an ergonomics call. ssh_write_file, ssh_upload, ssh_mkdir, and ssh_delete never build a shell command string, so a command-shaped regex has nothing to match. Concretely: SSH_MCP_COMMAND_BLACKLIST="^rm " does not stop ssh_delete, and SSH_MCP_COMMAND_WHITELIST="^ls " does not stop ssh_write_file. Closing this would need a separate path-policy mechanism, which this server deliberately does not have. If you must prevent remote mutation, drop those four tools from your MCP client's tool allowlist (or run a client that gates them) — these two env vars cannot do it.
env parameter (ssh_exec, ssh_multi_exec)When ssh_exec or ssh_multi_exec is called with env: { KEY: "value" }, the values are injected as a KEY='value' ... shell prefix before the command (see the tool descriptions). Policy is checked against the full prefixed command, not the bare command argument — once, before fan-out, in the ssh_multi_exec case. That's the safer ordering at the protocol layer — but it means whitelist patterns need to anticipate the prefix and must be anchored, not substring matches:
# WRONG -- blocks any ssh_exec call that uses `env`, because the final command
# starts with `KEY='value' ` and never matches `^ls`.
SSH_MCP_COMMAND_WHITELIST="^ls "
# RIGHT -- allow zero or more `KEY='value' ` prefixes before the real command.
SSH_MCP_COMMAND_WHITELIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*ls( |$)"You don't have to diagnose this from a bare rejection: when a whitelist blocks a call that used env, the error appends a note explaining that the prefix is why the ^ anchor stopped matching, and suggests the tolerant pattern above.
Avoid substring-match patterns like ls if you're worried about a hostile agent. An agent could pass env: { ATTACK: " ls " } to make the final command ATTACK=' ls ' rm -rf /, which matches a substring ls and bypasses the whitelist. Anchored patterns of the form above don't have this weakness because they require the real command name to follow the env-prefix block, not appear inside a quoted env value.
Blacklists need the same care. ^rm blocks a bare rm call, but doesn't block FOO='bar' rm. Use the same env-prefix-tolerant anchor:
SSH_MCP_COMMAND_BLACKLIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*rm( |$)"If you don't trust the agent's env values at all, the simplest mitigation is to leave env unused in your client config and pass everything through the command string yourself.
On Windows, ssh-mcp uses the OpenSSH Authentication Agent's \\.\pipe\openssh-ssh-agent named pipe automatically when SSH_AUTH_SOCK is not set. No SSH_AUTH_SOCK needed — just make sure the OpenSSH agent service is running.
ssh_agent_ensure and ssh_diagnose probe that pipe and tell you if the service is down. Remote operations do not: they assume the pipe and let the connection fail on its own if the agent isn't there. That is why a stopped agent service shows up as an auth failure rather than an "agent not running" error until you run the diagnostic tools.
All remote operations accept connection parameters:
Parameter | Description | Default |
| SSH hostname or IP (required) | — |
| SSH port | From SSH config or |
| SSH username | From SSH config or current user |
| Path to SSH private key | Auto-detect |
| SSH password (prefer keys) | — |
Auth resolution. An explicit credential wins outright and nothing else is offered. With neither given, ssh-mcp offers the ssh-agent and one on-disk key together — the way the OpenSSH client does — and lets the server pick during the auth exchange. It is not a strict first-match chain past step 2.
Explicit privateKeyPath — used alone. The agent is not offered and no other key is read.
Explicit password — used alone, same as above.
Neither given — both of the following are configured on the same connection:
ssh-agent — SSH_AUTH_SOCK, or on Windows the \\.\pipe\openssh-ssh-agent named pipe. The Windows pipe is assumed unconditionally; ssh-mcp does not check that the OpenSSH Authentication Agent service is actually running.
One on-disk key — the first readable path in ssh -G <host>'s identityfile list. OpenSSH emits that list for every host, including one with no IdentityFile line (it defaults to ~/.ssh/id_rsa, id_ecdsa, id_ecdsa_sk, id_ed25519, id_ed25519_sk), so this is the normal path — not a path reserved for hosts you configured an identity for. ssh-mcp's own built-in list (~/.ssh/id_ed25519, id_rsa, id_ecdsa) is a fallback used only when ssh -G cannot run at all, e.g. no SSH client installed.
Two things worth knowing about step 3:
Only one on-disk key is ever offered — the first candidate that exists. ssh-mcp does not walk the whole identity list the way ssh does, so if the first readable key is the wrong one, authentication rests on the agent's keys. Pass privateKeyPath to force a specific key.
When an agent is configured, an encrypted on-disk key is skipped and the scan moves to the next candidate. The underlying ssh2 library parses privateKey eagerly and errors with "no passphrase given" on an encrypted key, which would break the common setup of an encrypted key on disk with its decrypted copy loaded in the agent. With no agent configured, the first existing key is loaded regardless of encryption and ssh2 surfaces the passphrase error itself. Because the Windows pipe above is assumed unconditionally, the skip is always in force on Windows.
Agent calls ssh_git_check → "Permission denied. Your SSH key is not registered with github.com."
Agent calls ssh_key_list → finds id_ed25519 exists but is not loaded
Agent calls ssh_key_load("~/.ssh/id_ed25519") → "Key loaded"
Agent calls ssh_git_check → "Git SSH authentication to github.com succeeded as username"
Agent runs git pull → worksAgent calls ssh_exec on server → error: "Host key verification failed"
(auto-diagnostics included in error: "Fix with ssh_known_hosts_fix")
Agent calls ssh_known_hosts_fix("my-server") → "Host key refreshed"
Agent calls ssh_exec → worksAgent calls ssh_test("new-server") → "Connection refused at new-server:22"
Agent calls ssh_diagnose("new-server") → full report showing agent running, keys loaded, but host unreachable
Agent reports: "SSH server isn't running on new-server or port 22 is blocked"import { connect, exec, diagnose, ensureAgent, listSshKeys, checkGitSsh, ConnectionPool, isPoolFullError } from '@yawlabs/ssh-mcp';
// Fix SSH environment
const agent = ensureAgent();
console.log(agent.message);
// Check git access
const git = checkGitSsh('github.com');
console.log(git.message);
// List available keys
const keys = listSshKeys();
for (const key of keys) {
console.log(`${key.name} (${key.type}) - ${key.loadedInAgent ? 'loaded' : 'not loaded'}`);
}
// Run a remote command (one-off)
const client = await connect({ host: 'my-server', username: 'deploy' });
const result = await exec(client, 'uptime');
console.log(result.stdout);
client.end();
// Run multiple commands with connection pooling
const pool = new ConnectionPool();
await pool.withConnection({ host: 'my-server' }, async (client) => {
const r1 = await exec(client, 'uptime');
console.log(r1.stdout);
});
// Connection stays open for 60s — next call reuses it
await pool.withConnection({ host: 'my-server' }, async (client) => {
const r2 = await exec(client, 'df -h');
console.log(r2.stdout);
});
// A full pool rejects at once with a PoolFullError; pass a budget to wait for a slot
// instead, the way the tools do, and match the rejection on its code, not its text
try {
await pool.withConnection(
{ host: 'other-server' },
async (client) => {
const r3 = await exec(client, 'uptime');
console.log(r3.stdout);
},
{ waitForCapacityMs: 30_000 },
);
} catch (err) {
if (!isPoolFullError(err)) throw err;
console.log('no slot within 30s:', err.message);
}
pool.drain(); // close all connections when done
// Diagnose issues
const report = diagnose('my-server');
console.log(report.overall); // "ok" | "warning" | "error"
for (const check of report.checks) {
console.log(`[${check.status}] ${check.name}: ${check.message}`);
}The ssh-mcp command — what npx @yawlabs/ssh-mcp runs — is a small launcher. It prefers the oam runtime and otherwise runs the server on Node, so oam is optional. Its minimum is the latest oam release, currently 0.15.2, and it never serves on an older oam.
Two environment variables control the choice; set them in your MCP client's env block:
SSH_MCP_RUNTIME — which runtime to use. Case-insensitive; any value other than oam or node behaves as auto.
auto (default) — use the newest oam it can find at 0.15.2 or newer, otherwise run on Node.
oam — require oam. Fails loudly: if no usable oam is found, the launcher prints what it found and why each one was passed over to stderr, and exits with status 1 instead of starting the server.
node — always Node. The launcher does not look for oam, and OAM_BIN is ignored.
OAM_BIN — path to an oam binary to use in preference to discovery, when it is 0.15.2 or newer. If it does not exist, is older, or will not run, the launcher says so on stderr and carries on with discovery.
Discovery looks in %LOCALAPPDATA%\oam\bin (Windows only), then ~/.oam/bin, then every directory on PATH; asks every oam binary it finds for its version; and uses the newest one at 0.15.2 or newer. On a tie the one found first wins, so an installed copy beats one on PATH. On Windows only oam.exe counts: an oam.cmd/oam.bat shim on PATH is never run, and is named on stderr when no usable oam is found.
By default an unusable oam is not an error. When Node starts the launcher (npx or a global install, run directly by your MCP client), auto mode falls back to Node — silently when there was nothing to find, or with a note on stderr naming each oam (and OAM_BIN) it passed over and why: older than 0.15.2, not runnable, or a shim. A chosen oam that then fails to start is named on stderr too. When an older oam starts the launcher, the handoff to Node is always noted on stderr (see below). With SSH_MCP_RUNTIME=oam, each of these cases exits with status 1 instead.
When the launcher is itself started by oam (oam run <path>/bin/ssh-mcp.mjs, which is how Yaw MCP starts an npx @yawlabs/ssh-mcp entry when a recent oam is installed):
On oam 0.15.2 or newer it runs the server on that oam, in the same process. Nothing is discovered or spawned, OAM_BIN is not read, and SSH_MCP_RUNTIME=oam counts it as the oam it requires.
On an older oam it never runs the server there. It hands the server off to the newest usable oam it can find, or to Node on PATH, or exits with status 1 when there is neither (SSH_MCP_RUNTIME=oam exits with status 1 rather than handing off to Node).
With SSH_MCP_RUNTIME=node it hands the server off to Node on PATH, whatever the oam version.
For example, to always run on Node:
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "@yawlabs/ssh-mcp@latest"],
"env": { "SSH_MCP_RUNTIME": "node" }
}
}
}On Windows, add the same env block to the cmd /c form from Quick start.
Node.js 18+
SSH client installed (for diagnostics and environment management)
Optional: oam 0.15.2+ — see Runtime selection
MIT
Ensure ssh-agent is running and reachable. Starts a new agent if needed and sets environment variables so subsequent SSH operations work. Use this FIRST when SSH operations fail with agent-related errors.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It reveals that it starts a new agent if needed and sets environment variables, which is the core behavior. However, it does not elaborate on potential side effects (e.g., environment persistence, failure handling, or whether it modifies the current shell or system-wide settings). This is adequate but not fully transparent.
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, front-loaded with the primary purpose ('Ensure ssh-agent is running and reachable'), followed by a concise explanation and usage trigger. No wasted words; every sentence adds necessary 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?
For a tool with no parameters and no output schema, the description fully covers what it does and when to use it. It explains the action (starting agent, setting env vars) and the trigger condition. There are no missing details that an agent would need to correctly select and call this tool.
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 tool has zero parameters, so the baseline is 4. The description adds no parameter-specific detail (none needed), and the schema already has full coverage with an empty properties object. No additional semantic clarification is required.
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's purpose: ensuring ssh-agent is running and reachable, starting a new agent if needed, and setting environment variables. The verb 'ensure' and resource 'ssh-agent' are specific, and it distinguishes from sibling tools that focus on file operations, execution, or diagnostics.
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 an explicit trigger condition: 'Use this FIRST when SSH operations fail with agent-related errors.' This gives clear context for when to invoke the tool, though it does not explicitly mention when not to use it or suggest alternatives (e.g., other diagnostics).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve the effective SSH configuration for a host. Shows hostname, user, port, identity files, proxy settings, and all other options from ~/.ssh/config. Use this to understand how SSH will connect to a host.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. The verbs 'Resolve' and 'Shows' strongly imply a read-only operation with no side effects, and it specifies the data source (~/.ssh/config). It does not explicitly state that it avoids network connections or modifications, but the read-only nature is clear enough for an agent to infer safety.
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 with no redundancy. The first sentence front-loads the primary function and output details, while the second gives direct usage guidance. Every word contributes to understanding the tool.
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 single-parameter lookup tool, the description covers the key aspects: what it does, what it returns (including the catch-all 'all other options'), and when to use it. No output schema exists, but the description's enumeration of output fields sufficiently informs the agent of expected results.
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 fully describes the single 'host' parameter as an SSH hostname or IP address (100% coverage). The description adds no additional semantic beyond what the schema provides, 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 uses a precise verb ('Resolve') and a specific resource ('effective SSH configuration for a host'), listing the exact output fields (hostname, user, port, identity files, proxy settings). This clearly differentiates it from sibling tools like ssh_exec (execution) and ssh_read_file (file access), leaving no ambiguity about its 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 description explicitly states when to use it: 'Use this to understand how SSH will connect to a host.' It provides the context but does not explicitly mention exclusions or alternatives. However, by describing the tool's purpose as configuration resolution, it implicitly steers agents away from execution or file transfer tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file or empty directory on a remote host via SFTP. Auto-detects the path type and calls the right SFTP op (unlink for files/symlinks, rmdir for empty dirs). Recursive directory delete is intentionally NOT supported -- for that, use ssh_exec with rm -rf explicitly so the destructive intent is visible in the tool trace. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting. NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to ssh_exec and ssh_multi_exec, so a blacklist such as ^rm does NOT block this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| path | Yes | Absolute path of the file or empty directory to delete. Must start with /. | |
| port | No | SSH port (default: 22) | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the exact SFTP operations (unlink for files/symlinks, rmdir for empty dirs), the lack of recursive support, connection-pool wait behavior (up to 30s), and exemption from command policy. This is comprehensive behavioral disclosure.
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 opening sentence states the core purpose, then each subsequent sentence adds essential operational detail (SFTP ops, recursive limitation, pool wait, policy exemption). No redundant or filler content; it is appropriately dense.
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 covers the tool's destructive scope, its limits, alternative usage, and runtime behavior. Even without an output schema, an agent can invoke it correctly with confidence.
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%, and all six parameters are documented in the schema with types and defaults; the description does not add further meaning to any specific parameter. Baseline of 3 is appropriate because the schema does the heavy lifting.
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 action and scope: 'Delete a file or empty directory on a remote host via SFTP.' It also differentiates itself from siblings by noting that recursive directory delete is unsupported and pointing to ssh_exec for that, making the tool's niche 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?
Provides explicit usage guidance: for recursive deletes it says to use ssh_exec with `rm -rf`, and it clarifies that command whitelist/blacklist does not apply to this tool, only to ssh_exec/ssh_multi_exec. This tells the agent exactly when to prefer this tool and when not to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnose SSH connectivity issues. Checks ssh-agent status, loaded keys, known_hosts, SSH config, and attempts a test connection. Use this BEFORE attempting SSH operations if you suspect connectivity issues, or AFTER a failed SSH operation to understand why it failed.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| port | No | SSH port (default: 22) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the main behaviors—checking agent state, keys, known_hosts, config, and attempting a connection. However, it does not state whether the test connection or diagnostics have side effects, return values, or timeouts, which matters for an unannotated diagnostic tool.
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 deliver purpose, key behaviors, and usage timing without wasted words. The primary purpose is front-loaded, making it easy for an agent to scan and understand quickly.
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 moderately complex diagnostic tool with no annotations and no output schema, the description covers purpose, checks performed, and usage timing. A small gap is the lack of any detail about results or next-step actions, but the core invocation context is sufficiently complete.
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 both parameters (host and port) adequately. The description adds no additional parameter semantics beyond implying the connection target, 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?
Description states a specific verb ('Diagnose') and resource ('SSH connectivity issues'), and enumerates concrete checks: ssh-agent status, loaded keys, known_hosts, SSH config, and a test connection. This is clear enough to distinguish from most siblings, though it does not explicitly compare itself to the closely related ssh_test tool.
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 timing guidance: use it BEFORE SSH operations if issues are suspected, or AFTER a failed SSH operation to understand failure. This is clear context for when to choose the tool, though it does not name or exclude sibling tools like ssh_test or ssh_known_hosts_fix.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a file from a remote host to local filesystem via SFTP. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| port | No | SSH port (default: 22) | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| localPath | Yes | Local path to save the downloaded file | |
| remotePath | Yes | Absolute path to the remote file. Must start with /. | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It usefully discloses connection pool behavior: waiting up to 30s when the pool is full and honoring SSH_MCP_MAX_POOL_SIZE. However, it does not disclose other important behavioral traits such as whether an existing local file is overwritten, authentication requirements beyond the schema, or failure/error behavior.
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 core purpose is front-loaded, and the operational detail about pool wait behavior is separated cleanly. 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?
Given no output schema and no annotations, the description should cover key operational behavior. It covers purpose and pool waiting, and the schema handles parameter semantics, but it omits what happens on local file conflicts, return values, and explicit guidance for choosing between download and read/upload alternatives. This leaves moderate gaps for an agent deciding how 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?
Schema description coverage is 100%, so the schema already documents all 7 parameters including defaults, required fields, the absolute path constraint for remotePath, and the password plaintext warning. The description adds no parameter-level detail beyond indicating the source and destination, 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 states a precise action: 'Download a file from a remote host to local filesystem via SFTP.' It specifies both direction (remote to local) and transport (SFTP), which clearly distinguishes it from siblings like ssh_upload, ssh_read_file, and ssh_write_file.
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 when to use the tool—whenever a file needs to be downloaded from a remote host—but provides no explicit guidance about alternatives or when not to use it. It does not mention that ssh_read_file or ssh_exec might be better for reading file contents without copying to local disk.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a command on a remote host via SSH. The command is interpreted by the remote login shell — pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Use env to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command).
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. VALUES are POSIX-single-quoted, so any byte is safe in a value. KEYS cannot be quoted (a shell assignment prefix requires a bare name), so each key must match /^[A-Za-z_][A-Za-z0-9_]*$/ (the POSIX name grammar) — a key outside that grammar is rejected and the call fails before anything is sent to a host. Command policy is checked against the PREFIXED command, so a `^`-anchored whitelist pattern stops matching once this is set. | |
| host | Yes | SSH hostname or IP address | |
| port | No | SSH port (default: 22) | |
| command | Yes | Shell command to execute on the remote host (interpreted by the remote login shell) | |
| timeout | No | Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately. | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains that the command is interpreted by the remote login shell, metacharacters work as expected, returns stdout/stderr/exit code, applies whitelist/blacklist policy, and discloses that passwords pass as plaintext and may be logged. It also notes the timeout bounds the connection-pool wait. This is thorough and goes beyond what a schema could convey.
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 concise and front-loaded, starting with the core purpose in the first sentence. Each subsequent sentence adds a distinct, necessary detail—shell interpretation, return values, env usage, and policy checking—without redundancy or fluff. The structure is logical and easy to scan.
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 tool's complexity (8 parameters, nested env object, no output schema), the description covers all critical operational aspects: what the command does, how the shell interprets it, what is returned, policy enforcement, timeout behavior, and security warnings. The rich schema complements it well, and nothing essential for an agent to call this 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?
The schema description coverage is 100%, so the schema already documents every parameter in detail (including env quoting, timeout semantics, and password warnings). The tool description adds minimal parameter-level value beyond a mention of `env` usage, which is already covered in the schema. Per the baseline rule for high coverage, a 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 clearly states 'Execute a command on a remote host via SSH,' identifying a specific verb and resource. It also distinguishes itself from file-oriented siblings by explicitly covering generic shell execution, making its purpose unambiguous.
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 does not explicitly state when to use this tool versus alternatives. While it is obvious that this is the general-purpose execution tool among siblings like ssh_read_file and ssh_write_file, there is no explicit 'when to use' or 'when not to use' guidance. The only usage hint is the mention of `env` for setting environment variables, which is more parameter guidance than tool selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for files on a remote host. Wraps the find command with structured parameters so you don't have to construct find syntax manually.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| name | No | Filename pattern with wildcards (e.g. '*.log', 'config.*') | |
| path | Yes | Directory to search in (e.g. /var/log, /home/user) | |
| port | No | SSH port (default: 22) | |
| type | No | File type: f=file, d=directory, l=symlink | |
| newer | No | Reference file path -- find matches files modified more recently than this file | |
| maxsize | No | Maximum file size (e.g. '10M', '500k') | |
| minsize | No | Minimum file size (e.g. '1M', '100k') | |
| timeout | No | Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately. | |
| maxdepth | No | Maximum directory depth to search | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It does not disclose that the operation is read-only, nor does it mention authentication requirements, timeouts, or connection behaviors. The parameter descriptions cover some details (e.g., password plaintext risk, timeout), but the main description omits any behavioral context.
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, concise, and front-loaded with the purpose. It is not overlong, though it sacrifices substantive guidance for brevity.
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 tool with 13 parameters, no output schema, and no annotations, the description is incomplete. It does not describe what the tool returns (e.g., list of file paths) nor any prerequisites like SSH connectivity or authentication setup, leaving the agent without essential context 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%, so each parameter has a description. The tool description adds little beyond 'structured parameters' and does not elaborate on parameter semantics beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.
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 'Search for files on a remote host' with a specific verb and resource, and mentions wrapping the find command. It does not explicitly differentiate from sibling tools like ssh_ls or ssh_stat, but the core purpose is unambiguous.
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 find-like searches ('Wraps the find command with structured parameters so you don't have to construct find syntax manually') but does not explicitly state when to prefer this over ssh_ls or ssh_exec, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test Git-over-SSH authentication to a hosting provider (GitHub, GitLab, Bitbucket, etc). Verifies your SSH key is registered and working. Use this when git clone/pull/push fails with SSH errors.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Git hosting hostname (default: "github.com"). Omit for the default; an empty string is rejected. | |
| user | No | SSH user for the git host (default: "git"). Omit for the default; an empty string is rejected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It accurately conveys that the tool performs a test/verification of SSH authentication, implying a non-destructive diagnostic. However, it does not explicitly state the absence of side effects, potential prerequisites (e.g., key loaded via ssh_agent_ensure), or failure modes. This is adequate but not comprehensive.
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, both information-dense without redundancy. The primary action and purpose are front-loaded, followed by a concrete usage condition. No filler words; every phrase contributes to the agent's understanding. This is a model of conciseness.
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 tool with two optional parameters and no output schema, the description covers the purpose, when to use it, and what it verifies. The only gap is the lack of explicit return-value specification, but given the diagnostic nature, the outcome (success/failure) is implied. The description is complete enough for an agent to select and 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 input schema provides full descriptions for both parameters (host and user), including defaults and constraints. With 100% schema description coverage, the description adds no additional parameter detail, which is acceptable. The baseline of 3 applies because the schema sufficiently documents the parameters without needing extra elaboration.
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 ('Test Git-over-SSH authentication') and clearly identifies the resource (hosting providers like GitHub, GitLab, Bitbucket). It is unambiguous and distinct from generic SSH tools by focusing on Git-over-SSH. The mention of verifying the SSH key registration and working status adds actionable clarity.
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 trigger: 'Use this when git clone/pull/push fails with SSH errors.' This clearly indicates the intended scenario. It does not explicitly state when not to use it or name alternatives, but the specific use case distinguishes it from siblings like ssh_test without requiring further detail. A stronger exclusion clause would elevate this to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all SSH private keys in ~/.ssh/ with their type, fingerprint, and whether they are loaded in the agent. Use this to find which keys are available and which ones need to be loaded. Reports isError only when ~/.ssh exists but could not be read -- an absent or empty ~/.ssh is a successful answer with a ssh-keygen hint.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It clearly specifies the success/failure boundary: isError only when ~/.ssh exists but cannot be read, while absent or empty ~/.ssh is successful and returns an ssh-keygen hint. This is unusually precise.
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 three tight sentences, each carrying useful information: what is listed, when to use it, and exact error semantics. It is front-loaded with the core behavior and has 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?
Despite having no output schema, the description states the returned key fields and the failure condition. For a zero-parameter listing tool, this is complete enough for an agent to call and interpret the result 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 tool has zero parameters, so the baseline is 4. The description adds relevant context by naming the target directory (~/.ssh/), which is all the parameter semantics needed here.
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 'List' with a clear resource ('all SSH private keys in ~/.ssh/') and states the output fields (type, fingerprint, loaded state). This distinguishes it from sibling tools like ssh_key_load or ssh_agent_ensure without requiring schema inspection.
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 'Use this to find which keys are available and which ones need to be loaded,' giving a concrete use case. It does not explicitly name alternatives or when-not-to-use conditions, but the use case is clear enough to route an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load an SSH private key into the running agent. Ensures the agent is running first. Use this after ssh_key_list shows a key that is not loaded.
| Name | Required | Description | Default |
|---|---|---|---|
| keyPath | Yes | Path to the SSH private key to load (e.g. ~/.ssh/id_ed25519) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral burden. It adds useful context by noting 'Ensures the agent is running first', but it does not disclose error handling, idempotency, or permission needs. Minimum viable for a simple load operation.
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, both earning their place. The main action is front-loaded, the prerequisite and usage condition are stated succinctly, with 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?
For a simple one-parameter tool with no output schema, this description provides enough to invoke correctly: what it does, a key prerequisite, and the condition for use. It is slightly incomplete in not mentioning return values or error scenarios, but these are minor for this operation.
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% for the single parameter keyPath, and the description does not add meaning beyond what the schema already provides. 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 clearly states the action ('Load an SSH private key'), the target ('into the running agent'), and differentiates from siblings by referencing ssh_key_list. It is specific and unambiguous.
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 provides a condition for use ('after ssh_key_list shows a key that is not loaded'), but does not mention when not to use it or compare with sibling ssh_agent_ensure, which also handles agent startup. Lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a stale host key from known_hosts and re-scan the host to add the current key. Use this when you see 'Host key verification failed' errors, typically after a server has been recreated or reprovisioned.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| port | No | SSH port (default: 22) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and clearly discloses the mutating behavior: removal of a stale key followed by a re-scan to add the current key. It goes beyond the tool name by specifying the action sequence and trigger, although it doesn't mention the affected known_hosts path or side effects.
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 brief sentences: the first describes the action, the second the trigger. No waste and front-loaded with the primary behavior.
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?
Adequate for a two-parameter tool with no output schema: an agent knows what it does and when to invoke it. It could note that this modifies the local user's known_hosts file, but the action is clear from the phrase 'remove a stale host key from known_hosts'.
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 host and port each described. The description adds no extra parameter detail beyond the schema, so baseline 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?
States a specific sequence (remove stale key, re-scan host) on a specific resource (known_hosts), and explicitly names the error condition it addresses. This differentiates it from sibling ssh tools that execute, read, or list remote files.
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 tells when to use: upon 'Host key verification failed' errors after server recreate/reprovision. Does not name alternatives or exclude cases such as using ssh_diagnose for broader connectivity checks, so one point off.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files in a directory on a remote host via SFTP. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| path | Yes | Absolute path to the remote directory. Must start with /. | |
| port | No | SSH port (default: 22) | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It adds a useful detail about connection-pool waiting (SSH_MCP_MAX_POOL_SIZE, 30s wait), but it does not disclose the return format, whether only names are returned, or how errors such as missing directories or permission denials are surfaced.
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 each carry distinct information: the operation and a resource-limit caveat. No redundancy, filler, or extraneous detail.
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 listing tool, the description covers the operation and even a resource edge case, but the absence of an output schema means the agent must infer the return shape (filenames only? full paths? metadata?). It could also specify behavior on permission errors or nonexistent paths.
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 has 100% description coverage, so the baseline is 3 even without extra parameter information in the description. The description's mention of 'remote host' and 'directory' only repeats the schema's host/path definitions without adding new semantics.
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 ('List'), resource ('files in a directory on a remote host'), and transport ('via SFTP'), which clearly distinguishes it from sibling tools like ssh_read_file, ssh_upload, or ssh_exec. The scope is unambiguous and no tautology is present.
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 clear context for when to use the tool: remote directory listing via SFTP. It does not explicitly name alternatives or exclusion cases, but the operation is specific enough that the intended usage is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a directory on a remote host via SFTP. Set recursive: true to create parent directories as needed (like mkdir -p). Existing intermediate dirs are tolerated; an existing leaf path is still an error. Unlike the other SFTP tools, the path may be relative. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting. NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to ssh_exec and ssh_multi_exec, so a blacklist such as ^rm does NOT block this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| path | Yes | Path of the directory to create. Absolute (starting with /) is recommended and unambiguous. A relative path is also accepted and resolves against the SFTP working directory, which is normally the remote user's home. ~ is NOT expanded — SFTP has no shell to expand it. | |
| port | No | SSH port (default: 22) | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| recursive | No | Create parent directories as needed (default: false). Like `mkdir -p`. | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and does so richly. It documents error semantics ('existing leaf path is still an error'), waiting behavior ('waits up to 30s for a free slot'), and a major security/policy exception ('NOT gated by SSH_MCP_COMMAND_WHITELIST / BLACKLIST'). These exceed basic expectations and give the agent concrete expectations beyond just 'creates a directory.'
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 well-structured and front-loaded: it opens with the core purpose, then immediately covers recursive behavior, then path relativity, then connection pool, then command policy. Every sentence earns its place; there is no fluff or redundancy. It packs a lot of important detail into a compact paragraph without being verbose.
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 tool's simplicity (mkdir) and a fully documented schema, the description covers the key contextual gaps: error behavior, wait timeout, and command policy interplay. It does not explicitly state what happens after the 30s wait exceeds or what the success return value is, but these are minor for this operation. The description is largely complete for an agent to invoke the 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema, particularly for `recursive`: it explains the behavior of existing intermediate dirs vs. an existing leaf path, and the `~` expansion caveat for `path` (though that is also in the schema). This adds value beyond the raw property definitions, justifying a 4.
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: 'Create a directory on a remote host via SFTP.' This clearly states the tool's action and domain, and it distinguishes itself from siblings by noting 'Unlike the other SFTP tools, the path may be relative,' which helps an agent tell it apart from other SFTP operations like ssh_write_file or ssh_ls.
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 clear context about when to use the tool, such as supporting relative paths and the recursive flag behavior, but it stops short of explicitly naming alternatives or saying 'use this instead of ssh_exec for mkdir.' It includes a relevant exclusion about command policy (not gated by whitelist/blacklist), which is an implicit usage condition, but no direct when-not statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a command on multiple remote hosts in parallel. Runs at most SSH_MCP_MAX_POOL_SIZE hosts at once (default 100) and works through a longer list as slots free up. timeout is per host: it bounds each host's command, not the whole call. Each parallel slot works through its share of the list one host at a time, so with the pool to itself a call can take up to about ceil(hosts / SSH_MCP_MAX_POOL_SIZE) x (timeout + connect time). The connection pool is shared with every other tool; when it is full this call waits for slots instead of failing, and gives up only when none of its own hosts holds a slot and a full timeout has passed with none of them starting or finishing. The hosts waiting at that point (up to one per parallel slot) and every host still queued then report Connection pool is full; the queued ones are never attempted. Rerun those hosts once the other calls finish, or raise SSH_MCP_MAX_POOL_SIZE. Returns results per host. Use this instead of calling ssh_exec multiple times — it's faster and shows results side by side. Use env to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once, against the env-prefixed command, before fan-out).
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. VALUES are POSIX-single-quoted, so any byte is safe in a value. KEYS cannot be quoted (a shell assignment prefix requires a bare name), so each key must match /^[A-Za-z_][A-Za-z0-9_]*$/ (the POSIX name grammar) — a key outside that grammar is rejected and the call fails before anything is sent to a host. Command policy is checked against the PREFIXED command, so a `^`-anchored whitelist pattern stops matching once this is set. | |
| port | No | SSH port (default: 22) | |
| hosts | Yes | List of SSH hostnames or IPs | |
| command | Yes | Shell command to execute on all hosts | |
| timeout | No | Per-host command timeout in milliseconds (default: 30000): bounds each host's command, not the whole call. Also the call's no-progress budget on a full pool (see the tool description). | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the full burden falls on the description, and it delivers extensively: concurrency cap (SSH_MCP_MAX_POOL_SIZE, default 100), per-host timeout semantics, shared-pool waiting behavior, the exact give-up condition, the 'Connection pool is full' failure mode, and the policy check (checked once against the env-prefixed command before fan-out). This is unusually complete disclosure of scheduling, failure, and policy behavior.
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 long but every sentence carries real operational information needed to invoke this complex concurrent tool correctly; the purpose is front-loaded in the first sentence. It is structured as one dense paragraph, which hurts scannability — section breaks would improve it — but there is little waste given the genuine complexity being conveyed.
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 an 8-parameter concurrent tool with no annotations and no output schema, the description covers concurrency limits, pool contention, timeout semantics, env injection, and policy behavior remarkably well. The main gap is the return value: it only promises 'results per host' and the pool-full message, with no output schema to fill in the per-host result shape (exit code, stdout/stderr structure).
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% and the schema's own parameter descriptions are already rich (timeout is fully explained there, including its role as the no-progress budget; env is documented with quoting rules and key grammar). The tool description adds some value beyond the schema — notably that env lets you set variables 'without modifying the command string' and ties timeout into the concurrency model — but the schema already does most of the heavy lifting, 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 opening sentence, 'Execute a command on multiple remote hosts in parallel,' states a specific verb, resource, and execution mode. The description also distinguishes it from its sibling, explicitly telling the agent to use this 'instead of calling ssh_exec multiple times,' so an agent can select it correctly without inspecting either 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?
The description gives clear when-to-use guidance: 'Use this instead of calling ssh_exec multiple times — it's faster and shows results side by side,' and provides operational guidance for the pool-full failure case ('Rerun those hosts once the other calls finish, or raise SSH_MCP_MAX_POOL_SIZE'). However, it never states explicit when-not-to-use conditions or names other alternatives like ssh_diagnose, leaving a small gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file from a remote host via SFTP. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| path | Yes | Absolute path to the remote file. Must start with /. | |
| port | No | SSH port (default: 22) | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does add one meaningful behavioral detail: connection pool saturation behavior and the 30s wait. However, it does not mention return content format, file size limits, encoding handling, or error behavior, so transparency is only partial.
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 exactly two sentences: the first states the purpose, the second adds an important operational constraint. No filler or redundancy; every word contributes.
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 adequate for a simple read operation, but since there is no output schema and no annotations, it leaves the return value implied rather than explicit. It also lacks any mention of when to prefer alternatives, making it only minimally complete.
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 has 100% coverage, describing all parameters including defaults and the security warning on password. The description adds no parameter-specific meaning beyond the schema, meriting the baseline score 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 clearly states a specific action ('Read a file') on a specific resource ('remote host via SFTP'). It does not explicitly distinguish itself from similar siblings like ssh_download or ssh_tail, but the core purpose is unambiguous.
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?
No guidance is given about when to use this tool instead of alternatives such as ssh_download (transfer file to local) or ssh_tail (view file tail). There are no usage conditions, exclusions, or examples provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the status of a systemd service on a remote host. Returns whether it's active, its PID, uptime, and description. Use this instead of ssh_exec with systemctl.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| port | No | SSH port (default: 22) | |
| service | Yes | Systemd service name (e.g. nginx, sshd, docker) | |
| timeout | No | Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately. | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. 'Check' implies a read-only operation, and the description enumerates the returned fields (active state, PID, uptime, description), which is useful. It could additionally state explicitly that it does not modify the service or require elevated privileges, so a 4 is appropriate.
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 action is front-loaded, return values are summarized, and the sibling-tool guidance is delivered 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?
There is no output schema, but the description compensates by listing the key return fields. Auth and timeout parameters are already well covered by the input schema. Slightly missing are edge-case behaviors like what happens when the service does not exist or permissions are insufficient, which prevents a 5.
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%, and the schema already documents all 7 parameters, including defaults and timeout/pool behavior. The description adds overall tool context but no additional parameter-specific semantics, so it stays at the baseline 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 uses a specific verb and resource ('Check the status of a systemd service on a remote host') and expands on what is returned (active/PID/uptime/description). It also explicitly separates this tool from ssh_exec, so an agent can distinguish it without opening 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?
The description gives direct routing guidance: 'Use this instead of ssh_exec with systemctl.' This tells the agent exactly when to pick this tool over its most likely alternative, satisfying the usage-guidance requirement clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata for a file or directory on a remote host via SFTP. Returns size, permissions (octal), uid/gid, mtime/atime, and the path type. Symlinks are reported as symlink -> <target kind>: the type describes the link itself while size/mode/mtime describe its TARGET, and a dangling symlink is reported rather than erroring. Use this instead of parsing ls -la output. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| path | Yes | Absolute path to the remote file or directory. Must start with /. | |
| port | No | SSH port (default: 22) | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to rely on, the description carries the full burden and does so well. It discloses the subtle symlink behavior (link kind vs. target metadata, dangling symlink handling) and the connection-pool wait behavior with the exact environment variable and timeout. These are exactly the kind of non-obvious behavioral traits an agent needs to know.
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 dense but not bloated. Core purpose and return values come first, followed by the critical symlink edge case, the usage recommendation, and the pool-wait behavior. Every sentence contributes meaningful 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?
Since there is no output schema, the description compensates by naming the exact returned fields and their format (octal permissions, uid/gid, mtime/atime, path type). It also covers edge cases and failure patterns (dangling symlink) and operational constraints (pool wait). Nothing essential is missing for safe 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 six parameters. The description adds no extra parameter-level detail, which is acceptable at the baseline because the schema carries the 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 states a specific verb ('Get metadata'), a precise resource ('file or directory on a remote host via SFTP'), and enumerates the returned fields. It also implicitly differentiates from nearby siblings like ssh_ls and ssh_read_file by focusing on stat-like metadata.
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 tells the agent when to use this tool: whenever metadata is needed, and explicitly recommends it instead of parsing `ls -la` output. The guidance is direct and actionable, even though it does not enumerate every sibling alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the last N lines of a file on a remote host, optionally filtering by a grep pattern. Use this for reading log files instead of ssh_exec with manual tail/grep commands.
| Name | Required | Description | Default |
|---|---|---|---|
| grep | No | Case-insensitive pattern to filter lines | |
| host | Yes | SSH hostname or IP address | |
| path | Yes | Absolute path to the file to tail | |
| port | No | SSH port (default: 22) | |
| lines | No | Number of lines to read from the end (default: 100). Must be a positive integer. | |
| timeout | No | Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately. | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the transparency burden. It conveys the operation is a read (tail) and involves a remote host, which implies the safety profile, but it doesn't explicitly mention that it does not modify the file, requires SSH authentication, or may block on a connection pool. Basic but adequate; missing operational details beyond the name.
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 filler. The core action is front-loaded and the usage guidance appears immediately after, making it easy for an agent to parse quickly.
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 rich schema covers all 9 parameters and security caveats, and the description supplies the key usage context. The only minor gap is that the return value (the tailed lines) is not explicitly stated, though it is strongly implied by the purpose. No output schema exists to fill this in, but the omission is easy to infer.
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 provides full 100% parameter descriptions, including defaults, password warnings, and pool behavior, so the description adds little beyond reinforcing the grep filter and lines count. Baseline 3 is appropriate because the schema does the heavy lifting.
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 action ('Read the last N lines'), the resource ('a file on a remote host'), and the optional filter ('grep pattern'). It also explicitly calls out the intended use case (reading log files) and distinguishes itself from ssh_exec, making its purpose easy to grasp.
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: 'Use this for reading log files instead of ssh_exec with manual tail/grep commands.' This directly tells the agent when to select this tool and which sibling to prefer it over, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quick connectivity test to an SSH host. Reports success/failure with timing and actionable error details. Lighter and faster than ssh_diagnose — use this for a quick check before running operations.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| port | No | SSH port (default: 22) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool reports success/failure with timing and actionable error details, which informs the agent about the return type and content. It does not mention authentication or potential side effects, but 'test' implies a non-destructive operation. The description adds meaningful context beyond the bare name, so a 4 is appropriate.
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 extremely concise: two sentences that front-load the core purpose, then immediately state the differentiation and usage context. Every sentence earns its place, with no redundant phrasing or 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?
Given the simple two-parameter schema and absence of an output schema, the description covers the essential aspects: what it does, what it returns (success/failure, timing, error details), and when to use it. It lacks precise output formatting details, but it provides enough for an agent to invoke it correctly and interpret the result. This is nearly complete for such a lightweight tool.
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 covers 100% of parameter descriptions (host and port). The description adds no additional meaning about parameters—it does not explain expected formats, defaults, or how the port is used beyond the schema's basic default of 22. Therefore, the baseline of 3 is appropriate; the description adds no extra value here.
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's purpose: a quick connectivity test to an SSH host, reporting success/failure with timing and error details. It explicitly distinguishes itself from the sibling ssh_diagnose by being lighter and faster, so an agent can easily tell them apart without examining schemas.
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 states when to use this tool ('use this for a quick check before running operations') and contrasts it with ssh_diagnose ('lighter and faster'). This gives clear context and implies when not to use it (when a deeper diagnostic is needed). The guidance is direct and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a local file to a remote host via SFTP. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting. NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to ssh_exec and ssh_multi_exec, so a blacklist such as ^rm does NOT block this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| port | No | SSH port (default: 22) | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| localPath | Yes | Path to the local file to upload | |
| remotePath | Yes | Absolute path on the remote host. Must start with /. | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden. It does disclose meaningful behavior: SFTP transport, connection-pool waiting up to 30 seconds, and exemption from command policy. However, it does not mention whether the upload overwrites an existing remote file, what permissions are needed, or what the operation returns, which leaves side-effect ambiguity.
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, no filler. The main action is front-loaded, and the less obvious behavioral details about pool limits and command policy are packed into the second sentence without repetition.
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 tool has seven parameters, no annotations, and no output schema, so the description should supply additional operational context. It covers pool behavior and policy exemption, but it omits whether an existing remote destination is overwritten and what a successful result looks like, leaving the tool not fully self-contained.
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 parameters are already well documented. The description adds tool-level context but no parameter-specific semantics beyond what the schema provides, 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 opens with a specific verb and resource: 'Upload a local file to a remote host via SFTP'. This clearly identifies the operation, and the SFTP detail distinguishes it from exec-style tools and implies the counterpart download tool without ambiguity.
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 clear operating context by stating this is a file upload operation and explicitly notes that command whitelist/blacklist policies do not apply to this tool, which is useful in environments that restrict commands. However, it does not explicitly route the agent to alternatives like ssh_write_file or ssh_download, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write content to a file on a remote host via SFTP. Creates or overwrites the file. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting. NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to ssh_exec and ssh_multi_exec, so a blacklist such as ^rm does NOT block this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| path | Yes | Absolute path to the remote file. Must start with /. | |
| port | No | SSH port (default: 22) | |
| content | Yes | File content to write | |
| password | No | SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process. | |
| username | No | SSH username (default: current user) | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden, and it delivers: overwrite semantics are explicit, the 30s pool wait discloses blocking behavior, and the whitelist/blacklist exemption is a safety-relevant trait. It stops short of disclosing failure modes, parent-directory creation, or return behavior, but the critical destructive and latency behaviors are covered.
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: purpose/overwrite semantics front-loaded first, operational wait behavior second, and the safety-relevant policy exemption third. No filler, no repetition of schema content, and the most decision-relevant facts appear first.
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 7-parameter tool with no output schema and no annotations, the description covers the essential operational profile: what it does, that it overwrites, how long it may block, and its relationship to command policy. Minor gaps remain — return/error behavior and whether parent directories are created — but nothing an agent needs to invoke it safely 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 all 7 parameters are already documented in the schema and the baseline is 3. The description adds contextual value about connection pooling and policy but does not add meaning to any specific parameter, so it neither gains nor loses points.
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 names a specific verb and resource ('Write content to a file on a remote host via SFTP') and immediately adds 'Creates or overwrites the file.' The SFTP mechanism and the explicit reference to ssh_exec/ssh_multi_exec in the policy note clearly differentiate it from command-execution and read siblings, so an agent can tell it apart without opening schemas.
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, useful when-not signal: it is NOT gated by SSH_MCP_COMMAND_WHITELIST/BLACKLIST, and it names the alternatives that are (ssh_exec, ssh_multi_exec). It provides clear operational context (pool-full wait) but does not explicitly route an agent between this tool and other file-related siblings like ssh_upload or ssh_read_file.
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.
v0.17.0ssh_delete1 field changedInput schema / properties / path / descriptionPrevious value: -"Absolute path of the file or empty directory to delete"New value: +"Absolute path of the file or empty directory to delete. Must start with /."ssh_download1 field changedInput schema / properties / remotePath / descriptionPrevious value: -"Absolute path to the remote file"New value: +"Absolute path to the remote file. Must start with /."ssh_exec2 fields changedInput schema / properties / env / descriptionPrevious value: -"Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. Values are POSIX-single-quoted, so any byte is safe."New value: +"Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. VALUES are POSIX-single-quoted, so any byte is safe in a value. KEYS cannot be quoted (a shell assignment prefix requires a bare name), so each key must match /^[A-Za-z_][A-Za-z0-9_]*$/ (the POSIX name grammar) — a key outside that grammar is rejected and the call fails before anything is sent to a host. Command policy is checked against the PREFIXED command, so a `^`-anchored whitelist pattern stops matching once this is set."Input schema / properties / timeout / descriptionPrevious value: -"Command timeout in milliseconds (default: 30000)"New value: +"Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately."ssh_find1 field changedInput schema / properties / timeout / descriptionPrevious value: -"Command timeout in milliseconds (default: 30000)"New value: +"Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately."ssh_git_check4 fields changedInput schema / properties / host / descriptionPrevious value: -"Git hosting hostname (default: \"github.com\")"New value: +"Git hosting hostname (default: \"github.com\"). Omit for the default; an empty string is rejected."Input schema / properties / host / minLengthAdded value: +1Input schema / properties / user / descriptionPrevious value: -"SSH user for the git host (default: \"git\")"New value: +"SSH user for the git host (default: \"git\"). Omit for the default; an empty string is rejected."Input schema / properties / user / minLengthAdded value: +1ssh_ls1 field changedInput schema / properties / path / descriptionPrevious value: -"Absolute path to the remote directory"New value: +"Absolute path to the remote directory. Must start with /."ssh_mkdir1 field changedInput schema / properties / path / descriptionPrevious value: -"Absolute path of the directory to create"New value: +"Path of the directory to create. Absolute (starting with /) is recommended and unambiguous. A relative path is also accepted and resolves against the SFTP working directory, which is normally the remote user's home. ~ is NOT expanded — SFTP has no shell to expand it."ssh_multi_exec2 fields changedInput schema / properties / envAdded value: +{
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. VALUES are POSIX-single-quoted, so any byte is safe in a value. KEYS cannot be quoted (a shell assignment prefix requires a bare name), so each key must match /^[A-Za-z_][A-Za-z0-9_]*$/ (the POSIX name grammar) — a key outside that grammar is rejected and the call fails before anything is sent to a host. Command policy is checked against the PREFIXED command, so a `^`-anchored whitelist pattern stops matching once this is set.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}Input schema / properties / timeout / descriptionPrevious value: -"Command timeout in milliseconds (default: 30000)"New value: +"Per-host command timeout in milliseconds (default: 30000): bounds each host's command, not the whole call. Also the call's no-progress budget on a full pool (see the tool description)."ssh_service_status1 field changedInput schema / properties / timeout / descriptionPrevious value: -"Command timeout in milliseconds (default: 30000)"New value: +"Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately."ssh_stat1 field changedInput schema / properties / path / descriptionPrevious value: -"Absolute path to the remote file or directory"New value: +"Absolute path to the remote file or directory. Must start with /."ssh_tail1 field changedInput schema / properties / timeout / descriptionPrevious value: -"Command timeout in milliseconds (default: 30000)"New value: +"Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately."ssh_upload1 field changedInput schema / properties / remotePath / descriptionPrevious value: -"Absolute path on the remote host"New value: +"Absolute path on the remote host. Must start with /."ssh_write_file1 field changedInput schema / properties / path / descriptionPrevious value: -"Absolute path to the remote file"New value: +"Absolute path to the remote file. Must start with /."v0.11.7ssh_read_file1 field changedInput schema / properties / path / descriptionPrevious value: -"Absolute path to the remote file"New value: +"Absolute path to the remote file. Must start with /."v0.11.0ssh_deletessh_exec1 field changedInput schema / properties / envAdded value: +{
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. Values are POSIX-single-quoted, so any byte is safe.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}ssh_find1 field changedInput schema / properties / newerAdded value: +{
+ "description": "Reference file path -- find matches files modified more recently than this file",
+ "type": "string"
+}ssh_mkdirssh_statssh_tail4 fields changedInput schema / properties / lines / descriptionPrevious value: -"Number of lines to read from the end (default: 100)"New value: +"Number of lines to read from the end (default: 100). Must be a positive integer."Input schema / properties / lines / exclusiveMinimumAdded value: +0Input schema / properties / lines / maximumAdded value: +9007199254740991Input schema / properties / lines / typePrevious value: -"number"New value: +"integer"v0.9.1ssh_agent_ensuressh_config_lookupssh_diagnose4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / port / maximumAdded value: +65535Input schema / properties / port / minimumAdded value: +1Input schema / properties / port / typePrevious value: -"number"New value: +"integer"ssh_download5 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / password / descriptionPrevious value: -"SSH password (prefer keys)"New value: +"SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."Input schema / properties / port / maximumAdded value: +65535Input schema / properties / port / minimumAdded value: +1Input schema / properties / port / typePrevious value: -"number"New value: +"integer"ssh_exec9 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / command / descriptionPrevious value: -"Shell command to execute on the remote host"New value: +"Shell command to execute on the remote host (interpreted by the remote login shell)"Input schema / properties / password / descriptionPrevious value: -"SSH password (prefer keys)"New value: +"SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."Input schema / properties / port / maximumAdded value: +65535Input schema / properties / port / minimumAdded value: +1Input schema / properties / port / typePrevious value: -"number"New value: +"integer"Input schema / properties / timeout / exclusiveMinimumAdded value: +0Input schema / properties / timeout / maximumAdded value: +9007199254740991Input schema / properties / timeout / typePrevious value: -"number"New value: +"integer"ssh_findssh_git_checkssh_key_listssh_key_loadssh_known_hosts_fixssh_ls5 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / password / descriptionPrevious value: -"SSH password (prefer keys)"New value: +"SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."Input schema / properties / port / maximumAdded value: +65535Input schema / properties / port / minimumAdded value: +1Input schema / properties / port / typePrevious value: -"number"New value: +"integer"ssh_multi_execssh_read_file5 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / password / descriptionPrevious value: -"SSH password (prefer keys)"New value: +"SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."Input schema / properties / port / maximumAdded value: +65535Input schema / properties / port / minimumAdded value: +1Input schema / properties / port / typePrevious value: -"number"New value: +"integer"ssh_service_statusssh_tailssh_testssh_upload5 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / password / descriptionPrevious value: -"SSH password (prefer keys)"New value: +"SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."Input schema / properties / port / maximumAdded value: +65535Input schema / properties / port / minimumAdded value: +1Input schema / properties / port / typePrevious value: -"number"New value: +"integer"ssh_write_file5 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / password / descriptionPrevious value: -"SSH password (prefer keys)"New value: +"SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."Input schema / properties / port / maximumAdded value: +65535Input schema / properties / port / minimumAdded value: +1Input schema / properties / port / typePrevious value: -"number"New value: +"integer"v0.2.0ssh_diagnosessh_downloadssh_execssh_lsssh_read_filessh_uploadssh_write_fileScored across 21 tools
Most tools have distinct purposes, but ssh_test and ssh_diagnose both probe connectivity, and ssh_read_file/ssh_download as well as ssh_write_file/ssh_upload share file-transfer boundaries. Descriptions clarify these differences well, so ambiguity is limited to a few near-overlaps.
All tools share the ssh_ prefix and snake_case formatting, but the verb/noun ordering is inconsistent: some are verb-first (ssh_read_file, ssh_write_file), some are noun-first (ssh_key_load, ssh_config_lookup), and others are bare verbs (ssh_exec, ssh_find). The mixed pattern is readable but not predictable.
With 21 tools, this sits at the heavy end of the borderline range. Each tool fills a niche, but the large count may make selection harder than necessary, especially given overlapping utilities like ssh_test, ssh_diagnose, and ssh_git_check.
The toolkit covers agent/key management, connectivity diagnostics, command execution, SFTP file operations, config lookup, and known_hosts repair. Minor gaps like key generation or port forwarding exist, but core SSH workflows are well supported.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
