ssh_conn_add_host
Add a new SSH host configuration with credentials to the host config file. Use it to store connection details for later remote server access.
Instructions
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
passwordKey-based authentication: Provide
keyfile(and optionallykey_passphraseif 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Hostname or IP address | |
| port | No | SSH port | |
| user | Yes | Username for authentication | |
| alias | No | Short name for easy connection (e.g., 'prod', 'staging') | |
| keyfile | No | Path to SSH private key file (e.g., ~/.ssh/id_rsa) | |
| password | No | Password for authentication | |
| description | No | Description of what this host is for | |
| sudo_password | No | Password for sudo operations (defaults to regular password if not provided) | |
| key_passphrase | No | Passphrase for encrypted SSH key |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||