Which integrations are available for this server?

Allows natural language SSH automation via GitHub Copilot, enabling remote system management through commands such as connecting to servers, executing commands, file operations, package management, and service control.

How do I use mcp-ssh-tool?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-ssh-tool connect to 192.168.1.100 as admin" 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.

mcp-ssh-tool

by skot

Overview Schema Related Servers Score Discussions

Local

mcp-ssh-tool

npm version npm downloads license

A Model Context Protocol (MCP) SSH client server that provides autonomous SSH operations for GitHub Copilot and VS Code. Enable natural language SSH automation without manual prompts or GUI interactions.

Quick Start

Install

Global install (recommended): npm install -g mcp-ssh-tool
One-off run: npx mcp-ssh-tool

MCP Client Configuration (VS Code / Claude Desktop / others)

Add to your MCP configuration (mcp.json, .vscode/mcp.json, or the Claude Desktop MCP config):

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Usage Examples

Once configured, you can use natural language with your MCP client:

SSH Connection: "Connect to server 192.168.1.100 as admin using SSH key"
File Operations: "Read the content of /etc/nginx/nginx.conf on the server"
Command Execution: "Run 'systemctl status nginx' on the remote server"
Package Management: "Install htop package on Ubuntu server"
Service Control: "Restart the nginx service"

Available Tools

ssh_open_session - Establish SSH connection with various auth methods
ssh_close_session - Close SSH session
ssh_list_sessions - List all active SSH sessions
ssh_ping - Check if a session is alive and responsive
ssh_list_configured_hosts - List hosts from ~/.ssh/config
ssh_resolve_host - Resolve host alias from SSH config
proc_exec - Execute commands remotely (with optional timeout)
proc_sudo - Execute commands with sudo privileges
fs_read, fs_write, fs_list, fs_stat, fs_mkdir, fs_rm, fs_rename - File system operations
ensure_package - Package management
ensure_service - Service control
ensure_line_in_file - File line management
patch_apply - Apply patches to files
detect_os - System information detection

Related MCP server: mcp-ssh-tool

Overview

The SSH MCP Server acts as a bridge between GitHub Copilot and remote systems via SSH. It supports:

Non-interactive SSH operations - No prompts or GUI interactions
Multiple authentication methods - Password, SSH keys, or SSH agent
Session management - Automatic connection pooling with TTL and LRU eviction
File system operations - Read, write, list, and manage remote files via SFTP
Process execution - Run commands and sudo operations remotely
High-level automation - Package management, service control, and configuration management
Security - Automatic redaction of sensitive data in logs

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  GitHub Copilot │────│  SSH MCP Server  │────│  Remote Systems │
│     / VS Code   │    │                  │    │   (via SSH)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │ MCP stdio protocol    │ Session management    │ SSH + SFTP
         │                       │ LRU cache + TTL       │
         │                       │ Auth strategies       │

Installation

Prerequisites

Node.js ≥ 18 (LTS)
SSH access to target systems
SSH keys or credentials for authentication

Install from npm

npm install -g mcp-ssh-tool

Build from source

git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm run build
npm link

CLI Flags

--help / -h: Show usage and examples.
--version / -v: Print version.
--stdio: Force stdio mode (default).

Note: This is an MCP stdio server. The terminal is not an interactive shell; use an MCP client (Claude Desktop, VS Code MCP, etc.) or send JSON-RPC over stdio.

Platform Notes

Linux / macOS: Uses POSIX shell wrappers with safe quoting. Default temp directory: /tmp.
Windows targets: Requires OpenSSH server/agent; key discovery checks C:\\Users\\<you>\\.ssh\\. Commands are wrapped for PowerShell-safe execution. Package/service helpers are intentionally disabled on Windows targets.
Host keys: Host key checking is relaxed by default. Set STRICT_HOST_KEY_CHECKING=true and optionally KNOWN_HOSTS_PATH to enforce verification.

ChatGPT Desktop Integration

Quick Setup

npm run setup:chatgpt

This command automatically configures ChatGPT Desktop to use mcp-ssh-tool.

Manual Setup

Add to your ChatGPT Desktop MCP config:

macOS: ~/Library/Application Support/ChatGPT/mcp.json
Windows: %APPDATA%\ChatGPT\mcp.json
Linux: ~/.config/chatgpt/mcp.json

