Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-ssh Run 'df -h' on myserver"
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.
Alternative version: mcp-ssh-tmux.
Uses tmux for improved persistence, observability, and a superior "LLM-as-Observer" approach.
An MCP (Model Context Protocol) server that enables AI agents to establish and manage persistent SSH sessions.
Smart Command Execution: Never hangs the server - automatically transitions to async mode if timeout is reached
Persistent Sessions: SSH connections are reused across multiple command executions
Async Command Execution: Non-blocking execution for long-running commands
SSH Config Support: Automatically reads and uses settings from ~/.ssh/config
Multi-host Support: Manage connections to multiple hosts simultaneously
Automatic Reconnection: Dead connections are detected and automatically re-established
Thread-safe: Safe for concurrent operations
Network Device Support: Automatic enable mode handling for routers and switches
Sudo Support: Automatic password handling for sudo commands on Unix/Linux hosts
File Operations: Safe helpers to read and write remote files over SFTP
Command Interruption: Send Ctrl+C to interrupt running commands
Related MCP server: SSH MCP Server
The package is published on PyPI as mcp-ssh.
uvxuvx mcp-sshFor a persistent local installation:
uv tool install mcp-sshThis installs both mcp-ssh and the backward-compatible
mcp-ssh-session command.
Add to your ~/.claude.json:
{
"mcpServers": {
"ssh-session": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-ssh"],
"env": {}
}
}
}npx @modelcontextprotocol/inspector uvx mcp-sshuv venv
source .venv/bin/activate
uv pip install -e .execute_commandExecute a command on an SSH host using a persistent session.
Smart Execution: Starts synchronously and waits for completion. If timeout is reached, automatically transitions to async mode and returns a command ID. Server never hangs!
Advanced Features:
Automatic timeout handling with async transition
Interactive command support (use send_input for prompts)
Command interruption capability (interrupt_command_by_id)
Session persistence across multiple commands
Using SSH config alias:
{
"host": "myserver",
"command": "uptime"
}Using explicit parameters:
{
"host": "example.com",
"username": "user",
"command": "ls -la",
"key_filename": "~/.ssh/id_rsa",
"port": 22
}Network device with enable mode:
{
"host": "router.example.com",
"username": "admin",
"password": "ssh_password",
"enable_password": "enable_password",
"command": "show running-config"
}Unix/Linux with sudo:
{
"host": "server.example.com",
"username": "user",
"sudo_password": "user_password",
"command": "systemctl restart nginx"
}list_sessionsList all active SSH sessions.
close_sessionClose a specific SSH session.
{
"host": "myserver"
}close_all_sessionsClose all active SSH sessions.
execute_command_asyncExecute a command asynchronously without blocking the server. Returns a command ID for tracking.
Use with companion tools:
get_command_status(command_id) - Check progress and retrieve output
interrupt_command_by_id(command_id) - Send Ctrl+C to stop execution
send_input(command_id, text) - Provide input to interactive commands
{
"host": "myserver",
"command": "sleep 60 && echo 'Done'",
"timeout": 300
}get_command_statusGet the status and output of an async command.
{
"command_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}interrupt_command_by_idInterrupt a running async command by sending Ctrl+C.
{
"command_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}list_running_commandsList all currently running async commands.
list_command_historyList recent command history (completed, failed, interrupted commands).
{
"limit": 50
}read_fileRead the contents of a remote file via SFTP, with optional sudo support.
Basic usage:
{
"host": "myserver",
"remote_path": "/etc/nginx/nginx.conf",
"max_bytes": 131072
}With passwordless sudo (NOPASSWD in sudoers):
{
"host": "myserver",
"remote_path": "/etc/shadow",
"use_sudo": true
}With sudo password:
{
"host": "myserver",
"remote_path": "/etc/shadow",
"sudo_password": "user_password"
}Attempts SFTP first for best performance
Falls back to sudo cat via shell if permission denied and use_sudo=true or sudo_password provided
Supports both passwordless sudo (NOPASSWD) and password-based sudo
Enforces a 2 MB maximum per request (configurable per call up to that limit)
Returns truncated notice when the content size exceeds the requested limit
write_fileWrite text content to a remote file via SFTP, with optional sudo support.
Basic usage:
{
"host": "myserver",
"remote_path": "/tmp/app.env",
"content": "DEBUG=true\n",
"append": true,
"make_dirs": true
}With passwordless sudo (NOPASSWD in sudoers):
{
"host": "myserver",
"remote_path": "/etc/nginx/nginx.conf",
"content": "server { ... }",
"use_sudo": true,
"permissions": 420
}With sudo password:
{
"host": "myserver",
"remote_path": "/etc/nginx/nginx.conf",
"content": "server { ... }",
"sudo_password": "user_password",
"permissions": 420
}Uses SFTP when use_sudo=false and no sudo_password provided
Uses sudo tee via shell when use_sudo=true or sudo_password is provided
Supports both passwordless sudo (NOPASSWD) and password-based sudo
Content larger than 2 MB is rejected for safety
Optional append mode to add to existing files
Optional make_dirs flag will create missing parent directories
Supports permissions to set octal file modes after write (e.g., 420 for 0644)
Note: Shell fallback is slower than SFTP but enables writing to protected files
The server automatically reads ~/.ssh/config and supports:
Host aliases
Hostname mappings
Port configurations
User specifications
IdentityFile settings
Example ~/.ssh/config:
Host myserver
HostName example.com
User myuser
Port 2222
IdentityFile ~/.ssh/id_rsaThen simply use:
{
"host": "myserver",
"command": "uptime"
}For production environments where AI agents should not have access to real credentials, you can use environment variables to override connection parameters. This allows agents to use simple aliases while real credentials are stored securely in the MCP server configuration.
Use case: Hide real hostnames, IPs, usernames, and passwords from AI agents while still allowing them to manage production servers.
Variable | Description |
| Real hostname or IP address |
| SSH port (default: 22) |
| SSH username |
| SSH password |
| Path to SSH private key file |
| Sudo password |
| Enable password for network devices (routers/switches) |
Claude Desktop config (~/.claude.json):
{
"mcpServers": {
"ssh-session": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-ssh"],
"env": {
"OVRD_prod_db_HOST": "192.168.1.100",
"OVRD_prod_db_USER": "admin",
"OVRD_prod_db_PASS": "secret_password",
"OVRD_prod_db_SUDO_PASS": "sudo_password"
}
}
}
}Agent uses the alias (knows nothing about real credentials):
{
"host": "prod_db",
"command": "systemctl status postgresql"
}System resolves to real credentials:
Host: prod_db → 192.168.1.100
User: (from env) → admin
Password: (from env) → secret_password
Fully backward compatible - works without environment variables
The agent sees only the alias (prod_db), not the real IP
Credentials never appear in the AI context
Works with all tools: execute_command, read_file, write_file, etc.
Commands execute in persistent interactive shells that maintain state:
Current directory persists across commands (cd /tmp stays in /tmp)
Environment variables remain set
Shell history is maintained
On Unix-like shells, including BusyBox ash and OpenWrt, each command is
followed by a unique sentinel that includes its exit status. This avoids
guessing completion from prompts such as root@OpenWrt:/#.
Prompt detection remains available for network devices and interactive states that cannot use a POSIX shell sentinel. Idle detection is used only as a fallback while waiting for prompt or interactive-state changes.
Completion signals include:
Sentinel detected: Reliable completion and exit status for Unix, BusyBox, and OpenWrt shells
Prompt detected: Completion for routers, switches, and other non-POSIX targets
Interactive state detected: Password, confirmation, editor, or pager handling
Idle handling: After two seconds without output, the server checks the sentinel, prompt, and interactive state again. Silence alone does not complete a sentinel-enabled command.
Long-running commands: The idle timer resets every time new output arrives, so builds or scripts that output sporadically continue running until naturally complete or the overall timeout is reached.
ASYNC_COMMANDS.md - Smart execution and async commands
Distributed under the MIT License. See LICENSE for details.
Close all active SSH sessions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It fails to mention that this is a bulk destructive action, that it will kill all sessions including those with running commands, or that it is irreversible. This is a significant gap for a potentially disruptive 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?
The description is a single, clear sentence: 'Close all active SSH sessions.' It contains no extraneous words or repetition, and the critical information (action + scope) is front-loaded and immediately comprehensible.
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 no-parameter tool, the description is mostly complete in stating what it does. However, given its destructive nature and the presence of a safer sibling tool (close_session), the description should mention the broader impact (e.g., closing all sessions, potentially interrupting running commands) and guide users toward the appropriate tool for single-session closures. Without this, the completeness is adequate but has clear gaps.
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, and the input schema is an empty object. Per the rubric, a baseline of 4 is appropriate when there are 0 parameters, as there is nothing for the description to add beyond the schema. The description correctly implies no parameters are 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 'Close all active SSH sessions' uses a specific verb (close) and resource (all active SSH sessions), clearly distinguishing it from the sibling tool close_session, which handles a single session. The word 'all' makes the scope explicit 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?
The description implies usage: use this tool when you need to close every active SSH session, rather than a specific one. However, it does not explicitly mention alternatives like close_session or provide any when-to-use/when-not-to-use guidance. The context from the sibling list helps, but the description itself lacks explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close a specific SSH session.
The host parameter can be either a hostname/IP or an SSH config alias.
Args: host: Hostname, IP address, or SSH config alias username: SSH username (optional, will use SSH config or current user) port: SSH port (optional, will use SSH config or default 22)
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| port | No | ||
| username | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 useful behavioral details about parameter resolution (e.g., 'will use SSH config or current user' and 'default 22'). However, it does not mention side effects of closing a session (e.g., impact on running processes) or how errors are handled if the host is not found. For a destructive operation, more behavioral context would be beneficial.
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 with a brief intro and an Args list. However, there is redundancy: the host explanation is repeated both in the prose and in the Args entry. This is a minor inefficiency, but the overall length is appropriate and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple tool with 3 parameters and an output schema, the description covers the essential aspects: purpose, parameter semantics, and defaults. It lacks edge-case behavior such as behavior when the host does not match an existing session, but it does not need to explain return values since an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining each parameter with concrete meaning and defaults. It clarifies that host can be a hostname/IP or alias, username is optional and falls back to SSH config or current user, and port defaults to SSH config or 22. This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb-resource pair: 'Close a specific SSH session.' It specifies the exact scope (specific vs all sessions) and distinguishes itself from close_all_sessions. The mention of 'SSH session' clearly identifies the resource being acted on.
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 that this tool targets a single SSH session, implying it is for per-session management. However, it does not explicitly mention alternatives or when not to use it, such as 'use close_all_sessions to close multiple sessions at once.'
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 an SSH host using a persistent session.
Starts synchronously and waits for completion. If the command doesn't complete within the timeout, it automatically transitions to async mode and returns a command ID for tracking.
The host parameter can be either a hostname/IP or an SSH config alias. If an SSH config alias is provided, configuration will be read from ~/.ssh/config.
For network devices (routers, switches), use enable_password to automatically enter privileged/enable mode before executing commands.
For Unix/Linux hosts requiring sudo, use sudo_password to automatically handle the sudo password prompt. The command will be automatically prefixed with 'sudo' if not already present.
Advanced Features:
Automatic timeout handling with async transition
Interactive command support with input capability
Command interruption (Ctrl+C) for stuck processes
Session persistence across multiple commands
Args: host: Hostname, IP address, or SSH config alias (e.g., "myserver") command: Command to execute username: SSH username (optional, will use SSH config or current user) password: Password (optional) key_filename: Path to SSH key file (optional, will use SSH config) port: SSH port (optional, will use SSH config or default 22) enable_password: Enable mode password for network devices (optional) enable_command: Command to enter enable mode (default: "enable") sudo_password: Password for sudo commands on Unix/Linux hosts (optional) timeout: Timeout in seconds for command execution (default: 30)
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| port | No | ||
| command | Yes | ||
| timeout | No | ||
| password | No | ||
| username | No | ||
| key_filename | No | ||
| sudo_password | No | ||
| enable_command | No | enable | |
| enable_password | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does an excellent job. It discloses automatic async transition after timeout, automatic sudo prefixing, enable mode entry, session persistence, interactive input support, and command interruption. All these are behavioral traits beyond the input schema and are highly relevant for safe and correct invocation.
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 with a front-loaded summary, detailed paragraphs, and a bulleted 'Advanced Features' list. It is somewhat long but every section adds necessary detail for a tool with 10 parameters. Minor redundancy exists between the initial paragraphs and the advanced features list, but overall it is appropriately sized and organized.
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 comprehensive for a complex tool: it covers all parameters, device-specific behaviors, timeout handling, and advanced features. An output schema exists, so return value details are not required. Given no annotations and high complexity, the description fully equips an agent to use 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?
The schema provides 0% description coverage for parameters, but the description lists all 10 parameters with clear meanings, defaults, and examples (e.g., host as 'myserver', timeout default 30). It adds substantial value beyond the bare schema, fully compensating for the lack of schema-level 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 'Execute a command on an SSH host using a persistent session', which is a specific verb+resource. It distinguishes itself from the sibling execute_command_async by explaining the synchronous start and async transition behavior, making its unique role 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 provides usage context for different scenarios: using enable_password for network devices, sudo_password for Unix/Linux hosts, and handling SSH config aliases. It does not explicitly mention alternatives like execute_command_async for non-blocking execution, but the async transition behavior implies when the async sibling would be relevant. Thus it gives clear context but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a command asynchronously without blocking the server.
Returns a command ID that can be used to check status, retrieve output, or interrupt. Useful for long-running commands like 'sleep 60', monitoring tasks, or large operations.
Use with companion tools:
get_command_status(command_id) to check progress and retrieve output
interrupt_command_by_id(command_id) to send Ctrl+C and stop execution
send_input(command_id, text) to provide input to interactive commands
Args: host: Hostname, IP address, or SSH config alias command: Command to execute username: SSH username (optional) password: SSH password (optional) key_filename: Path to SSH key file (optional) port: SSH port (optional) timeout: Maximum execution time in seconds (default: 300)
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| port | No | ||
| command | Yes | ||
| timeout | No | ||
| password | No | ||
| username | No | ||
| key_filename | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 discloses the non-blocking behavior, return of a command ID, and the timeout parameter. However, it does not mention potential side effects, session requirements, or failure modes. Still, for an async execution tool, the core behaviors are well covered; the only minor gap is a lack of detail on output retrieval specifics.
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 with a clear opening statement, a short list of companion tools, and an Args section. It is front-loaded with the most important information (async behavior and command ID). Every sentence contributes value, and the length is appropriate for the complexity of 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 tool with 7 parameters, no annotations, and an output schema (which handles return value structure), the description is exceptionally complete. It covers the async nature, the command ID as the return mechanism, and all parameters. The companion tool references also round out the operational context, making the tool fully understandable.
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 0%, so the description must compensate. The description includes an explicit Args section that describes every parameter (host, command, username, password, key_filename, port, timeout) in plain language. This fully bridges the gap left by the schema, providing meaning beyond the raw property names.
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: 'Execute a command asynchronously without blocking the server.' It specifies the key output (a command ID) and differentiates itself from synchronous execution by highlighting the async behavior. This distinguishes it from the sibling 'execute_command' 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?
The description provides explicit usage context: 'Useful for long-running commands like sleep 60, monitoring tasks, or large operations.' It also lists companion tools (get_command_status, interrupt_command_by_id, send_input) with their purposes, giving clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the status and output of an async command.
Args: command_id: The command ID returned by execute_command_async
| Name | Required | Description | Default |
|---|---|---|---|
| command_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must carry the burden of disclosing behavioral traits. 'Get' implies a read-only operation, but the description doesn't explicitly state it's non-destructive or explain polling behavior or error conditions. It adds the fact that it returns output, but minimal extra context 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 sentences, front-loaded with the primary purpose, and includes a clear Args section. Every sentence earns its place, with no fluff or unnecessary 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 one-parameter tool with an output schema present, the description is adequate: it states what the tool does and where the parameter comes from. It doesn't explicitly detail polling behavior or when the command completes, but the output schema likely covers return values, making it 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?
The description explains that the command_id is the one returned by execute_command_async, which adds meaningful context beyond the schema's bare type definition. With schema coverage at 0%, this description fully compensates, making the parameter's purpose and origin clear.
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 the status and output of an async command, which is a specific verb+resource. It distinguishes itself from siblings by focusing on async commands and explicitly mentioning the command ID source, so the 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 after execute_command_async by specifying that the command_id comes from that tool. This gives clear context, though it doesn't explicitly mention alternatives or when-not-to-use, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Interrupt a running async command by sending Ctrl+C.
Args: command_id: The command ID returned by execute_command_async
| Name | Required | Description | Default |
|---|---|---|---|
| command_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 states the action (sends Ctrl+C) but fails to disclose effects like whether the command is forcibly terminated, what happens if the command ID is invalid or already finished, or whether the operation is reversible. This lack of edge-case behavior is a significant gap.
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) and front-loads the main action before explaining the argument. The Args section adds necessary detail without redundancy, and 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?
For a simple one-parameter tool operating on running async commands, the description covers the core purpose and parameter source. However, it lacks information about failure modes or state transitions (e.g., how the command status changes), and with no annotations, it does not fully prepare the agent for exceptional cases. An output schema exists, so return values are not necessary, but behavioral edge cases remain incomplete.
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 only defines command_id as a string with no description. The description adds essential context by specifying it is 'The command ID returned by execute_command_async', directly telling the agent where to obtain the value. This fully compensates for the 0% 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 states a specific verb ('Interrupt') with a clear resource ('a running async command') and mechanism ('by sending Ctrl+C'). This unambiguously distinguishes it from sibling tools like send_input or execute_command_async, making its purpose 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 usage context is implied ('Interrupt a running async command'), and the mention of 'command ID returned by execute_command_async' hints at when it's appropriate. However, there is no explicit guidance on when not to use it or alternatives for cancellation, such as sending Ctrl+C directly to a session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent command history (completed, failed, interrupted commands).
Args: limit: Maximum number of commands to return (default: 50)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the types of commands included (completed, failed, interrupted), which is useful. However, it does not explicitly state the tool is read-only, mention sorting or ordering, or clarify whether the history is session-specific or global, leaving some 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?
The description is concise: a single sentence defining the purpose plus a brief Arg spec for the only parameter. Every word contributes value, and the structure is front-loaded with the main purpose.
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 core functionality and the limit parameter. The presence of an output schema (indicated by context signals) likely covers return values. The main gap is the lack of session scope context, but overall the description is adequate for the tool's simplicity.
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 only provides the type and default for limit. The description adds meaning by explaining 'Maximum number of commands to return (default: 50)', which compensates for the schema's lack of description and helps the agent understand the parameter's purpose.
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 lists recent command history, specifying completed, failed, and interrupted commands. This distinguishes it from siblings like list_sessions and list_running_commands by focusing on past commands.
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 usage is implied through the description and tool name: the agent can infer this is for viewing past commands. However, there is no explicit guidance on when to use this vs. alternatives (e.g., list_running_commands for active commands) or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all currently running async commands.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It only states that the tool lists running async commands, with no detail on output format, scope (session-wide or global), authentication needs, or side effects. Since it is a list operation, it is likely read-only, but that is not 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 a single concise sentence with no wasted words. It is immediately clear and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters and has an output schema, so return values are accounted for. However, the description lacks behavioral context and usage differentiation, leaving some ambiguity about its role relative to sibling tools.
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 and schema coverage is 100%, so the baseline is 4. The description adds no parameter details because there are none to describe.
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 the specific verb 'List' and identifies the resource as 'currently running async commands', clearly distinguishing from siblings like list_command_history (past commands) and list_sessions (sessions). This is a specific and unambiguous purpose statement.
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 when/when-not guidance or alternative tool references are provided. Usage is implied by the name and description (e.g., use this to see currently active async commands), but there is no direct mention of when to prefer this over list_command_history or get_command_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active SSH sessions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral details such as read-only safety, authentication requirements, or what information is returned. It simply states the action without any side-effect 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 a single, concise sentence that front-loads the verb and resource. There is no unnecessary information, making it appropriately sized and 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?
For a simple parameterless list operation with an output schema, the description sufficiently captures scope ('all active SSH sessions'). It lacks some context about session ordering or metadata, but the output schema likely covers returned details.
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 schema fully covers parameter semantics. The description adds no parameter details, but none are needed; baseline 4 applies for parameterless tools.
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 uses the verb 'list' and specifies the resource 'active SSH sessions,' making the purpose unambiguous. It stands apart from sibling tools that create, close, or manipulate sessions.
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 offers no guidance on when to use this tool versus alternatives like close_session or execute_command. It only states what it does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a remote file over SSH.
Attempts to read using SFTP first. If permission is denied and use_sudo is True or sudo_password is provided, falls back to using 'sudo cat' via shell command.
Args: host: Hostname, IP address, or SSH config alias remote_path: Path to the remote file username: SSH username (optional) password: SSH password (optional) key_filename: Path to SSH key file (optional) port: SSH port (optional) encoding: Text encoding (default: utf-8) errors: Error handling for decoding (default: replace) max_bytes: Maximum bytes to read (default: 2MB) sudo_password: Password for sudo (optional, not needed if NOPASSWD configured) use_sudo: Use sudo for reading (tries passwordless if no sudo_password provided)
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| port | No | ||
| errors | No | replace | |
| encoding | No | utf-8 | |
| password | No | ||
| use_sudo | No | ||
| username | No | ||
| max_bytes | No | ||
| remote_path | Yes | ||
| key_filename | No | ||
| sudo_password | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that reading attempts SFTP first, falls back to 'sudo cat' under specific conditions, and mentions the max_bytes limit. This goes beyond a simple 'read file' and provides meaningful behavioral context. Missing details like error types or connection handling but adequate for a read 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?
The description is front-loaded with a clear one-sentence purpose, followed by an Args list that is necessary given 11 parameters. Each line earns its place, though the list is lengthy. It is structured and readable, not tautological.
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 complexity (11 params, 0% schema coverage, no annotations), the description is quite complete. It covers all parameters, defaults, and the sudo fallback behavior. Since an output schema exists, return value documentation isn't required. It doesn't mention failure modes or timeouts, but overall it provides sufficient 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 description coverage is 0%, so the description is the sole source of parameter clarity. The Args section explains each parameter, including host as 'Hostname, IP address, or SSH config alias', sudo_password behavior, max_bytes default (2MB), and encoding/errors. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read a remote file over SSH' — a specific verb (read) plus a resource (remote file) that distinguishes it from siblings like write_file and execute_command. The fallback mechanism is also described, reinforcing the read-only purpose.
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: use this tool to read remote files. It doesn't explicitly name alternatives or exclusions, but the purpose is obvious from the first line. The fallback logic is described, so the agent understands when sudo will be used. However, no explicit 'when-not' or alternative tool references are present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the terminal screen state for a session.
Returns the current screen content from the terminal emulator, including cursor position. Only works when MCP_SSH_INTERACTIVE_MODE=1 is set.
Args: host: Hostname, IP address, or SSH config alias username: SSH username (optional, will use SSH config or current user) port: SSH port (optional, will use SSH config or default 22) max_lines: Maximum number of lines to return (default: 24)
Returns: JSON string with screen lines, cursor position, and dimensions
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| port | No | ||
| username | No | ||
| max_lines | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 reveals the tool is a read operation, requires interactive mode, supports a max_lines truncation, and returns a JSON structure with lines, cursor position, and dimensions. While it doesn't cover all error scenarios, it provides substantial behavioral context beyond just the operation 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 tightly organized with a brief summary, an Args list, and a Returns note. Each sentence and parameter explanation serves a purpose, with no redundant or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, prerequisite, parameters, and return type, which is sufficient for an agent to select and invoke it. It doesn't discuss error handling or inactive session behavior, but given the output schema exists and the operation is straightforward, this is not a severe 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 0%, so the description compensates fully by explaining each parameter's meaning: host accepts hostname/IP/alias, username falls back to config/current user, port uses config or default 22, and max_lines limits the output. This adds significant value beyond the bare schema types and defaults.
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 ('read') and resource ('terminal screen state for a session'), clearly distinguishing it from sibling tools like execute_command or read_file. It further clarifies that it returns screen content and cursor position, leaving no ambiguity about the tool's 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 provides clear context for when the tool is applicable by stating it 'Only works when MCP_SSH_INTERACTIVE_MODE=1 is set', giving a concrete prerequisite. It does not explicitly name alternative tools or when not to use it, but the purpose is self-evident from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send input to a running async command and return any new output.
Useful for interacting with commands that require user input, such as:
- Pagers (less, more): send 'q' to quit, space to page down
- Yes/no prompts: send 'y' or 'n'
- Interactive programs: send appropriate responses
Args:
command_id: The command ID to send input to
input_text: Text to send (e.g., 'q', 'y
', etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| command_id | Yes | ||
| input_text | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it returns any new output and provides input formatting examples including newline characters. However, with no annotations, it does not cover error behavior, prerequisites (e.g., command must be waiting for input), or potential side effects, leaving behavioral gaps.
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 with the purpose. The use-case list and Args section are concise and each line adds value 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 presence of an output schema and two simple parameters, the description covers the core functionality well. It does not mention what happens if the command_id is invalid or if the command is no longer running, but the overall context is sufficient for a straightforward 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?
Although the JSON schema lacks descriptions, the description includes an Args section explaining command_id and input_text, with concrete examples for input_text. This adds meaningful value beyond the bare schema, but could go deeper on encoding or expected format edge cases.
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 sends input to a running async command and returns new output. It distinguishes itself from siblings by specifying 'running async command' and by focusing on command_id versus session-based alternatives like send_input_by_session.
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 lists common scenarios (pagers, yes/no prompts, interactive programs) with concrete examples, making when to use the tool clear. However, it does not explicitly state when not to use it or mention alternatives like send_input_by_session for session-based interaction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send input to the active shell for a session.
Useful for clearing stuck interactive states or sending input to the current shell.
Args:
host: Hostname, IP address, or SSH config alias
input_text: Text to send (e.g., 'q
' to quit pager, '' for Ctrl+C) username: SSH username (optional) port: SSH port (optional)
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| port | No | ||
| username | No | ||
| input_text | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of explaining behavior. It gives concrete examples of input_text (e.g., 'q' to quit pager, Ctrl+C), which is helpful behavioral context. However, it does not disclose potential side effects, whether the command is asynchronous, or any prerequisites like an existing session. This is a moderate level of transparency for a simple send-input 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?
The description is concise: a one-sentence purpose, a short use-case line, and a compact parameter list. Every sentence contributes value, and the structure is easy to scan. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, an output schema (per context signals), and no annotations, the description covers the essential usage context: what the tool does, when to use it, and parameter meanings. It does not mention whether an active session must already exist or how errors are reported, but the core usage is clearly specified. Slight gaps in error/state prerequisites prevent a perfect score.
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 no property descriptions (0% coverage), so the description fully compensates by explaining each parameter in the Args section. It clarifies 'host' as 'Hostname, IP address, or SSH config alias', gives a concrete example for 'input_text', and marks 'username' and 'port' as optional. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send input to the active shell for a session', identifying a specific verb and resource. It also provides a use case ('clearing stuck interactive states'), but it does not explicitly distinguish itself from the closely named sibling 'send_input', so it loses a point for lack of direct sibling differentiation.
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 includes 'Useful for clearing stuck interactive states or sending input to the current shell', giving clear context for when to use the tool. However, it does not mention any alternatives or exclusions, such as when to prefer 'interrupt_command_by_id' or 'send_keys', so full usage guidance is not provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send special keys or key sequences to a session.
Supports special key tokens:
or : Send newline
or : Send escape key
: Send tab key
: Send Ctrl+C (interrupt)
: Send Ctrl+D (EOF)
: Send Ctrl+Z (suspend)
, , , : Arrow keys
: Space character
Regular text is sent as-is. Mix special keys with text: "helloworld"
Args: host: Hostname, IP address, or SSH config alias keys: Key sequence to send (e.g., "q", ":wq", "") username: SSH username (optional) port: SSH port (optional)
Returns: Success message
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| keys | Yes | ||
| port | No | ||
| username | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses supported key tokens, how regular text is handled, and the return type, but omits behavioral details such as whether an existing session is required, what happens on failure, or whether it blocks waiting for output. This is a moderate 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 description is well-structured: a clear purpose sentence, a useful list of key tokens, an illustrative example, and a concise args listing. Every sentence adds value, making it appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior and parameters, and with an output schema present, the return statement is sufficient. However, it does not clarify how the tool interacts with sessions (e.g., whether it requires an existing session or can create one), which is relevant given sibling tools like list_sessions. This gap lowers 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?
Schema description coverage is 0%, but the description compensates well: it explains each parameter (host, keys, username, port), provides examples for keys, and specifies that username and port are optional. This adds meaningful semantic value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send') with a clear resource ('special keys or key sequences to a session') and lists supported key tokens, distinguishing it from siblings like send_input by focusing on special key handling.
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 by detailing special key tokens and mixing text, but does not explicitly compare with sibling tools like send_input or send_input_by_session, nor state when not to use it. There is no explicit alternative guidance, so it falls short of a higher score.
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 remote file over SSH.
If use_sudo is True or sudo_password is provided, uses sudo via shell commands (tee). Otherwise, attempts to write using SFTP.
Args: host: Hostname, IP address, or SSH config alias remote_path: Path to the remote file content: Content to write username: SSH username (optional) password: SSH password (optional) key_filename: Path to SSH key file (optional) port: SSH port (optional) encoding: Text encoding (default: utf-8) errors: Error handling for encoding (default: strict) append: Append to file instead of overwriting (default: False) make_dirs: Create parent directories if they don't exist (default: False) permissions: Octal file permissions to set (e.g., 420 for 0644) max_bytes: Maximum bytes to write (default: 2MB) sudo_password: Password for sudo (optional, not needed if NOPASSWD configured) use_sudo: Use sudo for writing (tries passwordless if no sudo_password provided)
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| port | No | ||
| append | No | ||
| errors | No | strict | |
| content | Yes | ||
| encoding | No | utf-8 | |
| password | No | ||
| use_sudo | No | ||
| username | No | ||
| make_dirs | No | ||
| max_bytes | No | ||
| permissions | No | ||
| remote_path | Yes | ||
| key_filename | No | ||
| sudo_password | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 key behaviors: sudo usage conditions, SFTP fallback, append vs overwrite, directory creation, permission setting, and byte limit. It does not cover failure modes or error handling details, but the disclosed information is substantial and accurate.
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 longer than ideal but well-structured: a clear one-sentence summary followed by a tabular Args list. Every line in the Args section is informative, though some entries merely restate the schema defaults. The front-loaded purpose statement ensures the most important information appears early.
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 15 parameters and no output schema details provided, the description covers the main operational modes (sudo vs SFTP), parameter meanings, and common options. It does not mention prerequisites like SSH connectivity or how existing files are handled beyond append, but given the complexity and presence of an output schema, the description is reasonably 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 0% description coverage, so the description must compensate. The Args section provides a concise one-line explanation for every parameter, including the often subtle 'sudo_password' behavior (not needed if NOPASSWD configured) and defaults like 'errors' and 'encoding'. This adds real semantic value beyond the bare schema properties.
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 statement: "Write content to a remote file over SSH." This clearly distinguishes the tool from siblings like read_file and execute_command, and the rest of the description reinforces this purpose.
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 how the tool behaves (e.g., SFTP vs sudo via tee) but does not provide explicit guidance on when to choose this tool over alternatives such as execute_command or read_file. Usage is implied by the tool's name and opening line, but no exclusions or alternative comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a distinct focus: session listing, sync/async execution, file operations, and async command management. The only slight overlap is between send_input and send_input_by_session, but their descriptions clearly differentiate async command IDs from persistent session hosts.
Tools generally follow a verb_noun pattern (list_sessions, execute_command, read_file). Minor deviations like execute_command_async and send_input_by_session use suffixes, and there's a mix of 'get' and 'list' for similar operations, but the overall style is consistent and predictable.
At 15 tools, the set sits at the upper bound of the ideal range but every tool serves a clear purpose. The count is well-suited to the broad scope of SSH management, covering sessions, execution, files, and interactive control without unnecessary bloat.
The toolset provides comprehensive coverage for SSH operations: sync and async command execution, session lifecycle, file read/write, command history, running command monitoring, and interactive terminal input. It addresses virtually all common SSH use cases, making it a complete solution.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Give your AI agents the tools to build, manage, and run automation workflows.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/DBeidachazi/mcp-ssh'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
