This MCP server enables AI agents to establish and manage persistent SSH sessions for executing commands on remote systems.
Core Capabilities:
Execute commands on SSH hosts using persistent, reusable connections across multiple operations
Multi-host management - connect to and manage multiple remote hosts simultaneously
Session management - list active sessions, close individual sessions by host identifier, or terminate all sessions at once
Connection Features:
SSH config support - automatically reads ~/.ssh/config for host aliases, hostnames, ports, users, and identity files
Flexible authentication - supports passwords, SSH keys, and explicit connection parameters
Automatic reconnection - detects and re-establishes dead connections
Thread-safe operations for concurrent usage
Specialized Support:
Network device handling - automatic enable mode management for routers and switches
Sudo support - automatic password handling for privileged commands on Unix/Linux systems
Enables persistent SSH connections to Linux systems for executing commands, managing services with sudo support, and performing system administration tasks remotely.
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 Session check disk usage on production server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
uvxuvx mcp-ssh-sessionAdd to your ~/.claude.json:
{
"mcpServers": {
"ssh-session": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-ssh-session"],
"env": {}
}
}
}npx @modelcontextprotocol/inspector uvx mcp-ssh-sessionuv 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-session"],
"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
Commands complete when either:
Prompt detected: Standard shell prompts ($, #, >, %) at end of output
Idle timeout: No output for 2 seconds after receiving data
Why idle timeout? Custom themed prompts may not match standard patterns. The 2-second idle timeout ensures commands complete even with non-standard prompts.
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?
Without annotations, the description must disclose behavioral traits. It only states it closes sessions, which implies destructive action, but does not mention potential side effects (e.g., closing the current user's session), required permissions, or whether the action is reversible. The lack of detail 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 a single, concise sentence that immediately conveys the core purpose. No extraneous words, perfectly front-loaded 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 tool with no parameters and a simple action, the description is minimally adequate. However, it lacks context on whether all sessions include the current one, if confirmation is needed, or what the output schema returns. An output schema exists, so return values are not required, but more behavioral context would improve 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 has zero parameters, and schema coverage is 100%. According to guidelines, 0 parameters warrants a baseline score of 4. The description adds no param info, but none 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 clearly states the action (close) and the target (all active SSH sessions), with a specific verb and resource. It is distinct from siblings like 'close_session' (singular) and 'list_sessions' (list), leaving 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 provides no guidance on when to use this tool versus alternatives like 'close_session' for individual sessions or 'list_sessions' to see active sessions before closing. No exclusions or context for usage are given.
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 | ||
| username | No | ||
| port | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits such as what happens if the session does not exist, authentication requirements, or side effects. With no annotations provided, the description should compensate but fails to do so.
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, using a short paragraph with bulleted args. It is front-loaded with the primary purpose. Every sentence adds value, though the Args section could be more terse.
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?
Considering there are no annotations but an output schema exists, the description does not explain the return value or confirm success/failure. For a tool with 3 parameters, it lacks completeness around expected outcomes and error conditions.
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 adds some value by explaining that 'host' can be a hostname/IP or SSH config alias. However, 'username' and 'port' are merely restated without additional meaning beyond the schema, so it meets the baseline for a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool closes a specific SSH session, identifying the resource as a session. It explains that the host parameter can be a hostname/IP or SSH config alias. However, it does not explicitly differentiate from the sibling 'close_all_sessions', though the name implies a single 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?
No guidance is provided on when to use this tool versus alternatives like 'close_all_sessions' or when not to use it. The description lacks context for an AI agent to decide between closing a single session or all sessions.
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 | ||
| command | Yes | ||
| username | No | ||
| password | No | ||
| key_filename | No | ||
| port | No | ||
| enable_password | No | ||
| enable_command | No | enable | |
| sudo_password | No | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully describes behavioral traits: persistent sessions, synchronous start with async fallback, timeout handling, interactive support, command interruption, session persistence, automatic sudo prefix, and authentication methods. It is highly 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 well-structured with a brief overview, detailed parameter list, and bullet-pointed advanced features. It is front-loaded with the core behavior. Some redundancy exists (e.g., 'automatically' used multiple times), but overall it is concise 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?
Given the tool's complexity (10 parameters, no annotations) and the existence of an output schema (not shown), the description covers input behavior well. It mentions returning a command ID for async mode but does not describe the synchronous output (e.g., stdout/stderr). Assuming the output schema covers return values, completeness is high but with a minor 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 coverage is 0% (no parameter descriptions in schema). The description provides thorough explanations for all 10 parameters in the 'Args' section, including default values, usage scenarios (host as alias, enable/sudo passwords), and constraints (optional fields). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes a command on an SSH host with a persistent session. It explains the synchronous start and potential async transition. However, given the sibling tool 'execute_command_async', the description does not explicitly differentiate when to use this tool vs the explicit async version, limiting clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: synchronous start, automatic async transition on timeout, and when to use enable_password/sudo_password. However, it does not explicitly state when to use this tool over its sibling 'execute_command_async' or when not to use it. The guidance is present but incomplete.
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 | ||
| command | Yes | ||
| username | No | ||
| password | No | ||
| key_filename | No | ||
| port | No | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses async behavior, returns command ID, and mentions companion tools. But lacks details on error handling, authentication specifics (beyond optional params), and what happens on timeout (though default is given). Adequate but not thorough.
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?
Well-structured: purpose, use cases, companion tools, then parameter list. No superfluous text, each sentence adds value. Front-loaded with key information about async behavior and return value.
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?
Output schema exists (though not shown) so return format is presumably documented elsewhere. Description covers all 7 parameters, mentions companion tools, and gives usage context. Missing some behavioral details but overall sufficient.
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%. The Args section adds basic descriptions to each parameter (e.g., host is 'Hostname, IP address, or SSH config alias'), but they remain terse and do not provide constraints or advanced semantics. Meets minimal expectations.
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 executes a command asynchronously without blocking, and distinguishes from synchronous counterparts by mentioning returns a command ID for later status retrieval. It also gives explicit use cases like long-running 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?
Provides explicit guidance on when to use (e.g., long-running commands, monitoring) and lists companion tools for follow-up actions. However, it does not explicitly contrast with alternatives like the synchronous 'execute_command'.
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?
With no annotations, the description carries full burden. It correctly implies a read operation but lacks details on side effects, error handling (e.g., if command fails), or whether the call is idempotent. The existence of an output schema mitigates this somewhat.
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: one sentence for purpose, then a one-line argument description. Every word is necessary, and it is front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is adequate. It covers purpose, parameter semantics, and the async nature. The presence of an output schema reduces the need to describe return values. Minor gap: no mention of what happens for invalid or expired command_id.
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 0%, so the description must compensate. It adds meaning by specifying that 'command_id' comes from execute_command_async, which guides the agent on how to obtain it. This is clear and useful, though not exhaustive.
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 specific verb 'Get' and resource 'status and output' of an async command, clearly distinguishing it from sibling tools like execute_command_async (which initiates) and list_running_commands (which lists without retrieving output).
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 states the command_id argument comes from execute_command_async, implying it is used after that tool. However, it does not explicitly exclude use cases like polling vs. final output, nor mention alternatives like interrupt_command_by_id.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It reveals the method (Ctrl+C) and that the command must be running, but does not discuss side effects, permissions, or whether the operation is reversible. This is adequate but not rich.
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 with two clear sentences: one for the tool purpose and one for the parameter. No wasted language, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple interrupt tool with one parameter, the description covers the essential aspects. Although an output schema exists, the description does not clarify what is returned (e.g., success status), but this is a minor omission given the tool's straightforward nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'command_id' is described as 'The command ID returned by execute_command_async', which adds valuable context beyond the schema's bare type and requirement. Since schema coverage is 0%, this description compensates well.
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 ('interrupt') and the resource ('a running async command'), with a specific mechanism ('sending Ctrl+C'). This differentiates it effectively from related sibling tools like execute_command or list_running_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 description implies usage for interfering with asynchronous commands but does not provide when-not-to-use guidance or explicitly mention alternatives. Given sibling tools like get_command_status or list_running_commands, the lack of context for choosing among them is a gap.
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?
No annotations provided; description only mentions listing history and default limit, lacking disclosure of scope (e.g., all sessions vs current), read-only nature, or other behavioral traits.
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 efficient sentences with no redundancies; front-loaded purpose and clear parameter explanation.
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 simple listing tool with output schema; but missing clarity on whether history is scoped to current or all sessions.
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 has 0% description coverage for the 'limit' parameter; description adds meaning by stating it's the maximum number of commands to return, beyond the schema's type and default.
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 clearly states the verb 'list' and resource 'recent command history' with status qualifiers (completed, failed, interrupted), distinguishing it from siblings like list_running_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?
Implied usage for viewing past commands but no explicit guidance on when to use alternatives like list_running_commands 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 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?
No annotations provided. Description only states the read-only action but does not confirm no side effects or disclose any behavioral details beyond the action.
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?
Single sentence, no redundancy, 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?
Simple tool with an output schema; description adequately covers functionality. Lacks mention of scope (e.g., what counts as 'running').
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?
No parameters; schema coverage is 100%. Description adds no parameter info but none 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 'List all currently running async commands' uses a specific verb and resource, clearly distinguishing from siblings like list_command_history and get_command_status.
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 vs alternatives, but the name and description imply it's for current running commands.
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?
With no annotations, the description takes full burden. It accurately conveys a read-only listing operation, which is inherently safe. No contradictory or missing behavioral cues.
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 information with no superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, output schema exists), the description provides sufficient context for an agent to understand its function. No additional details are necessary.
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 no parameters, so the baseline score of 4 applies. The description does not need to add parameter information.
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 action ('list') and resource ('all active SSH sessions'), which is specific and distinct from sibling tools like close_session or execute_command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as differentiating it from listing running commands or other session-related actions.
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 | ||
| remote_path | Yes | ||
| username | No | ||
| password | No | ||
| key_filename | No | ||
| port | No | ||
| encoding | No | utf-8 | |
| errors | No | replace | |
| max_bytes | No | ||
| sudo_password | No | ||
| use_sudo | 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 full burden. It discloses the dual read method (SFTP then sudo cat) and explains parameters like sudo_password and use_sudo. It could mention error handling, but the errors parameter is documented. Overall clear behavioral 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 concise, starting with a summary line and then listing parameters in a structured Args section. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, output schema exists), the description covers behavior (SFTP/sudo fallback), edge cases (sudo passwordless), and parameter semantics. With output schema present, return values need not be detailed.
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 explain all parameters. The Args section provides thorough explanation for all 11 parameters, including optional authentication, encoding, and sudo behavior, adding substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read a remote file over SSH' with a specific verb and resource. It further elaborates on fallback behavior (SFTP then sudo cat), distinguishing it from a simple read tool and from sibling 'write_file'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides conditional usage guidance: attempts SFTP first, falls back to sudo if permissions denied and appropriate parameters set. It does not explicitly state when not to use or compare to other siblings, but the context is clear enough for the tool's purpose.
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 | ||
| username | No | ||
| port | No | ||
| max_lines | No |
| 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 must fully disclose behavior. It mentions the read-only nature and the required condition, but does not elaborate on potential side effects or error states, leaving some 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 compact with a clear intro, condition, parameter list, and return value note. Every sentence is informative with no redundancy.
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 the tool's moderate complexity, the description covers the essential return structure and a critical usage condition. It could benefit from error handling or prerequisites, but is largely 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, but the description provides meaningful explanations for all 4 parameters, including defaults and optional usage for username and port. This adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reads the terminal screen state for a session, including cursor position. It is well-distinguished from sibling tools like execute_command and read_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the required environment variable MCP_SSH_INTERACTIVE_MODE=1 for operation. While it doesn't explicitly contrast with alternatives, the purpose is clear and unique among siblings.
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?
No annotations provided, so description carries burden. It indicates the tool sends input and returns output, but lacks details on side effects, permissions, or blocking behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a clear first sentence and bullet examples, though the 'Args' section somewhat redundantly restates schema properties.
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 output schema exists, description doesn't need return details. It covers usage scenarios and parameter purpose, though missing prerequisites (e.g., command must be running).
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 0%, but description adds meaning by explaining each parameter's role and providing examples for input_text, compensating for the schema lack.
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 sends input to a running async command and returns new output, with specific examples. It differentiates from siblings like send_input_by_session by focusing on commands rather than 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 provides context for when to use (interactive commands like pagers, prompts) but does not explicitly state when not to use or mention alternatives such as send_input_by_session.
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 | ||
| input_text | Yes | ||
| username | No | ||
| port | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the burden. It mentions interaction with active shell and gives input examples (Ctrl+C, 'q'), but does not disclose whether the session must already exist, what happens if the session is not interactive, or any 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?
The description is concise with a clear two-paragraph structure: purpose statement followed by arg descriptions. No unnecessary information. Slightly improved by front-loading the key verb-resource.
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 siblings like 'execute_command' and 'send_keys', and an output schema that is not shown, the description lacks details on session prerequisites, error conditions, or post-invocation behavior (e.g., whether input is queued or executed). It is adequate for basic use but incomplete for complex decisions.
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?
With 0% schema coverage, the description compensates fully by explaining each parameter: 'host' clarified as hostname/IP/alias, 'input_text' with concrete examples, and optionality of 'username' and 'port'. 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?
Clearly states it sends input to the active shell of a session. The verb 'send input' and resource 'active shell for a session' are specific, but the description does not differentiate from sibling tools like 'send_input' or 'send_keys' that may have similar purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an example use case ('clearing stuck interactive states') and mentions sending input to the current shell, but does not contrast with alternatives like 'execute_command' or 'send_keys', nor specify when not to use this tool.
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 | ||
| username | No | ||
| port | 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 full burden. It describes the action and supported tokens, but does not disclose side effects (e.g., no output reading, no mention of session state changes) or authentication requirements. Returns only a success message.
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 overview, token list, examples, and parameter definitions. It is comprehensive without being verbose, though the token list could be slightly condensed.
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 sibling tools, the description adequately covers the key aspects: input format, supported tokens, and parameter meanings. It could add context on behavioral differences from similar tools like send_input.
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 provides detailed explanations for each parameter in the Args section, including examples and optionality, which compensates for the 0% schema coverage. Each parameter's purpose and format are clearly defined.
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 special keys or key sequences to a session, with a specific verb and resource. It distinguishes from siblings like execute_command by focusing on key sequences rather than full 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 description explains the tool is for sending key sequences with special tokens, but does not explicitly state when to avoid using it or compare with alternatives like send_input. The context is clear but lacks exclusion guidance.
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 | ||
| remote_path | Yes | ||
| content | Yes | ||
| username | No | ||
| password | No | ||
| key_filename | No | ||
| port | No | ||
| encoding | No | utf-8 | |
| errors | No | strict | |
| append | No | ||
| make_dirs | No | ||
| permissions | No | ||
| max_bytes | No | ||
| sudo_password | No | ||
| use_sudo | 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 explains the sudo/SFTP mechanism, append, make_dirs, permissions, and max_bytes. However, it omits details on error handling, side effects of overwriting, or connection 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 front-loaded with the purpose, followed by a structured argument list. It is not overly verbose but lengthy due to many parameters; every line adds value.
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 15 parameters and an output schema, the description covers core behavior and parameter details. It mentions max_bytes and permissions. Could be more complete on error handling, but overall adequate for the complexity.
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 lists all 15 parameters with explanatory text (e.g., 'permissions: Octal file permissions to set (e.g., 420 for 0644)'), adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Write content to a remote file over SSH,' which clearly states the action (write) and resource (remote file). This distinguishes it from siblings like read_file and execute_command.
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 when to use sudo vs SFTP based on use_sudo and sudo_password. However, it does not explicitly exclude other use cases or compare with alternatives like execute_command for writing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tools are largely distinct across session management, command execution, file operations, and interactive features. Potential confusion between send_input, send_input_by_session, and send_keys is clarified by descriptions but still requires careful reading.
All tools follow a consistent verb_noun lowercase underscore pattern (e.g., execute_command, get_command_status, list_sessions). Compound verbs like close_all and send_input_by_session are still predictable and uniform.
15 tools cover the SSH domain comprehensively without being excessive. Each tool serves a specific need (sync/async commands, file transfer, interactive control, session management) and the count feels well-scoped.
Core SSH workflows are covered: command execution (sync and async), file reading/writing, session listing, and interactive input. Minor gaps include no explicit session creation tool (sessions are created implicitly) and no file deletion or rename operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/devnullvoid/mcp-ssh-session'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