{
  "mcpServers": {
    "ssh-mcp-server": {
      "name": "ssh-mcp-server",
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

For detailed usage, see docs/chatgpt-usage.md.

VS Code Copilot Integration

User-level Configuration (Recommended)

Open VS Code and press Ctrl+Shift+P, then run "MCP: Open User Configuration".

Add to your mcp.json:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Workspace-level Configuration

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Verification

Restart VS Code
Open Copilot Chat
The SSH MCP tools should appear in the available tools list
Test with: "Connect to 192.168.1.100 as admin and run 'uname -a'"

Usage Examples

Basic Connection and Command Execution

"Connect to 10.11.12.13 as deployer with password 'mypass' and run 'df -h'"

File Operations

"Connect to server.example.com as admin, read /etc/nginx/nginx.conf and show me the server blocks"

System Administration

"Connect to 192.168.1.50 as root, install htop package, start nginx service, and list /var/www contents"

Configuration Management

"Connect to web-server as admin, add these lines to /etc/hosts:
192.168.1.10 db-server
192.168.1.20 cache-server
Then restart networking service"

API Reference

Session Management

`ssh.openSession`

Opens a new SSH session with authentication.

Input:

{
  "host": "example.com",
  "username": "admin",
  "port": 22,
  "auth": "auto",
  "password": "optional",
  "privateKey": "optional-inline-key",
  "privateKeyPath": "optional-path",
  "passphrase": "optional",
  "useAgent": false,
  "readyTimeoutMs": 20000,
  "ttlMs": 900000
}

Output:

{
  "sessionId": "ssh-1645123456789-1",
  "host": "example.com",
  "username": "admin",
  "expiresInMs": 900000
}

`ssh.closeSession`

Closes an active SSH session.

Input:

{
  "sessionId": "ssh-1645123456789-1"
}

Output:

{
  "ok": true
}

Process Execution

`proc.exec`

Executes a command on the remote system.

Input:

{
  "sessionId": "ssh-1645123456789-1",
  "command": "ls -la /home",
  "cwd": "/tmp",
  "env": {"DEBUG": "1"}
}

Output:

{
  "code": 0,
  "stdout": "total 12\ndrwxr-xr-x 3 root root 4096...",
  "stderr": "",
  "durationMs": 245
}

`proc.sudo`

Executes a command with sudo privileges.

Input:

{
  "sessionId": "ssh-1645123456789-1",
  "command": "systemctl restart nginx",
  "password": "sudo-password",
  "cwd": "/etc"
}

File System Operations

`fs.read`

Reads a file from the remote system.

Input:

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "encoding": "utf8"
}

Output:

{
  "data": "127.0.0.1 localhost\n::1 localhost\n..."
}

`fs.write`

Writes data to a file (atomic operation using temp file + rename).

Input:

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/tmp/config.txt",
  "data": "server_name example.com;\nlisten 80;",
  "mode": 644
}

`fs.stat`

Gets file or directory statistics.

Output:

{
  "size": 1024,
  "mtime": "2024-01-15T10:30:00.000Z",
  "mode": 33188,
  "type": "file"
}

`fs.list`

Lists directory contents with pagination.

Input:

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/var/log",
  "page": 0,
  "limit": 50
}

Output:

{
  "entries": [
    {
      "name": "nginx",
      "type": "directory",
      "size": 4096,
      "mtime": "2024-01-15T10:30:00.000Z",
      "mode": 16877
    }
  ],
  "nextToken": "1"
}

`fs.mkdirp`

Creates directories recursively (mkdir -p equivalent).

`fs.rmrf`

Removes files or directories recursively (rm -rf equivalent).

`fs.rename`

Renames or moves files and directories.

High-Level Operations

`ensure.package`

Ensures a package is installed using the system's package manager.

Input:

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "sudoPassword": "optional"
}

Output:

{
  "ok": true,
  "pm": "apt",
  "code": 0,
  "stdout": "Package nginx is already installed",
  "stderr": ""
}

`ensure.service`

Manages system services (systemd or traditional service).

Input:

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "started",
  "sudoPassword": "optional"
}

`ensure.linesInFile`

Ensures specific lines exist in a file (idempotent).

Input:

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "lines": ["192.168.1.10 db-server", "192.168.1.20 cache-server"],
  "createIfMissing": true,
  "sudoPassword": "optional"
}

`patch.apply`

