cygnus-ssh-mcp

Official

Overview Schema Source Related Servers Discussions Admin

ssh_task_kill

Terminate a remote background process by sending a signal to its PID, with optional force-kill fallback if it doesn't exit in time.

Instructions

Terminate a background task (launched via ssh_task_launch, or any other real remote PID) by sending a signal to its PID.

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

With use_sudo=True on a 'linux'/'flex' connection with a BusyBox-style ps that doesn't support -o pgid= (check ssh_conn_connect/ ssh_conn_host_info's capabilities), this raises a clear error instead of running - there is no clean fallback, since killing just the captured PID (rather than its whole process group) can leave the sudo'd command's real child process(es) running as orphans, exactly the failure mode this check exists to prevent. Not an issue with use_sudo=False.

Returns: {'pid', 'result', 'signal', 'force_kill_used', 'timestamp'}. result is one of: - 'killed': confirmed terminated (by the initial signal or the force-kill fallback - see force_kill_used to tell which). Terminal - nothing left to check. - 'already_exited': the process was already gone before any signal was sent. Terminal. - 'failed_to_kill': still running after both the signal and force-kill attempt (or after the signal alone, if force=False). Not terminal - the process is still alive; consider retrying or investigating why it won't die. - 'invalid_pid': pid wasn't a valid positive integer - no signal was sent. - 'error': the kill attempt itself failed unexpectedly (e.g. connection issue) - the process's actual state is unknown, not necessarily still running.

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

Input Schema

TableJSON Schema

Name	Required	Description
`pid`	Yes	Process ID to terminate
`force`	No	Force kill with SIGKILL if process doesn't exit
`signal`	No	Signal to send (15=TERM, 9=KILL)
`use_sudo`	No	Use sudo for the kill operation
`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.

First observedv1.3.0May 28, 2026

TDQS

A4.2/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses signal behavior, the SIGKILL fallback gated by force and wait_seconds, the precise sudo/BusyBox failure mode and why no fallback exists, and the meaning of force_kill_used. This is far beyond what a bare mutation tool would convey.

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

Conciseness3/5

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

The core action is front-loaded, which is good, but the multi-line 'Returns' block is long and largely duplicates the existing output schema, and the sudo/BusyBox paragraph is dense. It is thorough but not tight; several sentences restate information available in structured fields.

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 5-parameter mutation tool with an output schema, the description covers the operation, the force-kill lifecycle, the environment-specific failure case, and how to interpret results. Nothing an agent needs to invoke or reason about the outcome 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 adds real meaning: force maps to SIGKILL (signal 9) after wait_seconds, use_sudo's BusyBox caveat, and the semantic distinction between force_kill_used and result. It enriches the parameters beyond their schema text.

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+resource: terminate a background task by sending a signal to its PID, and ties scope to tasks launched via ssh_task_launch. It does not explicitly differentiate from the sibling ssh_cmd_kill, which also kills a process, leaving the agent to infer which to use.

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?

Gives clear context (background tasks launched via ssh_task_launch or any real remote PID) and a concrete when-not condition: use_sudo=True on a BusyBox-style ps raises an error rather than running, so the caller must avoid that combination. It does not route to an alternative tool when this one is unsuitable.

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

Deploy Server