Run a one-off remote SSH command and return stdout, stderr, and exit metadata. The command runs in a non-interactive context. Use 'cwd' and 'env' for remote directory and environment setup (requires a POSIX shell on the remote). For interactive or long-running commands, use ssh_ensure_session instead.

Copy files or directories between the local machine and one remote target via the local scp client.

Incrementally sync files or directories between the local machine and one remote target via local rsync over SSH.

Read a remote file or list a remote directory over SSH — the remote counterpart of the local file-viewing tool. For a file, returns its content plus 'size_bytes' and 'total_lines'. Content is truncated at 20KB by default when 'view_range' isn't given and 'force_read_large_files' isn't set; use 'view_range' to page through large files instead. For a directory, returns non-hidden entries up to 2 levels deep.

Create a new remote file over SSH with the given content — the remote counterpart of the local file-creation tool. Fails if the path already exists (use ssh_edit to modify an existing file) or if the remote parent directory doesn't exist.

Replace exact text in an existing remote file over SSH — the remote counterpart of the local file-editing tool. Each edit's 'old_str' must match exactly one location in the file (as it stands after any earlier edits in the same call); ambiguous or missing matches fail without writing anything. Provide multiple {old_str, new_str} entries in 'edits' to batch several changes to the same file into a single read-then-write round trip instead of one SSH round trip per edit.

Search remote file contents over SSH — the remote counterpart of the local content-search tool. Backed by remote grep (PCRE-like -P when available, otherwise POSIX extended regex), recursing under 'path' while skipping .git/.hg/.svn. Defaults to 'files_with_matches' mode for efficiency; use 'content' mode for matching lines with line numbers and optional context.

Find remote files by name pattern over SSH — the remote counterpart of the local filename-pattern tool. Supports '', '?', '[seq]'/'[!seq]', '{a,b}' alternation, and '' for matching across multiple path segments (e.g. 'src//.ts'). A path segment starting with '.' is only matched by a pattern segment that itself starts with '.'. Enumerates under 'path' via remote find, skipping .git/.hg/.svn; matching is done locally.

Start a new persistent interactive SSH session backed by a local PTY. Returns the session id, initial output, and observer metadata. If 'truncated' is true or 'pending_output_chars' > 0 in the response, call ssh_read_session to retrieve the remaining buffered output. For most agent workflows, prefer ssh_ensure_session instead — it reuses existing sessions and avoids accidental duplicates.

Return an existing running SSH session or start a new one. This is the recommended tool for agent workflows — always provide a descriptive session_name so the session can be reliably found across tool calls and conversations. When a session is reused (reused=true in response), the cwd, env, and shell parameters are ignored — they only apply when creating a new session. Check 'created' vs 'reused' in the response to know which happened.

Read unread output from a tracked SSH session. Set wait_seconds (e.g. 1-10) to block until new output arrives; 0 returns immediately with whatever is buffered right now. Default: 1.0. If 'truncated' is true or 'pending_output_chars' > 0, call again to drain remaining output. Check 'running' to know whether the session is still alive.

Write text or a control sequence to a tracked SSH session PTY. Always terminate commands with a trailing newline (\n) to submit them. Control characters: \u0003 for Ctrl-C, \u0004 for Ctrl-D, \u001a for Ctrl-Z. Use wait_seconds (e.g. 1-5) to receive the command response in the same call. Check 'pending_output_chars' in the response; if non-zero, call ssh_read_session to drain.

Terminate a tracked SSH session, close any attached tmux observer, and return final unread output plus exit metadata. The transcript file is preserved on disk.

List tracked SSH sessions with their session_id, session_name, target, state, uptime, and observer details (including tmux_session_name for cross-referencing with tmux ls). Use session_name filter to find a specific named session.

Start a dedicated SSH port forward (local or remote). This is a separate tool from ssh_exec/ssh_start_session so MCP clients can permission-gate port forwarding independently. Use direction 'local' to make a remote service reachable on a local port, or 'remote' to expose a local service on the remote host.

List tracked SSH port forwards with their forward_id, direction, ports, target, and running status.

Stop a tracked SSH port forward and return its final status.