Applies a patch to a file using the patch command.

`os.detect`

Detects operating system information, package manager, and init system.

Output:

{
  "platform": "linux",
  "distro": "ubuntu",
  "version": "22.04",
  "arch": "x86_64",
  "shell": "bash",
  "packageManager": "apt",
  "init": "systemd",
  "defaultShell": "bash",
  "tempDir": "/tmp"
}

Authentication

The server supports multiple authentication methods with automatic fallback:

Authentication Strategy Priority

Password (if provided)
SSH Key (inline → path → auto-discovery)
SSH Agent (if available)

SSH Key Auto-Discovery

The server automatically searches for SSH keys in:

~/.ssh/id_ed25519
~/.ssh/id_rsa
~/.ssh/id_ecdsa

Note: DSA keys (id_dsa) are no longer supported due to security concerns.

Custom key directory: Set SSH_DEFAULT_KEY_DIR environment variable.

Examples

Password Authentication:

{
  "host": "server.com",
  "username": "admin",
  "auth": "password",
  "password": "secret"
}

SSH Key (inline):

{
  "host": "server.com",
  "username": "admin",
  "auth": "key",
  "privateKey": "-----BEGIN PRIVATE KEY-----\n...",
  "passphrase": "optional"
}

SSH Key (file path):

{
  "host": "server.com",
  "username": "admin",
  "auth": "key",
  "privateKeyPath": "/home/user/.ssh/id_rsa"
}

SSH Agent:

{
  "host": "server.com",
  "username": "admin",
  "auth": "agent"
}

Configuration

Environment Variables

LOG_LEVEL - Logging level (error, warn, info, debug)
SSH_DEFAULT_KEY_DIR - Custom SSH key directory
STRICT_HOST_KEY_CHECKING - Enable strict host key checking
KNOWN_HOSTS_PATH - Custom known_hosts file path

Default Settings

Connection timeout: 20 seconds
Session TTL: 15 minutes
Max concurrent sessions: 20
Host key checking: Relaxed (disabled by default)

Error Codes

The server returns structured error codes for machine-readable error handling:

EAUTH - Authentication failed
ECONN - Connection error
ETIMEOUT - Operation timeout
ENOSUDO - Sudo operation failed
EPMGR - Package manager not found
EFS - File system operation failed
EPATCH - Patch application failed
EBADREQ - Invalid request parameters

Each error includes:

name: Error class name
code: Machine-readable error code
message: Human-readable error message
hint: Optional suggestion for resolution

Security Features

Data Redaction

Sensitive data is automatically redacted from logs:

Passwords
Private keys
Passphrases
Sudo passwords
SSH agent socket paths

Connection Security

Configurable host key verification
Support for known_hosts files
Connection timeout enforcement
Automatic session cleanup

Session Management

TTL-based session expiration
LRU cache eviction
Graceful connection cleanup
No persistent credential storage

Development

Setup

git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install

Scripts

npm run build      # Compile TypeScript
npm run dev        # Watch mode compilation
npm run test       # Run unit tests
npm run e2e        # Run E2E tests (requires RUN_SSH_E2E=1)
npm run lint       # Type-check (no emit)
npm run format     # Run Prettier
npm run test:coverage
npm run docs

Testing

Unit Tests:

npm test

E2E Tests (optional):

RUN_SSH_E2E=1 npm run e2e

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

E2E tests require a local Docker container or SSH server for testing.

Contributing

Follow TypeScript and ESLint rules
Add tests for new features
Update documentation
Ensure all tests pass
Use conventional commit messages

License

MIT License - see LICENSE file for details.

Model Context Protocol - Official MCP documentation
VS Code MCP Guide - VS Code Copilot extensibility
GitHub Copilot - GitHub Copilot documentation

Available Tools

20 tools

ensure_lines_in_fileB

Ensures specific lines are present or absent in a file

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`path`	Yes	File path
`lines`	Yes	Lines to manage
`state`	Yes	Desired state

TDQS

B3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It does not specify whether the file is created if missing, if it is idempotent, what happens with duplicates, or any side effects. Critical for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise but omits important details. Not bloated, but under-specified for the complexity of the operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing crucial context: no mention that it relies on an SSH session (sessionId), no idempotency guarantees, no information about return values or error handling. Incomplete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and all parameters have descriptions. The tool description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool manages lines in a file (present or absent), which distinguishes it from sibling tools like ensure_package and ensure_service, as well as other file tools like fs_write (overwrites whole file) and fs_read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. It implies usage for ensuring lines exist or are removed, but lacks when-not conditions or mentions of alternative tools like fs_write for whole file edits.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ensure_packageC

