Cygnus Ssh MCP vs Forge

ssh_conn_add_host

Add a new host configuration to the host configuration TOML file. Despite the name, this does NOT update an existing entry - if the `user@host` key already exists, this returns an error response (`{'status': 'error', ...}`, not a raised exception) rather than overwriting it; use ssh_host_update for that instead. Before calling this, check 'ssh_host_list' - the host you want may already be configured, in which case you can call 'ssh_conn_connect' directly without adding anything. Authentication requires either a password OR a keyfile (or both): - Password authentication: Provide `password` - Key-based authentication: Provide `keyfile` (and optionally `key_passphrase` if the key is encrypted) If using key-only authentication and sudo operations are needed, you must explicitly provide `sudo_password` unless the server has passwordless sudo configured. Warn the user that credentials will be visible to the LLM and that it would be better for the user to add the host directly in the host configuration file. That said, never read this file yourself (directly or via any file/shell tool) to look up, verify, or copy existing hosts' credentials - ssh_host_list, ssh_conn_add_host, ssh_host_update, ssh_host_remove, and ssh_host_use_config are the only tools you should need for host management, and none of them ever expose a stored password/passphrase back to you. This tool always adds to whichever config file is currently active (the server's default unless ssh_host_use_config was called to switch to an alternate one - check ssh_host_list's `config_path` if unsure). The host config file is `~/.mcp_ssh_hosts.toml` if it exists, otherwise `./mcp_ssh_hosts.toml` in the server's working directory - it stores every host's password, sudo password, and key passphrase in plaintext, which is exactly why the tools above exist instead of editing it by hand. The configuration is stored under a ["user@host"] key. Optional fields: - alias: A short name for connecting (e.g., 'prod' instead of 'deploy@production.example.com') - description: A text description of what the host is for Returns: On success: `{'status': 'success', 'message', 'key', 'host', 'user', 'port', 'auth_method' ('key' or 'password'), and 'alias'/'description'/'keyfile' if provided}`. On failure (missing auth, duplicate host key, or duplicate alias): `{'status': 'error', 'error': <message>}` - for a duplicate host key, also includes `'existing_config'` (the current host/user/port/alias/description) so you can decide whether to use it as-is via `ssh_conn_connect` instead.

ssh_host_update

