cygnus-ssh-mcp

Official

by cygnussystems

Overview Schema Source Related Servers Discussions Admin

Python

Local

ssh_conn_connect

Connect to a pre-configured SSH host by user@hostname or alias; returns system info, OS type, and capability warnings.

Instructions

Establish an SSH connection using a pre-configured host. The host can be specified by its 'user@hostname' key or by its alias.

Beyond the three fully-supported platforms (Linux, macOS, Windows), any other SSH target that responds to a basic shell command connects too, reported as os_type='flex' (e.g. FreeBSD/OPNsense/pfSense-style routers, or other unrecognized POSIX kernels). For 'linux' and 'flex' connections, a one-time capability probe checks the specific shell/coreutils features this server depends on (some embedded/BusyBox-based devices lack GNU extensions like find -printf or tar --strip-components) - the result is returned as 'capabilities' (raw probe results) and, if anything's missing, 'capability_warnings' (plain-English gaps). Tools that need a missing capability fail with a clear error naming what's missing, rather than a cryptic remote command failure - nothing is silently degraded.

Returns: Dictionary with connection status and detailed system information. 'capabilities'/'capability_warnings' are included for 'linux'/'flex' connections only (empty/omitted for macOS/Windows, which are already fully supported and not probed). Two different "os_version" fields: connection.os_version is a short platform/distro identifier used internally (e.g. 'debian', 'centos', 'windows_server_2016', or 'unknown_linux'/'unknown_windows' if not recognized; None on macOS), while system.os_version is the human-readable version string reported by the OS itself (e.g. '12 (bookworm)', '14.8.9').

Long-running calls: if this takes longer than the server's wait cap (default 50s), it
returns {"status": "in_progress", "handle_id": ...} instead of the result - the work keeps
running. Get the result by polling ssh_cmd_check_status(handle_id=...), which returns this
tool's normal response once finished. Do not call it again meanwhile. Only one such
operation runs at a time; another one started meanwhile fails with a 'busy' error.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`host_name`	Yes	The 'user@hostname' identifier or alias of a pre-configured host

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.3.0May 28, 2026

TDQS

A4.2/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and delivers: it discloses the capability probe behavior for linux/flex targets, that missing capabilities fail with named errors rather than silent degradation, the os_type='flex' fallback for unrecognized POSIX kernels, the in_progress/handle_id long-running contract with polling instructions, and the single-concurrent-operation 'busy' error.

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?

Long but dense; most sentences earn their place (long-running contract, capability model, busy constraint). The two 'os_version' field explanation leans toward restating output-schema detail and is the weakest portion, but overall it is front-loaded and disciplined.

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

Completeness5/5

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

For a connection tool that can hang, this covers the async handle/polling flow, the concurrency limit, platform classification, and capability probing. Although an output schema exists, the remaining prose is behavioral rather than shape-describing, so nothing an agent needs to call it 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% for the single host_name parameter, so the schema already documents it. The description reinforces the 'user@hostname or alias' semantics and clarifies hosts must be pre-configured, but adds no syntax or format detail beyond the schema. Baseline 3 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?

States a specific verb+resource: establish an SSH connection to a pre-configured host. It also distinguishes itself from siblings like ssh_conn_status, ssh_conn_is_connected, and ssh_conn_host_info by framing this as the connection-establishment step and explaining the host key/alias resolution.

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?

It explains how to identify the host (user@hostname or alias) and, crucially, the long-running fallback ('do not call it again', poll ssh_cmd_check_status instead) and the one-operation-at-a-time constraint. However, it gives no explicit guidance on when to use this versus alternatives such as ssh_host_add_host or ssh_host_use_config when a host is not yet configured.

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

Deploy Server