Ensures a package is installed or removed

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`name`	Yes	Package name
`state`	Yes	Desired state

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavior. It only states the basic action without mentioning package manager, permissions, dependencies, error handling, or idempotency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. Perfectly concise for the minimal content provided.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool manipulates system packages via SSH, but description lacks context about supported OS, error states, or output. Incomplete for a mutation tool with no annotations or output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already describes all parameters with 100% coverage. Description adds no extra meaning beyond the overall purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool ensures a package is installed or removed, which distinguishes it from sibling tools like ensure_service or ensure_lines_in_file. However, 'ensures' is vague and could be more specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no mention of prerequisites or preferred scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ensure_serviceC

Ensures a service is in the desired state

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`name`	Yes	Service name
`state`	Yes	Desired state

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It does not mention idempotency, error handling (e.g., if service not found), or prerequisites like sudo privileges. The statement 'Ensures a service is in the desired state' implies idempotency but is too vague to be actionable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core purpose. No redundant words or digressions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, the description should indicate what the tool returns (e.g., confirmation, error). It does not cover idempotency or side effects. For a tool that may fail, this is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters have descriptions in the input schema (100% coverage), so the description adds no extra semantic value beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('ensures') and resource ('service'), clearly indicating it manages service state. It distinguishes from sibling tools like ensure_package or proc_exec, which handle packages or processes, respectively.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 ensure_package or proc_exec. The description lacks context for selecting this tool over others for service management.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fs_listB

Lists directory contents

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`path`	Yes	Directory path to list
`page`	No	Page number for pagination
`limit`	No	Maximum items per page (default: 100)

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only states 'Lists directory contents' without explaining pagination, the need for an active SSH session, default limit (100), or the format of the returned listing. This is minimal for a tool with four parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence. It is front-loaded and avoids extraneous details. While longer context might be helpful, for a simple listing tool this level of conciseness is appropriate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no output schema, and no annotations, the description is insufficiently complete. It fails to mention important context such as the need for an established SSH session, pagination behavior, or the structure of the returned directory listing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (all four parameters have descriptions). The description adds no additional meaning beyond what the schema already provides, aligning with the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Lists directory contents' uses a specific verb ('lists') and resource ('directory contents'), clearly distinguishing it from sibling tools like fs_read (reads file content) or fs_stat (file statistics). It leaves no ambiguity about the tool's primary function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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, nor any exclusions or prerequisites. While the sibling set implies directory listing is distinct, the description does not explicitly help the agent decide when to choose fs_list over other tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fs_mkdirpA

Creates directories recursively

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`path`	Yes	Directory path to create
`mode`	No	Directory permissions mode

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden. It discloses recursive behavior but omits edge cases like what happens if the path already exists, or how the optional 'mode' parameter affects behavior. Adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. Efficiently conveys the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple directory creation tool with no output schema, the description is sufficient but minimal. Could mention that it creates parent directories or behavior on existing directories. With no annotations, it's adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 3 parameters. The tool description adds no parameter-specific details beyond the operation. Baseline score of 3 is appropriate as description adds no extra value over schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Creates directories recursively' clearly states the verb 'creates', resource 'directories', and the recursive behavior. This differentiates it from siblings like fs_write (creates files) or fs_rmrf (removes).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., fs_write or existing directory creation). The description lacks context about when recursive creation is appropriate or when other tools are better.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fs_readA

Reads a file from the remote system

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`path`	Yes	File path to read
`encoding`	No	File encoding (default: utf8)

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description only says 'reads', omitting details on error handling, size limits, or encoding behavior beyond what the schema provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, directly conveys the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a basic tool with 3 parameters and no output schema, but lacks details on return values or edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions. The description adds no further semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action ('reads') and resource ('file from remote system'), distinguishing it from sibling tools like fs_write or fs_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While no explicit when-to-use/exclusions are given, the context of siblings makes it clear this is for reading files, and it is the only read tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fs_renameC