Update one or more fields of an existing host configuration - this is the safe way to rotate a password, change a port, or adjust other settings without ever needing to read or hand-edit the host configuration TOML file (which stores every host's credentials in plaintext - never read it directly; this tool, ssh_conn_add_host, ssh_host_remove, and ssh_host_list cover everything you should need). Only the fields you pass are changed - any parameter left at its default (omitted/`None`) keeps its current value. To clear a field entirely (e.g. drop a password when switching a host to key-only auth), pass an empty string `""` rather than omitting it. `user`/`host` themselves can't be changed this way (that changes the 'user@host' key identity) - remove and re-add instead if you need that. Prefer this over ssh_host_remove + ssh_conn_add_host for adjusting an existing host: remove+re-add loses every field you don't explicitly resupply, since ssh_conn_add_host has no knowledge of the entry it just deleted. `host_name` may be either the 'user@hostname' key or a configured alias - resolved the same way as ssh_conn_connect. Warn the user that any new password/passphrase value passed here will be visible to the LLM, the same caveat as ssh_conn_add_host. Returns: On success: `{'status': 'success', 'message', 'key', 'updated_fields' (list of field names that were actually changed)}`. On failure (the update would leave neither a password nor a keyfile set, or a duplicate alias): `{'status': 'error', 'error': <message>}` - not a raised exception. Raises: SshError: If `host_name` doesn't resolve to any configured host (tried as both key and alias).

ssh_conn_status

Get essential SSH connection status information. Returns: Dictionary containing basic connection status (user, working directory, OS type)

ssh_conn_host_info

Get detailed SSH connection status and system information. Returns: Dictionary containing full connection status and detailed system info including hardware, memory, disk usage, and more. For a 'linux' or 'flex' (non-Linux/macOS/Windows) connection, also includes 'capabilities' (probed GNU/BusyBox-coreutils feature support) and 'capability_warnings' (plain-English list of confirmed gaps) - see ssh_conn_connect's docstring for what these mean.

ssh_host_use_config

Switch which host configuration file ssh_host_list, ssh_conn_connect, ssh_conn_add_host, ssh_host_update, and ssh_host_remove all operate against, for the rest of this session (or until you call this again) - not just for one call. This is the same "one active thing at a time" model ssh_conn_connect uses for SSH connections, applied to host configuration files instead; the two are completely independent (switching config files doesn't affect any current SSH connection, and vice versa). Use this when you want to browse or use hosts from a different TOML file than the server's default - e.g. a separate list of hosts for a different environment/project. The alternate file must already exist and be a valid host configuration TOML file (see ssh_conn_add_host's docstring for the format) - this deliberately does NOT auto-create a missing file the way the server's own default config file is created on first run, since an LLM-supplied path with a typo should fail loudly rather than silently create a stray file somewhere. Omit `config_path` (or pass `""`) to switch back to the server's original default configuration file. ssh_host_list's response always includes `config_path` showing whichever file is currently active, so you can check before mutating anything with ssh_conn_add_host/ssh_host_update/ssh_host_remove. Returns: On success: `{'status': 'success', 'message', 'config_path', 'is_default' (bool), 'host_count'}`. On failure (path doesn't exist, path is a directory, or the file fails to parse as valid host config TOML): `{'status': 'error', 'error': <message>}` - not a raised exception.

ssh_host_list

List all configured SSH hosts with their aliases and descriptions. This is the ONLY correct way to see what hosts are configured - never read the host configuration TOML file directly (ssh_conn_add_host's docstring names its path). That file stores every host's password, sudo password, and key passphrase in plaintext; this tool deliberately omits all of that and returns only the fields below. If you need to add, change, or remove a host, use ssh_conn_add_host, ssh_host_update, or ssh_host_remove instead of editing the file - between those and ssh_host_use_config, there is no legitimate reason to open it. Lists hosts from whichever config file is currently active - the server's default unless ssh_host_use_config was called to switch to an alternate file. The returned `config_path` always shows which one that is. Returns: Dictionary with: - hosts: List of host information dictionaries, each containing: - key: The 'user@host' key - alias: Optional short name for the host - description: Optional description of the host - config_path: The host configuration file this list came from

ssh_host_remove

Remove a host configuration from the host configuration TOML file (see ssh_conn_add_host's docstring for its exact path and why you should never read it directly - use ssh_host_list to see what's configured instead). To change a host's password/port/etc. rather than deleting it, use ssh_host_update instead - removing and re-adding loses every field you don't explicitly resupply. Returns: Dictionary with operation status

ssh_host_disconnect

Disconnect the current SSH connection if one exists. Use this when you want to explicitly close the current SSH connection before connecting to a different host or when you're done with SSH operations. Returns: Dictionary with disconnection status

ssh_conn_verify_sudo

Check whether elevated access is available on the remote system, without running any privileged command. Call this before using `use_sudo=True` on other tools if you're not sure elevation will succeed. On Linux/macOS: probes whether `sudo` is available and whether it needs a password (via a passwordless `sudo -n` check, then a password-based check if that fails). Tools called afterward with `use_sudo=True` will use whichever mode this detected. On Windows: there is no per-command elevation - checks whether the current SSH session itself is already running as Administrator. If it's not, no tool call can become elevated; you must reconnect as an Administrator account instead. Returns: Dictionary with: - available (bool): True if sudo/elevation can be used at all (passwordless OR password-based on Linux/macOS; same as `passwordless` on Windows, since there's no separate password-based mode there) - passwordless (bool): True if no password is needed (passwordless sudo, or an already-elevated Windows session) - requires_password (bool): True if sudo works but needs a password (always False on Windows)