Remote SSH MCP

Run command in persistent SSH session

ssh_run

Destructive

Run non-interactive commands in a persistent remote shell, retaining working directory and environment across calls. Supports waiting and timeout for long-running tasks.

Instructions

Start a non-interactive command in the same persistent shell identified by id. cwd and environment changes persist. The call waits at most wait_sec (default 10 seconds); if the command is still active it returns status=running without stopping it. Commands have no automatic execution timeout by default. Only an explicitly provided timeout_sec sends Ctrl-C at that deadline. Never retry a running command: poll with ssh_peek(wait_sec=...) so the MCP call blocks until idle or the wait expires; do not spam peeks with wait_sec=0. Call ssh_interrupt to stop it, or open another session for concurrent work. Only one foreground command may run per id. Do not use vim, top, password prompts, or other interactive TUI/input flows.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>",
      "command": "<command>"
    },
    "name": "ssh_run"
  }
}

Input Schema

Name	Required	Description	Default
`id`	Yes
`command`	Yes
`wait_sec`	No
`timeout_sec`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Jul 31, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond annotations (readOnlyHint=false, destructiveHint=true), the description adds rich behavioral detail: wait_sec behavior with status=running, no automatic timeout, timeout_sec sending Ctrl-C, one foreground command per id, and persistence of cwd/environment changes.

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

Conciseness5/5

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

The description is front-loaded with the core operation and then provides precise behavioral and usage clauses. Every sentence adds value, and the length is justified by the tool's complexity.

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

Completeness4/5

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

The lifecycle, timeout, concurrency, and restrictions are thoroughly covered. However, with no output schema, the description does not specify the return payload for completed commands—only mentioning status=running for still-active commands. This is a minor but non-negligible gap.

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?

The schema has zero property descriptions, but the description fully compensates: id identifies the persistent shell, command is non-interactive, wait_sec is the call wait limit with a default, and timeout_sec triggers Ctrl-C at the deadline. All four parameters are semantically grounded.

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?

The description clearly states it starts a non-interactive command in the same persistent shell identified by id, with persistent cwd and environment changes. This distinguishes it from sibling tools like ssh_open (new session) and ssh_peek/ssh_interrupt.

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?

Explicit guidance is given: poll with ssh_peek(wait_sec=...), call ssh_interrupt to stop, open another session for concurrency, and never retry a running command. It also explicitly forbids interactive TUI/input flows such as vim or top.

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

Deploy Server