Renames or moves a file/directory

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`from`	Yes	Source path
`to`	Yes	Destination path

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It fails to mention overwrite behavior, error conditions (e.g., destination exists), permission requirements, or atomicity. The phrase 'renames or moves' is vague without stating if move implies across filesystems.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise at one phrase, but this sacrifices necessary detail. While efficient, it omits critical information that affects tool invocation, making it less effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 required parameters and no output schema, the description should explain outcomes, side effects, and return behavior. It does not state whether it returns success/failure, or if the operation is reversible. Incomplete for the complexity of rename/move operations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for each parameter, though minimal ('Source path', 'Destination path'). The description does not add extra meaning beyond these, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (rename/move) and resource (file/directory), distinguishing it from other fs tools like fs_read or fs_rmrf. However, it lacks specifics like scope or whether it works on both files and directories, which are already clear from the description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. For example, it does not clarify when to use fs_rename vs. reading and writing, or if there are prerequisites like session being open.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fs_rmrfB

Removes files or directories recursively

ParametersJSON Schema

Name	Required	Description	Default
`sessionId`	Yes	SSH session ID
`path`	Yes	Path to remove

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states the tool removes recursively, but does not disclose that it is irreversible or destructive. In the absence of annotations, the agent lacks awareness of behavioral traits such as requiring confirmation or handling errors. No details on permissions or safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise with no unnecessary words. However, it could benefit from additional context without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description does not explain output or error behavior. For a destructive tool, it lacks warnings about permanence. The sessionId parameter is crucial but not elaborated. The tool is simple, but the description omits key completeness aspects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides descriptions for both parameters ('SSH session ID', 'Path to remove'), covering 100%. The description adds no additional semantic information beyond what is already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool removes files or directories recursively. The verb 'removes' and resource 'files or directories' are specific and distinguishable from sibling tools like fs_list, fs_read, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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. It does not mention that this is destructive or irreversible, nor does it suggest when to use other file manipulation tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fs_statC

Gets file or directory statistics

ParametersJSON Schema

Name	Required	Description	Default
`sessionId`	Yes	SSH session ID
`path`	Yes	Path to stat

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only states 'Gets statistics' without mentioning side effects, error conditions, permissions required, or return structure. This is insufficient for an AI agent to understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise at 5 words, no redundant information. However, it could be slightly expanded to improve clarity without sacrificing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is incomplete for a stat tool with no output schema. It does not explain what statistics are returned (e.g., size, permissions, modification time) or how to interpret the output. Essential context for the AI agent to use the tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema descriptions, which already define sessionId and path adequately. No additional context is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves file or directory statistics, distinguishing it from sibling tools like fs_read (content) and fs_list (directory listing). However, it lacks specificity on what statistics are returned.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use fs_stat versus alternatives such as fs_read or fs_list. The description does not mention prerequisites, context, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fs_writeC

Writes data to a file on the remote system

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`path`	Yes	File path to write
`data`	Yes	Data to write to file
`mode`	No	File permissions mode

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It fails to disclose critical behaviors such as whether the file is created if missing, whether existing content is overwritten, or what permissions are applied via the 'mode' parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise and free of unnecessary words. It front-loads the core purpose without elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description should explain return values or success indications. It also does not contextualize the mapping of 'sessionId' to a remote SSH session, nor does it mention the effect of 'mode' on file creation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the parameter names and schema descriptions, particularly for 'mode' (file permissions) and 'data' (encoding or format).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('writes data') and resource ('file on the remote system'), distinguishing it from read, rename, and remove siblings. However, it does not specify whether the write overwrites or appends, which could be clearer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidance is provided. The description does not mention when to use this tool versus alternatives like fs_rename or ensure_lines_in_file, nor does it note any prerequisites or limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

os_detectC

Detects operating system and environment information

ParametersJSON Schema

Name	Required	Description	Default
`sessionId`	Yes	SSH session ID

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only says 'detects', with no disclosure of potential side effects, latency, or that it uses the SSH session. Minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely brief (6 words). While concise, it omits essential details like output format. It is not front-loaded with critical information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description does not explain what 'detects' returns. For a simple tool, it should at least indicate whether it returns OS name, version, etc. Incomplete for an agent to use effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (sessionId is described). The description adds no extra parameter meaning beyond what the schema provides, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool detects OS and environment info, matching its name. It does not distinguish from sibling tools, but no sibling has a similar purpose, so it's adequately specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. It doesn't specify that it requires an established SSH session, nor does it mention scenarios where it's inappropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

