mcp-ssh/skills/mcp-ssh-server/references/tool-usage.md

MCP SSH Tool Usage

Connection Inputs

Most tools use these inputs:

• host: direct remote hostname or IP address.
• username: remote SSH username.
• port: optional remote SSH port, default 22.
• keyPath: optional local private key path. If omitted, the server tries ~/.ssh/id_ed25519, then ~/.ssh/id_ecdsa, then ~/.ssh/id_rsa.
• keyPassphrase: optional passphrase for encrypted private keys. Treat as sensitive.

Current limit: do not rely on OpenSSH aliases, SSH agent identities, ProxyJump, ProxyCommand, or ssh -G resolution.

ssh_exec

Use for one bounded remote command.

Inputs:

• Required: host, username, command.
• Optional: cwd, port, keyPath, keyPassphrase, timeoutSeconds.

Example:

{
  "host": "prod-api.example.com",
  "username": "deploy",
  "command": "systemctl status nginx --no-pager",
  "cwd": "/var/www",
  "timeoutSeconds": 30
}

Expected result includes exitCode, stdout, stderr, and durationMs. Non-zero exit codes are preserved. Timeout results use timedOut: true.

Terminal Session Tools

Use for interactive or stateful remote shell work.

Start:

{
  "host": "prod-api.example.com",
  "username": "deploy",
  "cols": 120,
  "rows": 40,
  "idleTimeoutSeconds": 900
}

Write:

{
  "sessionId": "term_abc123",
  "input": "pwd\n"
}

Read:

{
  "sessionId": "term_abc123",
  "maxBytes": 12000
}

Stop:

{
  "sessionId": "term_abc123"
}

Operational notes:

• Include newline characters when submitting shell commands.
• Read after each write when command output matters.
• Stop sessions explicitly after finishing.
• The remote account's default shell starts without injected setup commands.

sftp_list

Use to list a remote directory over SFTP.

{
  "host": "prod-api.example.com",
  "username": "deploy",
  "remotePath": "/var/www"
}

Result entries include name, path, type, size, and modifiedUtc.

No SCP fallback is available for directory listing.

sftp_get

Use to download one remote file into the MCP server working directory.

{
  "host": "prod-api.example.com",
  "username": "deploy",
  "remotePath": "/var/log/app.log",
  "localPath": "downloads/app.log",
  "overwrite": false,
  "maxBytes": 104857600
}

Notes:

• Local paths must stay inside the MCP server working directory.
• Existing local files are not overwritten unless overwrite is true.
• The server tries SFTP first and silently falls back to SCP when SFTP is unavailable.

sftp_put

Use to upload one local file from the MCP server working directory.

{
  "host": "prod-api.example.com",
  "username": "deploy",
  "localPath": "dist/app.tar.gz",
  "remotePath": "/tmp/app.tar.gz",
  "overwrite": false,
  "maxBytes": 104857600
}

Notes:

• Local paths must stay inside the MCP server working directory.
• Existing remote files are not overwritten unless overwrite is true.
• The server tries SFTP first and silently falls back to SCP when SFTP is unavailable.

Common Error Handling

Treat these as actionable errors:

• ssh_key_not_found: supply keyPath or ensure a default key exists.
• ssh_authentication_failed: check username, key, and keyPassphrase.
• invalid_host, invalid_username, invalid_port: fix connection inputs.
• local_file_exists or remote_file_exists: decide whether overwrite: true is appropriate.
• unsafe_local_path: choose a local path inside the MCP server working directory.
• download_too_large or upload_too_large: raise maxBytes only if the transfer is intended.