ssh-mcp

Overview Schema Source Related Servers Discussions Admin

execute_on_group

Executes a shell command on all servers in a specified group in parallel. Supports configurable timeouts, working directories, dry-run, and fail-fast modes, returning per-server results.

Instructions

Execute a shell command on all servers in a group in parallel.

Concurrency is capped by the max_parallel_hosts setting (default 10; configure in [settings] of servers.toml, range 1–100). The semaphore is PROCESS-WIDE, not per call: concurrent execute_on_group calls share the same slots and therefore serialise against each other for their share of them.

Args: group: Group name (e.g. 'production', 'web'). Use list_groups to see available groups. command: Shell command to execute on every server in the group. Rejected if it exceeds max_command_bytes (default 65536 encoded UTF-8 bytes). timeout: Per-server command timeout in seconds. Default 30. Not range-checked, and overridden per server by a timeout set on that server's entry in servers.toml. Each server has its own timer; slow servers do NOT extend the per-server limit for others. working_dir: Absolute remote directory to cd into on each server. Uses each server's default_dir if omitted. fail_fast: If True, cancel remaining tasks as soon as any server returns a non-zero exit code or errors. Default False — run all servers to completion and report each result. force: If True, bypass the dangerous-command detection patterns. Use only for audited bulk operations. The same broad block list described under execute applies here — including plain bash -c / python3 -c / eval wrappers. Default False. dry_run: If True, do NOT connect or execute anywhere. Return a per-server preview describing what would run. Dangerous- command detection still applies. Useful for previewing fleet-wide rollouts before committing. Default False.

Returns: Formatted summary showing per-server results, success/failure counts, and aggregate exit status.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`force`	No
`group`	Yes
`command`	Yes
`dry_run`	No
`timeout`	No
`fail_fast`	No
`working_dir`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.1.1Jul 4, 2026

addedInput schema / properties / dry_run

Added value: +{
+  "default": false,
+  "title": "Dry Run",
+  "type": "boolean"
+}

addedInput schema / properties / force

Added value: +{
+  "default": false,
+  "title": "Force",
+  "type": "boolean"
+}

First observedv0.1.0Mar 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses parallel execution, the process-wide concurrency semaphore, per-server timeout independence, fail_fast semantics, dangerous-command detection, and dry_run's no-connect guarantee. This gives the agent a strong model of side effects and resource behavior.

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 purpose and the most important concurrency behavior, then organized into clean Args and Returns sections. It is long, but every sentence adds operational value, and the structure makes the details scannable for an agent.

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?

Given the tool's complexity — 7 parameters, fleet-wide parallel execution, failure modes, and safety controls — the description is complete. It covers behavior, defaults, parameter semantics, edge cases like serializer sharing, and the return format, leaving no significant operational gap for the agent.

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 fully explain all 7 parameters, and it does. Every parameter receives its own Args entry with default values, constraints, and behavioral nuance, such as max_command_bytes for command, per-server timeout overrides, and force bypassing dangerous-command detection.

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 opens with a specific verb and resource: 'Execute a shell command on all servers in a group in parallel.' This clearly distinguishes it from the sibling 'execute' tool, which presumably targets a single server, and it orients the agent immediately to the group-scoped behavior.

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?

The description gives clear context: commands run fleet-wide across a group, and it points to list_groups to discover valid group names. It also explains when dry_run is useful for previewing rollouts. However, it does not explicitly state when to prefer this tool over the sibling 'execute' tool or when not to use it, so it stops short of fully explicit usage routing.

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

Deploy Server