patch_applyB

Applies a patch to a file

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`path`	Yes	File path to patch
`patch`	Yes	Patch content (unified diff format)

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. However, it only says 'Applies a patch to a file' without detailing what happens on success/failure, whether the patch is applied in-place, 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, straightforward sentence with no extraneous words. It is efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and annotations, the description should provide more context about expected outcomes (e.g., return value, error conditions). It does not cover these aspects, making it incomplete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter having a description in the schema. The tool description adds no additional semantic value beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Applies a patch to a file' clearly states the verb (applies) and resource (patch to a file), distinguishing it from sibling tools like fs_write (which writes entire files) or ensure_lines_in_file (which ensures lines are present).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 (e.g., fs_write, ensure_lines_in_file), nor are there any prerequisites or exclusions mentioned. The description is silent on usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

proc_execC

Executes a command on the remote system

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`command`	Yes	Command to execute
`cwd`	No	Working directory
`env`	No	Environment variables

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description only says 'executes a command', but does not disclose potential side effects, security implications, or that it requires an established SSH session. For a remote execution tool, this 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. Could be slightly improved by adding a brief note on session requirement or return value, but current is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 4 parameters, no output schema, and no annotations, the description fails to explain prerequisites (session must be open), return format, or safe usage tips. Incomplete for a potentially destructive operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 4 parameters are described in the schema (100% coverage). The description adds no extra meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'executes a command on the remote system' with a specific verb and resource. However, it does not differentiate from sibling tool 'proc_sudo' which also executes commands.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like proc_sudo, or any prerequisites (e.g., need an open SSH session). No when-not or exclusion criteria mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

proc_sudoC

Executes a command with sudo privileges

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	SSH session ID
`command`	Yes	Command to execute with sudo
`password`	No	Sudo password
`cwd`	No	Working directory

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must disclose behavioral traits. It fails to mention that password may be required, that sudo can prompt for input, or any security implications. Only states the action without 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no superfluous words. It is appropriately concise for a straightforward tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given four parameters and no output schema, the description is insufficient. It does not explain return values, error handling, or prerequisites (e.g., that sessionId must correspond to an open SSH session).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, providing basic parameter meanings. The description adds nothing beyond what the schema already provides, warranting a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it executes a command with sudo privileges, distinguishing it from proc_exec (likely without sudo). However, it could be more specific about requiring an existing SSH session, which is inferred from context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 proc_exec. No exclusion criteria or context for when sudo is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ssh_close_sessionC

Closes an SSH session

ParametersJSON Schema

Name	Required	Description	Default
`sessionId`	Yes	Session ID to close

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must convey behavioral traits. It only states 'closes', omitting details like whether the session is destroyed, if it can be reused, 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence. It efficiently conveys the core purpose without extraneous text, though it could be slightly more descriptive without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is minimally sufficient. However, it lacks context on error conditions (e.g., invalid session ID) or the outcome of closing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'sessionId' is described in the schema ('Session ID to close') and the description adds no further meaning. With 100% schema coverage, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Closes an SSH session', which matches the tool name. It is specific and unambiguous, though it does not add detail beyond the name itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., ssh_list_sessions, ssh_open_session). No mention of prerequisites or best practices, such as only closing sessions that are open.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ssh_list_configured_hostsA

Lists all hosts configured in ~/.ssh/config

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavioral traits. It states the action but does not mention that it is read-only, what format the hosts are returned in, or potential edge cases. Adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence with no extraneous content, perfectly sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema or annotations, the description covers the basic purpose but lacks details on return format, errors, or performance characteristics. Could be more complete for a tool with no other documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters; schema coverage is 100%. The description adds no parameter info because none exist, which is appropriate. Baseline score of 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all hosts from ~/.ssh/config using a specific verb and resource, and it distinguishes itself from sibling SSH tools that perform different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for viewing configured hosts but provides no explicit when-to-use or when-not-to-use guidance, nor alternatives. It is acceptable for a simple tool but lacks exclusionary context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ssh_list_sessionsB

