# 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:

```json
{
  "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:

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

Write:

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

Read:

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

Stop:

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.