让 SSH 为 AI 工具所用。 MCP 服务器，管理你的 SSH 环境、诊断问题、修复故障，并让你的智能体远程访问任何内容。
Fork 关系： 本仓库是 YawLabs/ssh-mcp 的衍生 fork。它保留了上游的 SSH/MCP 实现，并通过
SSH_CREDENTIALS_JSON增加了服务端密码别名解析， 从 MCP 工具参数中移除了明文密码，并修复了当~/.ssh尚不存在时首次运行known_hosts创建的问题。上游仍是原始项目；fork 特有的改动在此单独维护。
上游项目由 Yaw Labs 构建和维护。
一键将其添加到你的本地 Yaw MCP 配置中，使其在每个 Yaw Terminal 会话中可用。或者按下面的说明手动安装。
AI CLI 工具在子进程中运行，而 SSH 在那里经常出问题。智能体尝试 git pull 却得到 Permission denied (publickey)。它尝试 SSH 到服务器，但 agent socket 已过期。它尝试部署，但主机密钥因实例被重建而改变。每次 AI 都不知道哪里出了问题，然后陷入困境。
这种情况发生在所有需要 SSH 密钥的场景中：
Git — clone、pull、push、fetch、submodules、LFS
包管理器 — 从私有仓库执行 npm install、pip install、go get、cargo、composer
服务器访问 — SSH、SCP、SFTP、rsync
隧道 — 端口转发到数据库、SOCKS 代理
部署 — Ansible、Terraform、Capistrano、部署脚本
云 — AWS EC2、GCP、Azure、DigitalOcean、任何 VPS
ssh-mcp 解决了这个问题。它管理 SSH agent、加载密钥、诊断故障并提供可操作的修复命令，以及远程操作——全部作为你的 AI 智能体可以调用的 MCP 工具。
Related MCP server: MCP SSH Server
添加到你的 MCP 客户端配置：
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "@txcxgzs/ssh-mcp@latest"],
"env": {
"SSH_CREDENTIALS_JSON": "{\"ssh1\":\"your-password\"}"
}
}
}
}在 Windows 上，用 cmd /c 包裹，因为 Node 20+ 无法直接生成 .cmd 文件：
{
"mcpServers": {
"ssh": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@txcxgzs/ssh-mcp@latest"]
}
}
}@latest 标签使 npx 在每次生成时重新向 registry 解析，因此每个 MCP 会话都使用最新发布的版本。或者，如果你更想固定版本（不自动更新），可以全局安装：
npm install -g @txcxgzs/ssh-mcp
# then in client config: "command": "ssh-mcp"修复你本地 SSH 配置的工具，让其他一切——git、部署、隧道——不再出问题。
工具 | 描述 |
| 确保 ssh-agent 正在运行。如果需要则启动一个，并为会话设置环境变量。 |
| 列出 ~/.ssh/ 中的所有 SSH 密钥，包括类型、指纹和 agent 状态。 |
| 将密钥加载到正在运行的 agent 中。确保先启动 agent。 |
| 解析主机的有效 SSH 配置（主机名、用户、端口、代理、身份文件）。 |
| 移除过期的主机密钥并重新扫描。修复"主机密钥验证失败"错误。 |
| 测试通过 SSH 的 Git 认证，支持 GitHub、GitLab、Bitbucket 等。 |
| 快速连通性测试，带计时和可操作的错误详情。 |
工具 | 描述 |
| 完整的 SSH 环境诊断。检查 agent、密钥、配置、known_hosts 和连通性。对每个故障返回精确的修复命令。 |
工具 | 描述 |
| 在远程主机上执行命令。返回 stdout、stderr 和退出码（当通道以仅信号方式关闭时返回 |
| 通过 SFTP 从远程主机读取文件。 |
| 通过 SFTP 将内容写入远程主机上的文件。 |
| 通过 SFTP 将本地文件上传到远程主机。 |
| 将文件从远程主机下载到本地文件系统。 |
| 列出远程主机上目录中的文件。 |
| 获取文件或目录的元数据（大小、八进制模式、uid/gid、mtime/atime、isFile/isDirectory/isSymbolicLink）。用它代替解析 |
| 通过 SFTP 创建目录。设置 |
| 通过 SFTP 删除文件或空目录。根据路径类型自动分派 unlink 或 rmdir。有意不支持递归删除目录——如果需要，请使用 |
封装智能体常用 ssh_exec 模式的工具——更快且更不易出错。
工具 | 描述 |
| 在多个主机上并行运行命令。按主机返回结果。如果配置了命令策略，则受其约束（策略在扇出前检查一次）。 |
| 使用结构化参数远程搜索文件（ |
| 读取文件最后 N 行，可选地按 grep 模式过滤。 |
| 检查 systemd 服务状态（active、PID、运行时间、描述）。仅当无法找到/查询单元时标记 |
当任何远程操作失败时，ssh-mcp 会自动运行诊断并将结果包含在错误响应中。你的智能体不需要单独调用 ssh_diagnose——它会在错误消息中直接被告知问题所在以及如何修复。
远程操作自动复用 SSH 连接。当你的智能体对同一主机进行多次调用时，第一次调用打开连接，后续调用复用该连接。连接在最后一次使用后保持 60 秒，然后自动关闭。
连接池默认上限为 100 个活动连接。设置 SSH_MCP_MAX_POOL_SIZE=<n> 可提高上限，以应对针对大量不同主机的扇出工作负载（例如跨大型机群的 ssh_multi_exec）。达到上限时，连接池会驱逐一个空闲条目以腾出空间；如果所有条目都在使用中，则拒绝并返回 Connection pool is full。
所有连接都遵循你的 ~/.ssh/config。主机别名、自定义端口、用户名、身份文件和 ProxyJump 设置都会自动使用。如果你在 SSH 配置中配置了 Host myserver，只需传入 host: "myserver"——ssh-mcp 会解析一切。
ProxyJump / 堡垒主机 自动支持。如果你的 SSH 配置中某个主机有 ProxyJump bastion，ssh-mcp 会透明地通过堡垒机连接。链式代理也可以工作。
所有远程操作都会根据 ~/.ssh/known_hosts 验证服务器的主机密钥：
已知主机，密钥匹配 — 接受。
已知主机，密钥已更改 — 拒绝（MITM 防护）。
未知主机 — 首次连接时接受（TOFU）。使用 ssh_known_hosts_fix 固定密钥，以便将来检测不匹配。
对于更严格的环境，设置 SSH_MCP_STRICT_HOST_KEY=1 以拒绝未知主机。先用 ssh_known_hosts_fix 显式添加它们。
诊断工具（ssh_test、ssh_diagnose）对其探测命令使用 StrictHostKeyChecking=no。这些探测只运行 echo SSH_OK——不传递凭据或数据——因此宽松设置对连通性测试是安全的。实际操作始终通过 hostVerifier 进行。
ssh_exec 和 ssh_multi_exec 接受来自代理的自由格式 shell 命令。对于注重安全性的部署，你可以通过两个环境变量限制允许执行的命令，每个变量接受一个以逗号分隔的正则表达式模式列表：
SSH_MCP_COMMAND_WHITELIST — 如果设置，命令必须至少匹配一个模式，否则会被阻止。
SSH_MCP_COMMAND_BLACKLIST — 如果设置，命令不得匹配任何模式，否则会被阻止。
当两者都设置时，命令必须通过两项检查（先白名单，后黑名单）。当两者都未设置时（默认情况），所有命令都被允许。
模式是 JavaScript 正则表达式。使用 ^ 和 $ 进行锚定匹配；否则模式被视为子字符串匹配。逗号是分隔符，因此模式中的字面逗号需要用 \x2c 或字符类来表示。
# 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/"被阻止的命令会显示为清晰的错误信息，指出哪个模式（或哪个环境变量）拒绝了该调用，以便代理能够调整而不是猜测。策略在 SSH 连接打开之前就执行——被阻止的命令不会启动任何远程进程。
结构化的高级工具（ssh_find、ssh_tail、ssh_service_status、SFTP 操作）不受策略限制。它们从类型化参数构建命令，因此严格的白名单 ^ls 会迫使你为了保持这些工具可用而允许 ^find、^tail、^systemctl——这反而使严格白名单失去意义。
ssh_exec 的 env 参数之间的策略交互当使用 env: { KEY: "value" } 调用 ssh_exec 时，这些值会以 KEY='value' ... 的 shell 前缀形式注入到命令之前（参见 ssh_exec 的描述）。策略检查的是完整的带前缀命令，而不是裸的 command 参数。这是在协议层更安全的排序——但这意味着白名单模式需要预料到前缀，并且必须是锚定的，而不是子字符串匹配：
# 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( |$)"避免使用子字符串匹配模式，例如 ls，如果你担心恶意代理的话。代理可以传入 env: { ATTACK: " ls " } 使最终命令变成 ATTACK=' ls ' rm -rf /，这会匹配子字符串 ls 并绕过白名单。上述形式的锚定模式没有这个弱点，因为它们要求真正的命令名跟在环境变量前缀块之后，而不是出现在带引号的环境变量值内部。
黑名单需要同样的注意。^rm 会阻止裸的 rm 调用，但不会阻止 FOO='bar' rm。使用同样的环境变量前缀容错锚定：
SSH_MCP_COMMAND_BLACKLIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*rm( |$)"如果你完全不信任代理的 env 值，最简单的缓解措施是在客户端配置中不使用 env，并自己通过 command 字符串传递所有内容。
在 Windows 上，ssh-mcp 会自动检测 OpenSSH 认证代理服务（通过 \\.\pipe\openssh-ssh-agent 命名管道）。无需 SSH_AUTH_SOCK——只需确保 OpenSSH 代理服务正在运行即可。
所有远程操作都接受连接参数：
参数 | 描述 | 默认值 |
| SSH 主机名或 IP（必填） | — |
| SSH 端口 | 来自 SSH 配置或 |
| SSH 用户名 | 来自 SSH 配置或当前用户 |
| SSH 私钥路径 | 自动检测 |
| 仅在服务器端 | — |
认证解析顺序： ssh-mcp 从以下列表中选择第一个匹配项，并且不会回退到后面的条目——这使得认证方法具有确定性和可预测性。
显式的 privateKeyPath
从 credential_id 解析出的密码
ssh-agent（Unix 上是 SSH_AUTH_SOCK，Windows 上是 \\.\pipe\openssh-ssh-agent）
来自 ~/.ssh/config 中该主机的身份文件
默认密钥路径（~/.ssh/id_ed25519、id_rsa、id_ecdsa）
真实密码永远不会作为 MCP 工具参数。仅在 MCP 服务器环境中配置别名到密码的映射，然后让代理动态选择 host、port、username 和 credential_id：
SSH_CREDENTIALS_JSON={"ssh1":"password1","ssh2":"password2"}{
"host": "bore.pub",
"port": 45201,
"username": "root",
"credential_id": "ssh1",
"command": "hostname"
}如果省略 credential_id，密钥和 ssh-agent 认证仍然可以工作。未知的别名会失败，但错误信息中不会包含任何已配置的密码。
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 } from '@txcxgzs/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);
});
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}`);
}Node.js 18+
已安装 SSH 客户端（用于诊断和环境管理）
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.
| 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) | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| 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 behavioral burden. It is transparent about the operation's side effects, auto-detection logic, the specific SFTP ops used (unlink/rmdir), and the non-recursive limitation. It stops short of disclosing permission requirements or exact failure behavior, but for a destructive tool it is unusually explicit about what happens and what does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundancy: the first states the core purpose, the second explains the mechanics in one clause, and the third gives the necessary alternative and rationale. The critical scoping constraint (non-recursive) is front-loaded and the rationale for the alternative is clearly articulated.
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 what the tool does, its limitations, and the recommended alternative, which is sufficient for an agent to decide when to call it. It does not describe the return value or failure output, but since the tool is simple and no output schema exists, this is a minor omission rather than a usability gap.
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 fully documents all six parameters. The description adds no parameter-level detail beyond the schema, only reinforcing that the path refers to a file or empty directory and that deletion is non-recursive. This meets the baseline for schema-covered parameters without adding significant extra meaning.
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 verb ('Delete'), a specific resource ('a file or empty directory on a remote host via SFTP'), and defines the scope of supported targets (files, symlinks, empty dirs). It also distinguishes itself from ssh_exec for recursive deletes, preventing confusion among the many SSH siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when NOT to use this tool ('Recursive directory delete is intentionally NOT supported') and names the exact alternative to use instead ('use ssh_exec with rm -rf explicitly'). This gives the agent both a clear trigger condition and a fallback path with no ambiguity.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| port | No | SSH port (default: 22) | |
| 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 /. | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| 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 full responsibility for disclosing behavior. It only states the basic operation and does not mention side effects such as overwriting existing local files, handling missing remote files, permission issues, or what the return value indicates. This lack of detail leaves significant behavioral uncertainty.
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 a single, concise sentence that conveys the essential purpose without unnecessary words. It is well-structured and immediately informative, achieving maximum 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?
The description, combined with the fully detailed schema, is sufficient for an agent to perform a basic file download. It covers the core operation and all parameters are explained. However, it lacks explicit mention of output/return behavior and edge cases, though these are not critical for a simple download operation. This is slightly above average completeness.
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 descriptions cover all parameters (100% coverage), but the tool description adds no extra meaning beyond what is already in the schema. Since the schema already explains each parameter (e.g., host, remotePath), the description does not enhance understanding. This aligns with the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (download), the object (a file), the direction (from remote to local), and the method (SFTP). This unambiguous purpose differentiates it from siblings like ssh_upload (which does the opposite) and ssh_read_file (which does not save locally).
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 transferring a remote file to the local filesystem, but it does not explicitly state when to choose this over alternatives (e.g., ssh_read_file for viewing content) or provide exclusion criteria. The guidance is clear from context but not explicit, so it falls at the implied level.
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. | |
| 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) | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| 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 burden. It discloses policy checks (whitelist/blacklist) and warns against passing real passwords for credential_id. It does not explicitly mention potential side effects of command execution, but that is inherent to the tool's purpose.
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 concise, covering the main purpose, shell interpretation, return values, environment handling, and policy checks in a clear sequence without unnecessary fluff.
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 complexity of command execution, the description covers essential aspects: return format, policy restrictions, environment handling, and security warnings. It does not need to explain timeouts or username since those are in the schema. The absence of an output schema is compensated by stating what is returned.
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 detailed descriptions for each parameter. The tool description adds a helpful note about using env without modifying the command string, but this is largely redundant with the schema. Baseline for high coverage is 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 clearly states the tool executes a command on a remote host via SSH, distinguishing it from file-oriented siblings. It specifies shell interpretation and return of stdout/stderr/exit code, making the 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?
While the description clarifies that this tool executes commands (as opposed to file operations like ssh_read_file), it does not explicitly mention when to prefer this over other command-related siblings like ssh_multi_exec. The guidance is implicit rather than explicit.
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) | |
| maxdepth | No | Maximum directory depth to search | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| 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 only says it wraps find, but doesn't disclose that it's a read-only operation, what the output format is, or any side effects (e.g., permission errors, handling of no matches). This is a significant gap for a tool with zero annotation coverage.
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 wasted words. The core action is front-loaded in the first sentence. It's appropriately concise, though it could have included more behavioral detail without becoming 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?
For a tool with 13 parameters, no output schema, and no annotations, the description is far too sparse to be complete. It leaves out crucial context such as return format, error behavior, timeout handling, authentication nuances, and the exact semantics of options like maxdepth or newer. An agent would need to make many assumptions.
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%, meaning every parameter is described in the schema. The description adds no parameter-specific detail beyond a generic reference to 'structured parameters'. It doesn't clarify unusual parameters like newer or the size constraints beyond what the schema already states. Baseline 3 applies 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 it searches for files on a remote host, which is a specific verb and resource. It also notes it wraps the find command, giving a concrete conceptual anchor. However, it doesn't explicitly differentiate from sibling tools like ssh_ls, though the 'search' wording implies a find-like operation.
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 explains the motivation—avoiding manual find syntax—which gives a reason to use it. But it doesn't explicitly state when to use this tool vs alternatives like ssh_exec for ad-hoc commands or ssh_ls for simple directory listings. There's no mention of when not to use it, leaving the decision partly implicit.
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") | |
| user | No | SSH user for the git host (default: "git") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It states that it verifies SSH key registration and working auth, which implies a read-only diagnostic action. However, it doesn't disclose expected outcomes, error behaviors, or any side effects (like network calls) beyond the implied test. Adequate but not rich; a 3 reflects that it conveys the core purpose without going into behavioral detail.
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 highly informative and front-loaded. The first sentence defines the tool's function, the second gives a concrete usage scenario. There is no redundant wording or repetition of schema info, making it exceptionally concise and well-structured 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?
For a simple tool with two optional parameters, no output schema, and no nested objects, the description covers the essential aspects: what it tests and when to use it. It doesn't mention that it only performs the SSH handshake (not full Git operations) or that the agent must have a key loaded—but those are covered by sibling tools (e.g., ssh_agent_ensure) and are reasonable to omit. The description is complete enough for an agent to call the tool correctly in the described context.
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% description coverage for both parameters (host and user), each with clear descriptions and defaults. The tool description does not add extra meaning to these parameters, so it relies on the schema. Per the rubric, with high schema coverage, a baseline of 3 is appropriate; the description adds no significant parameter-related value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Test') and resource ('Git-over-SSH authentication'), and names a clear scope (hosting providers like GitHub, GitLab, Bitbucket). It clearly distinguishes this from sibling tools like ssh_test (generic connectivity) or ssh_known_hosts_fix (host key issues), so an agent can quickly tell what this tool is for.
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 provides a clear, actionable context for when to invoke the tool. It doesn't explicitly mention alternatives, but the trigger is specific enough to guide selection among the many ssh siblings, so it earns a 4 rather than a 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states what the tool returns (type, fingerprint, loaded status), making its behavior transparent. It does not explicitly state that it is read-only, but the action 'list' and absence of side effects imply safety. No annotations are present, so the description carries the burden, which it meets adequately.
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 (two sentences), front-loads the primary action and output details, and includes a purposeful usage hint. There is no redundancy or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description adequately explains the returned fields. It does not cover edge cases (e.g., empty key directory) or error conditions, but for a simple listing tool, the context provided is sufficient for an agent to use 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 tool has zero parameters, so there is no parameter ambiguity. The description correctly omits any parameter details, and the schema aligns with this. No further explanation is needed.
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') and identifies the resource ('SSH private keys in ~/.ssh/') with clear attributes (type, fingerprint, loaded status). It distinguishes itself from sibling tools like ssh_key_load and ssh_agent_ensure by focusing solely on enumeration.
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 a clear use case: 'find which keys are available and which ones need to be loaded.' It implies when to use this tool (before loading keys) but does not explicitly state when not to use it (e.g., for loading or modifying keys). Still, the guidance is actionable and contextually relevant.
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.
| 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) | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| 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 must carry the full burden of behavioral disclosure. It states the operation uses SFTP but says nothing about return format (e.g., simple filenames vs. detailed info), whether hidden files are included, how errors like permission denied are handled, or whether it follows symlinks. This significant gap leaves the agent uncertain about the tool's 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 a single, effective sentence that conveys the core action and transport method with zero wasted words. It is front-loaded and easy to parse, making it exemplary in 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?
The tool has six parameters, no output schema, and no annotations. The description only covers the basic action and leaves out critical details such as the expected output shape (is it just names or also metadata?), the behavior for non-existent paths, and any permission or authentication requirements beyond the schema's parameter notes. Given these gaps, the description is not sufficiently complete for an agent to invoke this tool with full 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%, so all six parameters (host, path, port, username, credential_id, privateKeyPath) are already documented with meaningful descriptions. The tool description adds no extra parameter-specific semantics beyond the SFTP context, which is marginal. Per the baseline for high schema coverage, a 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 specific verb 'List' and a clear resource 'files in a directory on a remote host', and specifies the method 'via SFTP'. This unambiguously distinguishes it from siblings like ssh_read_file (reads file content) and ssh_stat (checks file metadata). The purpose is immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to list directory contents on a remote host), but it does not explicitly contrast with alternatives such as ssh_exec (which could run 'ls') or provide when-not-to-use guidance. The usage context is implicitly clear but not explicitly differentiated from other SSH tools.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| path | Yes | Absolute path of the directory to create | |
| port | No | SSH port (default: 22) | |
| username | No | SSH username (default: current user) | |
| recursive | No | Create parent directories as needed (default: false). Like `mkdir -p`. | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the behavioral burden. It discloses the non-obvious mkdir -p semantics clearly: existing intermediate directories are tolerated while an existing leaf path remains an error. It could also mention authentication expectations or result/error reporting, but the most important behavioral nuances 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?
Two focused sentences earn their place: the core operation comes first, and the second sentence explains the one flag that materially changes behavior. The code-style formatting is precise and the description contains 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?
The core operation, the important flag, and the key error semantics are all present, and the schema fully covers every parameter. The description could be more explicit about which authentication path to use or what the success/error return looks like, but the tool is simple enough that an agent can invoke it correctly with current information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all seven parameters at 100% coverage, so the baseline is 3. The description adds value by clarifying the recursive behavior beyond the schema, especially the tolerated-intermediate-dirs vs valid-leaf distinction. This pushes it slightly above baseline.
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 starts with a specific action and resource: create a directory on a remote host via SFTP. This clearly distinguishes it from sibling read, write, list, and transfer tools without requiring the agent to inspect 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 practical guidance for the recursive flag and explains important edge-case behavior, which implies the intended use. However, it never explicitly compares this to alternatives such as using ssh_exec for mkdir, so the when-to-use-vs-sibling guidance is only implied.
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. Returns results per host. Use this instead of calling ssh_exec multiple times — it's faster and shows results side by side. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once before fan-out).
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Command timeout in milliseconds (default: 30000) | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| 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 full burden of behavioral disclosure. It transparently surfaces parallel execution, the policy whitelist/blacklist check performed once, and the command execution nature. It does not warn about potential destructive side effects of the executed command itself, but this is inherent to a command execution tool and somewhat self-evident; the policy note is a valuable 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?
Three concise sentences, each earning its place: the purpose, the usage guidance, and the policy caveat. Information is front-loaded and easily scannable with no redundancy 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?
With 7 parameters fully documented in the schema and no output schema present, the description covers the essential decision points: what it does, when to use it over the alternative, and the policy constraint. Could elaborate on result structure, but 'results per host' suffices for a command fan-out tool. Comprehensive enough for selection and 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 parameters are already well-documented in the JSON schema. The tool description adds no additional parameter semantics beyond restating the command and hosts concepts. Per guidelines, this lands at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Execute' with resource 'command on multiple remote hosts in parallel', clearly distinguishing from sibling ssh_exec that targets a single host. The alternative is explicitly named once, resolving ambiguity 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?
Explicitly instructs to use this tool 'instead of calling ssh_exec multiple times,' and gives a concrete rationale (faster, side-by-side results). This directly aids tool selection among the large sibling set.
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.
| 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) | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose side effects, return format, or potential failure modes. It only states the operation without indicating whether the file content is returned or any other behavioral details.
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 a single, concise sentence with no redundant or filler content. It efficiently conveys the core functionality without unnecessary verbosity.
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 lacks important contextual details such as the output format (e.g., file content) and any limitations (e.g., textual vs binary, encoding). It does not explain the behavior in enough depth for a user to fully understand the tool's usage without additional inference.
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 complete descriptions for all parameters (host, path, port, username, credential_id, privateKeyPath), so coverage is high. The description adds no additional semantic meaning beyond the schema, which is acceptable given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Read') and the resource ('a file from a remote host via SFTP'), clearly distinguishing it from sibling tools like ssh_write_file or ssh_download.
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 provide any guidance on when to use this tool versus alternatives such as ssh_download or ssh_cat. It lacks context on criteria for choosing this over similar operations.
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) | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation but does not explicitly state side effects, permission requirements, or failure modes. It mentions using systemctl indirectly but lacks details on potential errors (e.g., service not found) or the need for sudo. Given no annotations, this is a moderate level of transparency.
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 to the point. It states purpose, return content, and usage guidance without unnecessary elaboration. Every sentence carries meaningful information, making it highly efficient.
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 adequately covers the tool's function and return fields, and it provides a usage note regarding alternatives. It does not explain edge cases like missing services or privilege requirements, but for a simple status check, this is largely sufficient. The lack of an output schema is mitigated by the return description.
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?
All parameters are described in the schema with adequate detail, so the description adds no additional parameter semantics. The schema covers host, service, timeout, etc., and the tool description does not clarify or enhance these. This aligns with the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: checking the status of a systemd service on a remote host. It specifies the return value (active state, PID, uptime, description) and differentiates it from related tools like ssh_exec. This leaves no ambiguity about what the tool does.
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 instructs to use this tool instead of ssh_exec with systemctl, providing a direct alternative and a clear condition for selection. This guides the agent on when to choose this tool over others in the sibling set.
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 type flags (isFile, isDirectory, isSymbolicLink). Use this instead of parsing ls -la output.
| 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) | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| 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 full burden of transparency. It implies a read-only operation but does not explicitly state there are no side effects, nor does it describe error handling, authentication failures, or path existence checks. The description is honest about what it does but lacks detail on edge cases.
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, consisting of two sentences: one stating the primary function and return fields, and a second providing a practical comparison against parsing `ls -la`. It is well-structured and avoids unnecessary verbosity.
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 absence of an output schema, the description adequately lists the returned metadata fields. It also provides a usage context (instead of parsing `ls -la`). However, it does not mention error scenarios (e.g., file not found), symlink behavior, or whether authentication is required beyond the parameters, leaving minor gaps in completeness.
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 descriptions for all six parameters, covering host, path, port, username, credential_id, and privateKeyPath. The description adds useful constraints like 'Must start with /' for path and 'Never pass a real password here' for credential_id, enhancing clarity beyond basic schema definitions.
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 retrieves metadata for a file or directory on a remote host via SFTP, and it specifically names the returned fields (size, permissions, uid/gid, mtime/atime, type flags). It also distinguishes itself from alternative approaches by advising against parsing `ls -la` output, making the 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 explicitly recommends using this tool instead of parsing `ls -la` output, giving a clear context for when it is appropriate. It does not explicitly mention sibling tools like ssh_ls or ssh_read_file, but the guidance is sufficient for a typical use case.
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) | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| 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 full behavioral burden. The verb 'read' and the tail/grep semantics imply a read-only operation, but the description does not disclose SSH authentication expectations (credential_id vs privateKeyPath vs username), failure behavior on missing files or unreachable hosts, or the fact that all non-required params have defaults. The schema partially compensates by documenting each parameter, including the security warning on credential_id.
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 zero filler: the first states the operation, the second gives the recommended use case and the alternative to avoid. The core purpose is front-loaded and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex tool with 9 parameters, no annotations, and no output schema, the description covers the core behavior and primary use case while the schema thoroughly documents all parameters, including secure handling of credential_id. It does not hint at the return format since no output schema exists, but that gap is minor for a straightforward read-only tail 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%, so the schema already documents every parameter including defaults, giving a baseline of 3. The description reinforces the mapping of 'last N lines' to the lines parameter and 'grep pattern' to the grep parameter, but adds no meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read'), a resource ('file on a remote host'), and quantifies the behavior ('last N lines' with optional 'grep pattern' filtering). It explicitly differentiates itself from ssh_exec by noting it should be used 'instead of ssh_exec with manual tail/grep commands,' so an agent can select 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 second sentence provides actionable context: use this for 'reading log files' and names the alternative to avoid ('ssh_exec with manual tail/grep commands'). However, it does not state exclusions such as whole-file reads (which would route to ssh_read_file) or live-following scenarios, so the guidance is clear but not exhaustive.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | SSH hostname or IP address | |
| port | No | SSH port (default: 22) | |
| 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 /. | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| 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 mentions SFTP, which is useful, but it does not reveal authentication requirements, whether remote directories are created, overwrite behavior, or any side effects of the transfer.
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 a single, front-loaded sentence with no filler. It conveys the core action and protocol efficiently, making it easy to scan and understand.
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 a rich 7-parameter schema, the description gives only minimal context. It omits important operational details such as credential handling, required authentication method, transfer behavior, and expected output, which are not covered elsewhere since no output schema or annotations exist.
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 little beyond mapping local file to localPath and remote host to remotePath, which is expected given the schema already explains each parameter.
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 (Upload), the object (a local file), and destination (remote host via SFTP). It is unambiguous and self-contained, though it does not explicitly distinguish itself from sibling tools like ssh_write_file or ssh_download.
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 the tool is for transferring a local file to a remote host, which conveys basic usage context. However, it does not mention when to prefer this over alternatives such as ssh_write_file for writing remote content directly, nor any exclusions.
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.
| 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 | |
| username | No | SSH username (default: current user) | |
| credential_id | No | Alias of an SSH password configured only on the MCP server (for example, ssh1 resolves to SSH_CREDENTIAL_SSH1). Never pass a real password here. | |
| privateKeyPath | No | Path to SSH private key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly notes that the tool creates or overwrites the file, a key behavioral trait. It does not mention error handling or permissions, but the overwrite behavior is clearly disclosed.
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, using only two sentences to convey the essential information without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write operation, the description is complete enough. It does not explicitly mention return values, but given no output schema and the basic nature, this is acceptable. The overwrite behavior is the key contextual detail and is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions, so the baseline is 3. The tool description adds no additional meaning beyond the schema's parameter descriptions.
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 writes a file via SFTP, distinguishing it from sibling tools like read, upload, and execute.
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 explicit guidance on when to use this tool versus alternatives (e.g., when to prefer this over ssh_upload or ssh_exec). The description lacks any mention of use cases or cautions.
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.14.3ssh_agent_ensuressh_config_lookupssh_deletessh_diagnosessh_downloadssh_execssh_findssh_git_checkssh_key_listssh_key_loadssh_known_hosts_fixssh_lsssh_mkdirssh_multi_execssh_read_filessh_service_statusssh_statssh_tailssh_testssh_uploadssh_write_fileScored across 21 tools
Every tool has a clearly defined purpose: execution, file transfer, metadata, diagnostics, key/agent management, and specialized helpers like git_check and service_status. Potential overlaps (e.g., ssh_test vs ssh_diagnose) are explicitly differentiated by speed and depth.
All tools share the ssh_ prefix and mostly follow a verb-noun pattern (ssh_read_file, ssh_write_file, ssh_upload, ssh_mkdir). A few deviate slightly, like ssh_known_hosts_fix and ssh_service_status, but the overall convention remains predictable.
21 tools is somewhat high for most servers, but the SSH domain genuinely spans execution, SFTP, key management, agent management, diagnostics, and networking. Each tool appears to justify its inclusion, though a few edge-case utilities feel additive.
The toolset covers the core lifecycle of SSH operations: connection, command exec, file transfer, diagnostics, key loading, and service status checking. Minor gaps exist, such as no remote file move/rename or permission change tool, but these are likely outside the primary scope because ssh_exec can handle them.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
SSH into your Linux server, home lab, VPS, or Proxmox machine from Claude or ChatGPT — no port forwarding, no VPN. Run shell commands, read files, tail logs, and manage processes directly from chat. One-command setup. 5-day free trial, no card required.
Manage servers through SSH.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
