portal-mcp-server

remote_transfer

Transfer files between local and remote hosts over SFTP for binary-safe, atomic uploads, downloads, recursive sync/mirror, and batch transfers.

Instructions

Transfer files between local and remote via SFTP (binary-safe, atomic).

Modes

direction="upload": local_path → remote_path (single file). Example: remote_transfer(direction="upload", host="web01", local_path="/tmp/app.jar", remote_path="/opt/app/app.jar")
direction="download": remote_path → local_path (single file). Example: remote_transfer(direction="download", host="web01", remote_path="/var/log/syslog", local_path="/tmp/syslog")
direction="sync": recursively sync local_path directory → remote_path directory (upload). Files already present with a matching size+mtime (or sha256 when checksum=True) are skipped.
direction="mirror": recursively mirror remote_path directory → local_path directory (download); the remote→local counterpart of "sync". Example: remote_transfer(direction="mirror", host="web01", remote_path="/srv/www/", local_path="./www/")
direction="upload-list" / "download-list": transfer an explicit list of file pairs given in paths_json (an arbitrary local→remote mapping, not a whole directory). Each pair is skipped when already present with a matching size+mtime (or sha256 when checksum=True), so re-runs only move the changed files; a single pair's failure is collected in failed[] without aborting the batch. local_path / remote_path are ignored in these modes. Example: remote_transfer(direction="upload-list", host="web01", paths_json='[{"local":"/tmp/a.conf","remote":"/etc/app/a.conf"}, {"local":"/tmp/b.conf","remote":"/etc/app/b.conf"}]')

Args: checksum: for the incremental modes (sync/mirror/upload-list/ download-list), compare files by sha256 instead of size+mtime (slower, requires sha256sum on the remote; missing remote files or an unavailable sha256sum force a re-transfer). paths_json: JSON array of {"local": ..., "remote": ...} objects, required by the upload-list / download-list modes (ignored otherwise). resume: (upload only) if a SMALLER partial already exists at remote_path from an interrupted transfer, append just the missing tail instead of restarting, then verify the whole file's sha256 and re-upload fresh once on mismatch. Default on; set False to force a fresh overwrite. The result carries resumed=true when the tail path ran.

Progress is reported to the MCP client during transfers.

Returns a JSON status dict. Single-file: {status, direction, host, bytes, duration_s, ...}. sync/mirror/upload-list/download-list: {status, uploaded|downloaded, skipped, failed[], bytes_total, bytes_transferred, duration_s}.

For text-only edits prefer remote_patch (hash-protected). Use remote_transfer when SFTP semantics are needed: binary files, large files, whole directory trees. Note: directory modes copy files only — symlinks and special files are skipped, and empty directories are not created on their own.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`host`	Yes
`resume`	No
`checksum`	No
`direction`	Yes
`local_path`	Yes
`paths_json`	No
`remote_path`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv4.0.3Sep 28, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so: atomic/binary-safe claims, skip-on-matching-size+mtime or sha256 behavior, per-pair failure collection without aborting the batch, resume tail-append plus sha256 re-upload fallback, symlink/special-file skipping and no empty-dir creation, and progress reporting. This is unusually rich disclosure for a mutation-heavy tool.

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 mode list and each section earns its place, but the multi-line indented examples and the repeated skip-explanation across sync and list modes add some length that a tighter phrasing could avoid.

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?

For a 7-parameter, six-mode tool with an output schema, everything an agent needs is present: mode semantics, required vs ignored params, incremental behavior, failure handling, and edge cases (symlinks, empty dirs), plus sibling routing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate and does — checksum, paths_json (format plus an inline JSON example), resume (default, semantics, resumed=true flag), and direction are all documented beyond their bare schema titles, with local/remote path roles clarified per mode.

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 and resource ('Transfer files between local and remote via SFTP') and then enumerates the six direction modes with concrete input/output semantics for each. An agent can distinguish this from remote_patch, remote_read, or remote_shell purely from the description.

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?

Explicitly routes the agent: 'For text-only edits prefer remote_patch (hash-protected). Use remote_transfer when SFTP semantics are needed: binary files, large files, whole directory trees.' It also states the mode-selection rules (list modes ignore local_path/remote_path).

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

Deploy Server