cygnus-ssh-mcp

Official

Overview Schema Source Related Servers Discussions Admin

ssh_cmd_kill

Terminate a running SSH command by its handle ID from ssh_cmd_run. Optionally force-kill a process that doesn't exit after a wait period.

Instructions

Terminate a currently running command by its handle ID (the handle_id field - also returned as id - from ssh_cmd_run's response).

This tool is specifically for killing commands started with ssh_cmd_run - it looks up handle_id in this connection's command history, not by raw PID. For background tasks launched with ssh_task_launch, use ssh_task_kill with the PID instead. Raises an error if handle_id doesn't exist in history (e.g. from a previous connection - handles don't survive reconnects) or has no associated PID.

If force=True and the process doesn't exit after wait_seconds, it will be forcibly killed with SIGKILL (signal 9).

Returns: {'handle_id', 'pid', 'result', 'signal', 'force_kill_used', 'timestamp'}. result is one of: - 'not_running': the command was already confirmed not running before any signal was sent (checked first, via a live PID status check) - nothing to do. - 'killed': confirmed terminated (by the signal or the force-kill fallback - see force_kill_used to tell which). - 'already_exited': the process was gone by the time the signal landed. - 'failed_to_kill': still running after the signal (and force-kill, if force=True) - not terminal, the process is still alive. - 'invalid_pid': the command's tracked PID wasn't a valid positive integer. - 'error': the kill attempt itself failed unexpectedly - the process's real state is unknown.

`force_kill_used` is True iff the SIGKILL fallback was actually attempted
(the initial signal alone was not enough), regardless of whether the
fallback itself succeeded - False if the initial signal alone was
sufficient, the process was already gone, or `force=False`.

Note: after a successful kill (`'killed'` or `'already_exited'`, or the early
`'not_running'` case), a later `ssh_cmd_check_status` call for this same
`handle_id` will report status `'killed'`.

Input Schema

TableJSON Schema

Name	Required	Description
`force`	No	Force kill with SIGKILL if process doesn't exit
`signal`	No	Signal to send (15=TERM, 9=KILL)
`handle_id`	Yes	Command handle ID to kill - the 'id' field from ssh_cmd_run's response
`wait_seconds`	No	Seconds to wait before force kill

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.6.1Oct 5, 2026

changedInput schema / properties / handle_id / description

Previous value: -"Command handle ID to kill"New value: +"Command handle ID to kill - the 'id' field from ssh_cmd_run's response"

First observedv1.3.0May 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does so: it enumerates every terminal state a kill can end in, explains the force+wait_seconds escalation to SIGKILL, defines force_kill_used precisely (attempted, not succeeded), and discloses the side effect that ssh_cmd_check_status will later report 'killed'. Permission, reversibility, and ambiguity cases are all addressed.

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 purpose and routing in the first two paragraphs, then error conditions, then returns. It is long, and the Returns block partially restates the output schema, but the per-state semantics justify most of the length.

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 4-parameter mutation tool with no annotations, the description closes every gap an agent needs: identifier provenance, escalation policy, full result vocabulary including the ambiguous 'failed_to_kill' and 'error' states, and the downstream status effect. Nothing required to invoke or interpret it is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description goes further: it clarifies that handle_id is a history lookup rather than a raw PID, that force only matters if the process survives wait_seconds, and how signal and force interact. It does not add much on wait_seconds beyond the schema default.

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+resource (terminate a running command) and immediately scopes the identifier type: the handle_id from ssh_cmd_run, explicitly contrasted with raw PID. An agent can distinguish it from ssh_task_kill without opening any schema.

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?

Names the alternative tool and the exact condition for choosing it (background tasks from ssh_task_launch → ssh_task_kill with PID). It also states the failure condition (handle not in this connection's history; handles don't survive reconnects), which is a genuine when-it-won't-work exclusion.

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

Deploy Server