Lists all active SSH sessions with their details

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully convey behavioral traits. It says 'active SSH sessions' implying a read operation, but does not disclose whether it requires authentication, has side effects (e.g., polling), or other constraints. The description is too brief to cover the typical behavioral information an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-formed sentence of seven words. It is extremely concise with no redundant or unnecessary information, demonstrating optimal structure for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no parameters and no output schema, the description is minimally adequate. It could be more specific about what 'details' are returned (e.g., session ID, host, user) to help an agent understand the output. Given the lack of complexity, a moderate score is appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema coverage is trivially 100%. Per rubric, a parameterless tool deserves a baseline of 4. The description does not add parameter-specific meaning because there are none, but it already explains the tool's purpose sufficiently.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: listing active SSH sessions with details. It uses a specific verb ('Lists') and resource ('active SSH sessions'), making the purpose clear. However, it does not distinguish this tool from siblings like 'ssh_list_configured_hosts' or 'ssh_open_session'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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. It does not mention prerequisites, context, or when not to use it. For example, it could note that 'ssh_open_session' is needed before sessions exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ssh_open_sessionC

Opens a new SSH session with authentication

ParametersJSON Schema

Name	Required	Description
`host`	Yes	SSH server hostname or IP
`username`	Yes	SSH username
`port`	No	SSH port (default: 22)
`auth`	No	Authentication method (default: auto)
`password`	No	Password for authentication
`privateKey`	No	Inline private key content
`privateKeyPath`	No	Path to private key file
`passphrase`	No	Passphrase for encrypted private key
`useAgent`	No	Use SSH agent for authentication
`readyTimeoutMs`	No	Connection timeout in milliseconds (default: 20000)
`ttlMs`	No	Session TTL in milliseconds (default: 900000)

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description does not disclose that the tool returns a session identifier, that it is stateful, or any side effects (e.g., potential for failed authentication). Lacks critical behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no fluff. However, given the tool's complexity (11 parameters), it is too brief and sacrifices informational completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is extremely sparse. It fails to explain the return value (session handle), how to use the session with other tools, authentication failure handling, or security implications. With no output schema and no annotations, this is severely incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so parameters are well-documented in the schema. The tool description adds no additional semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Opens') and resource ('SSH session'), and adds 'with authentication' for context. However, it does not distinguish from sibling tools like ssh_ping or ssh_resolve_host, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., ssh_ping for testing connectivity). No prerequisites or conditions mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ssh_pingB

Checks if an SSH session is still alive and responsive

ParametersJSON Schema

Name	Required	Description	Default
`sessionId`	Yes	SSH session ID to check

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool 'checks if alive and responsive' but does not explain what 'alive' means (e.g., does it send a test packet? Check TCP connection?). No side effects or prerequisites are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is front-loaded and to the point, earning its place without any waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description is adequate but not fully complete. It lacks details about the return value (e.g., boolean, status message) and how 'responsive' is determined. Additional context would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'sessionId', which is already described in the schema. The description adds no additional meaning or context beyond what the schema provides. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: checking if an SSH session is alive and responsive. It uses a specific verb 'checks' and resource 'SSH session', and it distinguishes itself from sibling tools like ssh_open_session or ssh_list_sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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. For example, it does not clarify when ssh_ping should be preferred over ssh_list_sessions or other tools. No explicit context or exclusion criteria are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ssh_resolve_hostA

Resolves a host alias from ~/.ssh/config to connection parameters

ParametersJSON Schema

Name	Required	Description	Default
`hostAlias`	Yes	Host alias from SSH config

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Fails to disclose return format, error behavior (e.g., if alias not found), or whether it's a pure read operation. Only mentions output is 'connection parameters' without specifics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy. Concisely conveys purpose without wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema or annotations, the description is minimal. Lacks details on return format and edge cases. Adequate for a simple tool but could be more informative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with description 'Host alias from SSH config'. Tool description adds no extra detail beyond schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action: resolves a host alias to connection parameters, specifying the source (~/.ssh/config). Distinguishes from siblings like ssh_list_configured_hosts (lists hosts) and ssh_open_session (opens session).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not guidance. Implies usage for resolving a specific alias, but lacks differentiation from listing hosts or opening sessions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

