Skip to main content
Glama

ssh_exec

Run allow-listed shell commands on a preset SSH host and return stdout, stderr, and exit code, with key-based auth, approval prompts, and audit logging.

Instructions

Run a shell command on the preset's SSH host. The command must match one of the preset's allowed_commands regexes (anchored ^...$). Words are separated by single spaces and may contain only letters, digits and - _ . / : = @ , + %; quotes, $, backticks, globs, redirections and other shell syntax are refused. Returns stdout, stderr, and exit_code. Key-based auth only; host key is verified against the user's known_hosts file. Sensitive presets trigger the approval prompt. If the user previously approved a time-boxed window for this preset+action, the call proceeds without a new prompt and is recorded as 'windowed' in the audit log. Every call is recorded to the audit log.

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": {
      "preset_name": "<preset_name>",
      "command": "<command>"
    },
    "name": "ssh_exec"
  }
}

Input Schema

NameRequiredDescriptionDefault
commandYes
preset_nameYes

Output Schema

NameRequiredDescriptionDefault
noticeNoSet when mcp-warden stopped reading the output (over the limit).
stderrYes
stdoutYes
exit_codeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.6.0
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Set when mcp-warden stopped reading the output (over the limit).",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  2. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden and mostly succeeds: it declares the sandbox rules (no quotes, `$`, backticks, globs, redirections), key-based auth only, host key verification against known_hosts, the approval-prompt path, time-boxed approval windows recorded as 'windowed', and audit logging of every call. It stops short of disclosing timeouts, output size limits, working directory, or what happens when a command is refused.

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-loads the core action and the matching constraint before the auth, approval, and audit details. It is dense but nearly every clause adds operational meaning; only the trailing restatement of audit logging after the windowed-approval sentence feels slightly redundant.

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?

An output schema exists, so return values need not be explained, yet the description still names stdout, stderr, and exit_code. For a two-parameter exec tool with no annotations, the remaining gaps are edge-case behavior: failure mode on a rejected command and any timeout or concurrency limits.

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 coverage is 0%, so the description must compensate and it does: it defines exactly what 'command' may contain (space-separated words, permitted character classes, rejected shell syntax) and anchors 'preset_name' semantically to a preset with allowed_commands, sensitivity level, and approval state. This is richer than the bare string types in the schema.

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

Purpose4/5

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

States a specific verb and resource: 'Run a shell command on the preset's SSH host,' and immediately scopes it to commands matching the preset's allowed_commands regexes. It does not differentiate itself from the sibling ssh_run, so an agent must infer which of the two exec-style tools to pick.

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

Usage Guidelines3/5

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

Gives implied eligibility conditions (command must match an anchored regex, restricted character set) and notes that sensitive presets trigger an approval prompt, which effectively tells the agent when the call will stall. However, it never names an alternative such as ssh_run or sftp_transfer, nor states when this tool is preferable to them.

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