46 lines
3.1 KiB
Markdown
46 lines
3.1 KiB
Markdown
---
|
|
name: mcp-ssh-server
|
|
description: "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](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.
|