powershell-mcp

Overview Schema Source Related Servers Discussions Admin

sftp_upload

Upload a local file to a remote host over SFTP in-process to deploy scripts and configs to Linux hosts without scp.exe or WSL.

Instructions

Upload a local file to a remote host over SFTP, in-process (ssh2 â€” no scp.exe, no WSL, headless). Use to deploy scripts/configs to Linux hosts.

Input Schema

Name	Required	Description
`host`	Yes	Remote host or IP.
`port`	No	SSH port (default 22).
`staged`	No	Opt-in verified staging. Upload fails closed where atomic no-clobber is unsupported; download uses SHA-256 readback and atomic no-clobber hard link.
`password`	No	Password auth (used if no key).
`username`	Yes	SSH username.
`localPath`	Yes	Local file path on this Windows host.
`timeoutMs`	No	Hard timeout in ms (default 120000).
`passphrase`	No	Passphrase for the private key, if any.
`remotePath`	Yes	Destination path on the remote host.
`hostKeyPins`	No	Explicit SHA256:base64 trusted host key fingerprints; multiple keys permit rotation.
`credentialRef`	No	Operator-provisioned scoped credential reference, exclusive with raw auth.
`privateKeyPath`	No	Path to a private key file on this Windows host.

Output Schema

Name	Required	Description	Default
`log`	No
`detail`	Yes
`stderr`	Yes
`stdout`	Yes
`target`	Yes
`exitCode`	Yes
`timedOut`	Yes
`transport`	Yes
`durationMs`	Yes
`truncation`	Yes
`executionId`	Yes
`errorRecords`	No
`schemaVersion`	Yes
`terminationStatus`	Yes
`terminationCertainty`	Yes
`errorRecordsTruncated`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.7.0Oct 24, 2026

addedInput schema / properties / credentialRef

Added value: +{
+  "description": "Operator-provisioned scoped credential reference, exclusive with raw auth.",
+  "type": "string"
+}

addedInput schema / properties / hostKeyPins

Added value: +{
+  "description": "Explicit SHA256:base64 trusted host key fingerprints; multiple keys permit rotation.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / staged

Added value: +{
+  "description": "Opt-in verified staging. Upload fails closed where atomic no-clobber is unsupported; download uses SHA-256 readback and atomic no-clobber hard link.",
+  "type": "boolean"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "detail": {
+      "additionalProperties": false,
+      "properties": {
+        "bytes": {
+          "type": "number"
+        },
+        "cleanup": {
+          "enum": [
+            "not_needed",
+            "removed",
+            "failed",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "direction": {
+          "enum": [
+            "upload",
+            "download"
+          ],
+          "type": "string"
+        },
+        "error": {
+          "type": "string"
+        },
+        "finalized": {
+          "type": "boolean"
+        },
+        "localExitCode": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "sha256": {
+          "type": "string"
+        },
+        "shell": {
+          "type": "string"
+        },
+        "signal": {
+          "type": "string"
+        },
+        "verification": {
+          "enum": [
+            "not_started",
+            "sha256_matched",
+            "failed"
+          ],
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "durationMs": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "errorRecords": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "type": "string"
+          },
+          "exceptionType": {
+            "type": "string"
+          },
+          "fullyQualifiedErrorId": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "category",
+          "fullyQualifiedErrorId",
+          "exceptionType",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "errorRecordsTruncated": {
+      "type": "boolean"
+    },
+    "executionId": {
+      "type": "string"
+    },
+    "exitCode": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "log": {
+      "additionalProperties": false,
+      "properties": {
+        "complete": {
+          "type": "boolean"
+        },
+        "expiresAt": {
+          "type": "string"
+        },
+        "handle": {
+          "type": "string"
+        },
+        "stderrBytes": {
+          "type": "number"
+        },
+        "stdoutBytes": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "handle",
+        "complete",
+        "stdoutBytes",
+        "stderrBytes",
+        "expiresAt"
+      ],
+      "type": "object"
+    },
+    "schemaVersion": {
+      "const": 1,
+      "type": "number"
+    },
+    "stderr": {
+      "type": "string"
+    },
+    "stdout": {
+      "type": "string"
+    },
+    "target": {
+      "type": "string"
+    },
+    "terminationCertainty": {
+      "enum": [
+        "unknown",
+        "root_exited"
+      ],
+      "type": "string"
+    },
+    "terminationStatus": {
+      "enum": [
+        "completed",
+        "nonzero_exit",
+        "script_error",
+        "remote_error",
+        "timeout",
+        "cancelled",
+        "transport_error",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "timedOut": {
+      "type": "boolean"
+    },
+    "transport": {
+      "enum": [
+        "powershell",
+        "program",
+        "winrm",
+        "ssh",
+        "sftp"
+      ],
+      "type": "string"
+    },
+    "truncation": {
+      "additionalProperties": false,
+      "properties": {
+        "limitBytesPerStream": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "stderr": {
+          "additionalProperties": false,
+          "properties": {
+            "capturedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "observedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "omittedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "observedBytes",
+            "capturedBytes",
+            "omittedBytes",
+            "truncated"
+          ],
+          "type": "object"
+        },
+        "stdout": {
+          "additionalProperties": false,
+          "properties": {
+            "capturedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "observedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "omittedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "observedBytes",
+            "capturedBytes",
+            "omittedBytes",
+            "truncated"
+          ],
+          "type": "object"
+        },
+        "truncated": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "truncated",
+        "limitBytesPerStream"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "executionId",
+    "transport",
+    "target",
+    "stdout",
+    "stderr",
+    "exitCode",
+    "durationMs",
+    "timedOut",
+    "truncation",
+    "terminationStatus",
+    "terminationCertainty",
+    "detail"
+  ],
+  "type": "object"
+}

First observedv0.5.0Aug 6, 2026

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description carries the full burden, and it does disclose meaningful execution traits: in-process ssh2, headless, no dependency on scp.exe or WSL. It omits the most consequential write behavior — whether an existing remote file is overwritten by default (the schema's opt-in "staged" no-clobber hint implies clobbering is the default) and what auth/host-key policy is enforced when pins are absent.

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?

Two front-loaded sentences with no filler: action first, implementation constraint second. Minor deduction for the mojibake in the em-dash encoding and for spending words on "no scp.exe, no WSL" that could have covered overwrite semantics instead.

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

Completeness3/5

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

An output schema exists, so return values need not be explained, and the schema fully documents parameters. But for a 12-parameter mutation tool with zero annotations, the description leaves the destructive side (remote file overwrite, failure/rollback behavior without `staged`) undiscussed, which is the biggest remaining gap for correct invocation.

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

Parameters3/5

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

Schema description coverage is 100%, so all 12 parameters (including staged, hostKeyPins, credentialRef) are already documented in the schema; baseline 3 applies. The description adds no per-parameter meaning beyond noting the in-process transport, which only loosely relates to the credential and staging options.

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 (upload a local file) plus the transport (SFTP) and direction, which cleanly separates it from the sibling sftp_download. The parenthetical about running in-process via ssh2 (no scp.exe, no WSL, headless) further distinguishes it from an exec-based workaround.

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

Usage Guidelines4/5

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

"Use to deploy scripts/configs to Linux hosts" gives a clear intended context for invocation. It stops short of exclusions or naming alternatives (e.g., sftp_download, ssh_exec with a heredoc, run_program), so it is clear but not routing-complete.

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