20 tool updatesv1.2.8Jun 10, 2026
- First observedensure_lines_in_file
- First observedensure_package
- First observedensure_service
- First observedfs_list
- First observedfs_mkdirp
- First observedfs_read
- First observedfs_rename
- First observedfs_rmrf
- First observedfs_stat
- First observedfs_write
- First observedos_detect
- First observedpatch_apply
- First observedproc_exec
- First observedproc_sudo
- First observedssh_close_session
- First observedssh_list_configured_hosts
- First observedssh_list_sessions
- First observedssh_open_session
- First observedssh_ping
- First observedssh_resolve_host

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Disambiguation5/5

Each tool has a clear, distinct purpose. SSH session management, filesystem operations, system administration, and execution tools are all well-separated with no overlapping responsibilities.

Naming Consistency4/5

Most tools follow a domain prefix pattern (ssh_, fs_, proc_, ensure_) with verb_noun structure. Minor inconsistency: patch_apply lacks a prefix, and os_detect is less descriptive, but overall pattern is clear.

Tool Count5/5

20 tools is well-suited for the domain of SSH remote management, covering session lifecycle, file operations, package/service management, and execution without being overwhelming.

Completeness4/5

The tool set covers core SSH management tasks comprehensively. Minor gaps exist (e.g., file permissions, user management), but these are beyond the typical scope of an SSH toolkit.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
237
supportsheep
io.github.pooriaarab
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Customer Support Content Management Systems Marketing
1
termalin-web A
in.termal
Run commands and read/write files on your servers over Termalin's keyless tunnels (hosted MCP).
Shell Access File Systems
81
QuallaaOAuth
com.quallaa
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
AI & Machine Learning Communication
2

Related MCP Servers

SSH MCP Server
Shell Access Code Execution
vilasone455
F
license
A
quality
D
maintenance
A local Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH connections.
Updated a year ago (2025-05-27 06:59 UTC)
6
17
2
-
mcp-ssh-tool
Shell Access Command Line OS Automation
oaslananka
A
license
A
quality
A
maintenance
SSH automation MCP server that enables Claude and ChatGPT to execute commands, manage files, install packages, and control services on remote servers over SSH — supporting password, key, and agent authentication.
Updated 4 months ago (2026-05-17 11:52 UTC)
33
1,267
4
MIT
Simple SSH MCP Server
Shell Access Command Line OS Automation
bhayanak
A
license
Not graded
quality
D
maintenance
An MCP server that gives AI assistants full SSH/SFTP remote operations — session management, command execution, interactive shells, file transfers, port forwarding, and system diagnostics.
Updated 5 months ago (2026-04-17 09:50 UTC)
2
MIT
ssh-mcp
Shell Access Command Line
slepp
A
license
A
quality
C
maintenance
An MCP server that gives AI agents SSH access to remote machines through your local OpenSSH client, enabling remote command execution, file transfer, persistent shell sessions, and port forwarding.
Updated 2 months ago (2026-07-09 00:20 UTC)
17
16
MIT

Appeared in Searches

MCP SSH Reloaded - SSH Server/Tool for Model Context Protocol

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/skot/mcp-ssh-tool'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

mcp-ssh-tool

Quick Start

Install

MCP Client Configuration (VS Code / Claude Desktop / others)

Usage Examples

Available Tools

Overview

Architecture

Installation

Prerequisites

Install from npm

Build from source

CLI Flags

Platform Notes

ChatGPT Desktop Integration

Quick Setup

Manual Setup

VS Code Copilot Integration

User-level Configuration (Recommended)

Workspace-level Configuration

Verification

Usage Examples

Basic Connection and Command Execution

File Operations

System Administration

Configuration Management

API Reference

Session Management

ssh.openSession

ssh.closeSession

Process Execution

proc.exec

proc.sudo

File System Operations

fs.read

fs.write

fs.stat

fs.list

fs.mkdirp

fs.rmrf

fs.rename

High-Level Operations

ensure.package

ensure.service

ensure.linesInFile

patch.apply

os.detect

Authentication

Authentication Strategy Priority

SSH Key Auto-Discovery

Examples

Configuration

Environment Variables

Default Settings

Error Codes

Security Features

Data Redaction

Connection Security

Session Management

Development

Setup

Scripts

Testing

License

Contributing

License

Related Links

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

`ssh.openSession`

`ssh.closeSession`

`proc.exec`

`proc.sudo`

`fs.read`

`fs.write`

`fs.stat`

`fs.list`

`fs.mkdirp`

`fs.rmrf`

`fs.rename`

`ensure.package`

`ensure.service`

`ensure.linesInFile`

`patch.apply`

`os.detect`