mcp-ssh/skills/mcp-ssh-server/SKILL.md

name, description

name	description
mcp-ssh-server	Use an MCP SSH Server exposed to Codex for remote SSH operations. Use when Codex needs to run bounded remote commands, manage an interactive SSH terminal session, list remote directories, download files, or upload files through the mcp-ssh tools: ssh_exec, ssh_terminal_start, ssh_terminal_write, ssh_terminal_read, ssh_terminal_stop, sftp_list, sftp_get, and sftp_put.

MCP SSH Server

Overview

Use this skill when an MCP SSH server is available and the task requires remote shell or file-transfer work. The server accepts direct SSH connection inputs and uses key-file authentication; it does not resolve OpenSSH aliases or use an SSH agent in the current tool surface.

For detailed inputs and examples, read references/tool-usage.md.

Workflow

1. Identify the narrowest operation. Use ssh_exec for one command, terminal tools for interactive/stateful work, sftp_list for remote directory listing, and sftp_get/sftp_put for file transfer.
2. Collect connection inputs before calling a tool: host, username, optional port, optional keyPath, and optional keyPassphrase.
3. Treat host as a direct hostname or IP address. Do not pass OpenSSH aliases unless the user confirms they resolve directly for this server.
4. Prefer explicit bounds for risky operations: timeoutSeconds for commands, idleTimeoutSeconds for terminals, and maxBytes for transfers.
5. Keep secrets out of visible text. Use keyPassphrase only when required and never echo or store it.
6. Stop terminal sessions when finished with ssh_terminal_stop.

Tool Selection

• Use ssh_exec for checks, deployments, service commands, one-shot scripts, and commands where stdout/stderr and exit code matter.
• Use ssh_terminal_start plus ssh_terminal_write and ssh_terminal_read for REPLs, long-running interactive tools, TTY-sensitive commands, or workflows that need shell state.
• Use sftp_list to inspect remote directories.
• Use sftp_get to download a remote file into the MCP server working directory.
• Use sftp_put to upload a local file from the MCP server working directory to the remote host.

Safety Rules

• Set timeoutSeconds for commands that might hang. The default is bounded, but explicit values make intent clear.
• Use cwd with ssh_exec instead of shelling through cd ... && ... when the tool supports it.
• For terminal sessions, read output after writes and stop the session when done.
• For downloads and uploads, remember local paths must stay inside the MCP server process working directory.
• Leave overwrite false unless the user asked to replace an existing local or remote file.
• For large files, set maxBytes deliberately.

Current Limits

• SSH agent auth is not part of the current tool inputs.
• OpenSSH config aliases, ssh -G, ProxyJump, ProxyCommand, and known-host policy controls are not part of the current tool inputs.
• Directory upload/download is not exposed; transfer individual files.
• sftp_list has no SCP fallback. sftp_get and sftp_put silently fall back to SCP when SFTP is unavailable.