cygnus-ssh-mcp

Official

Overview Schema Source Related Servers Discussions Admin

ssh_file_transfer

Upload or download a single file between the local machine and a remote host over SFTP. Use it for one-file transfers; for directories, use ssh_dir_transfer.

Instructions

Transfer a single FILE between the local machine (running this MCP server) and the remote host, via SFTP. Both local_path and remote_path must be file paths, not directories - for whole-directory transfers, use ssh_dir_transfer instead. For remote-to-remote copies (no local machine involved), use ssh_file_copy instead.

Caveat: use_sudo=True on download/upload stages a copy through /tmp/ using Unix shell commands (mv/chmod/rm) - this only works against Linux/macOS remote hosts. Windows has no per-command sudo concept anyway (see ssh_conn_verify_sudo), so use_sudo=True against a Windows connection raises immediately instead of attempting these Unix commands - connect as Administrator instead.

Returns: {'operation' (human-readable description of what happened), 'success': True, 'local_path', 'remote_path', 'sudo', 'connection'}. Raises an exception on failure rather than returning a success: False dict.

Long-running calls: if this takes longer than the server's wait cap (default 50s), it
returns {"status": "in_progress", "handle_id": ...} instead of the result - the work keeps
running. Get the result by polling ssh_cmd_check_status(handle_id=...), which returns this
tool's normal response once finished. Do not call it again meanwhile. Only one such
operation runs at a time; another one started meanwhile fails with a 'busy' error.

Input Schema

TableJSON Schema

Name	Required	Description
`use_sudo`	No	Use sudo for transfer
`direction`	Yes	Transfer direction
`local_path`	Yes	Local file path
`remote_path`	Yes	Remote file path

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.3.0May 28, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden and does so well: it discloses the sudo /tmp staging mechanism and its OS restriction, that Windows raises rather than attempting Unix commands, that failures raise exceptions instead of returning success:False, the exact success response shape, and the async long-running protocol (50s cap, handle_id, poll via ssh_cmd_check_status, don't re-invoke, single-concurrency 'busy' error).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the routing rules before the caveats, and uses a Returns block plus a long-running paragraph to organize secondary detail. Every sentence earns its place, though the sudo caveat and async paragraph make it longer than typical for a 4-param tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema existing, the description adds return-shape and exception semantics plus the async polling contract, which the output schema alone would not convey. Nothing needed to call this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: local_path/remote_path must be file paths and not directories, and use_sudo=True is explained behaviorally (staged through /tmp with mv/chmod/rm, Windows raises). It doesn't restate the direction enum, but the constraints it adds are substantive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+transport: transfer a single FILE via SFTP between the local machine and remote host. It explicitly differentiates itself from two named siblings (ssh_dir_transfer for directories, ssh_file_copy for remote-to-remote), so an agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use rules with named alternatives and their selecting conditions: directories -> ssh_dir_transfer, remote-to-remote -> ssh_file_copy. The sudo caveat further scopes usage (Linux/macOS only; Windows raises immediately).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server