Skip to main content
Glama
kchattx

Bifrost MCP

by kchattx
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Bifrost MCP

Bifrost MCP exposes an MCP server for managing persistent interactive SSH sessions. Codex, Hermes Agent, or another MCP client can install this project locally and use it over stdio through the bifrost-mcp entrypoint.

Bifrost MCP is an MCP server for bridging AI agents to remote-admin sessions. Today it supports persistent interactive SSH sessions plus bounded WinRM command-execution sessions. It uses Paramiko as its SSH client; it does not shell out to ssh, does not use sshpass, and does not assume access to host-mounted key files inside a container. SSH command execution is MCP-first and runs through the existing interactive shell session; exec_command is intentionally not implemented.

Bifrost MCP preserves the same safety model across transports: server-side credential resolution, explicit session state, and no secret material returned to the agent.

Requirements

  • Python 3.11 or newer

  • mcp[cli]

  • paramiko

  • gopass CLI for credential storage, installed and initialized in the same operating-system environment that runs bifrost-mcp

Related MCP server: mcp-remote-ssh

Local Installation

Install Bifrost MCP in the same operating-system environment that will run the MCP client. For example, if Codex or Hermes Agent runs inside WSL, create the venv in WSL and use WSL paths. If the client runs on Windows, create a Windows venv and use Windows paths.

WSL/Linux:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .
.venv/bin/bifrost-mcp --help
.venv/bin/python -m bifrost_mcp --help

Windows PowerShell:

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\bifrost-mcp.exe --help
.\.venv\Scripts\python.exe -m bifrost_mcp --help

Install In Codex

Register the local stdio server with Codex. Prefer the installed bifrost-mcp console script instead of python -m bifrost_mcp; it avoids CLI parsing problems with dash-prefixed Python arguments in some MCP registration commands.

WSL/Linux, using the WSL virtualenv:

codex mcp add bifrost -- /path/to/bifrost-mcp/.venv/bin/bifrost-mcp

Windows PowerShell, using the Windows virtualenv:

codex mcp add bifrost -- C:\path\to\bifrost-mcp\.venv\Scripts\bifrost-mcp.exe

You can also edit Codex's config file directly. Use the config file for the environment where Codex runs, for example ~/.codex/config.toml in WSL/Linux or %USERPROFILE%\.codex\config.toml on Windows:

[mcp_servers.bifrost]
command = "/path/to/bifrost-mcp/.venv/bin/bifrost-mcp"
args = []

Windows equivalent:

[mcp_servers.bifrost]
command = "C:\\path\\to\\bifrost-mcp\\.venv\\Scripts\\bifrost-mcp.exe"
args = []

Install In Hermes Agent

Hermes Agent has a native MCP client. Register Bifrost MCP as a stdio MCP server with the hermes mcp add command. Use the console script as the command and leave --args empty.

For most users, prefer the setup helper. It creates the virtualenv, installs Bifrost, verifies gopass, registers the MCP server, and writes runtime path settings to Hermes MCP config rather than .env:

scripts/setup-hermes-mcp.sh --profile lseng --home /home/hermes

Why explicit --home matters: Hermes profiles, containers, systemd units, and web UIs may run MCP subprocesses with a profile-scoped or service-specific HOME. Bifrost credentials are stored under the operating-system account home that owns the gopass and GPG store. The setup helper therefore registers Bifrost with explicit environment values such as:

mcp_servers:
  bifrost:
    command: /home/hermes/mcp_servers/bifrost-mcp/.venv/bin/bifrost-mcp
    env:
      HOME: /home/hermes
      GNUPGHOME: /home/hermes/.gnupg

Do not put SSH passwords, GPG passphrases, or private keys in Hermes .env or config.yaml. .env is for application secrets such as API tokens; Bifrost SSH/sudo secrets belong in gopass, GPG agent, SSH agent, or another real secret manager.

WSL/Linux, using the WSL virtualenv:

hermes mcp add bifrost \
  --command /path/to/bifrost-mcp/.venv/bin/bifrost-mcp

Windows PowerShell, using the Windows virtualenv:

hermes mcp add bifrost `
  --command C:\path\to\bifrost-mcp\.venv\Scripts\bifrost-mcp.exe

The hermes mcp add command connects immediately and prompts which discovered tools to enable. Accept all tools, or choose selectively.

Direct ~/.hermes/config.yaml equivalent:

mcp_servers:
  bifrost:
    command: "/path/to/bifrost-mcp/.venv/bin/bifrost-mcp"
    args: []

Windows path equivalent, for a Hermes process running on Windows:

mcp_servers:
  bifrost:
    command: "C:\\path\\to\\bifrost-mcp\\.venv\\Scripts\\bifrost-mcp.exe"
    args: []

Verify the Hermes MCP registration:

hermes mcp test bifrost
hermes mcp list

After adding or changing the MCP server, restart Hermes Agent or run /reload-mcp inside an active Hermes session. Bifrost MCP tools are exposed with Hermes' MCP prefix, for example:

mcp_bifrost_create_ssh_session
mcp_bifrost_run_command

Running The MCP Server Directly

Codex should use the default stdio transport:

bifrost-mcp --transport stdio

For MCP protocol debugging, the server also supports MCP HTTP transports:

bifrost-mcp --transport sse --host 127.0.0.1 --port 8000
bifrost-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Session cleanup defaults to one hour of inactivity and can be configured with either:

BIFROST_MCP_SESSION_IDLE_TIMEOUT_SECONDS=1800 bifrost-mcp
bifrost-mcp --session-idle-timeout-seconds 1800

gopass Setup

Bifrost MCP reads SSH and sudo secrets from gopass. Install and initialize gopass in the same operating-system environment that runs the bifrost-mcp server process:

  • If Codex or Hermes Agent launches Bifrost MCP from a WSL/Linux virtualenv, install and initialize gopass in WSL/Linux.

  • If Codex or Hermes Agent launches Bifrost MCP from a Windows virtualenv, install and initialize Windows gopass and make sure it is on that process's PATH.

  • Do not initialize only Windows gopass for a WSL/Linux MCP server, or only WSL/Linux gopass for a Windows MCP server.

Install examples:

# Debian/Ubuntu/WSL
sudo apt update
sudo apt install gopass gnupg
# macOS
brew install gopass gnupg
# Windows, for a Windows-native Bifrost MCP server
winget install gopass.gopass
# or: choco install gopass

Initialize a password store with a GPG identity. If you do not already have a GPG key, create one first:

gpg --full-generate-key
gpg --list-secret-keys --keyid-format=long
gopass init <gpg-key-id-or-email>

If you already have a usable GPG key, you can skip key generation and run only gopass init <gpg-key-id-or-email>.

Verify gopass is ready in the Bifrost MCP runtime environment:

command -v gopass
gopass ls

gopass ls must succeed before bifrost-mcp credential ..., create_ssh_session, or the sudo cache tools can resolve stored secrets.

Optional sanity test:

printf '%s' 'test-secret' | gopass insert -m bifrost_mcp/readme-test
gopass show bifrost_mcp/readme-test
gopass rm -f bifrost_mcp/readme-test

The sanity-test path is only a temporary gopass entry. It is not a Bifrost credential slug.

If gopass works in an interactive shell but fails when Bifrost MCP is launched by Codex or Hermes Agent, start the MCP client from the shell where command -v gopass and gopass ls work, or update the service/desktop environment so the launched process inherits the right PATH, GPG agent, and password-store environment. On Windows, restart the terminal or agent after installing gopass so PATH changes are visible.

Credential Store Setup

Bifrost MCP requires gopass for SSH and sudo secrets. Secrets are managed out-of-band by the local user and are never accepted as normal MCP tool parameters. After gopass ls succeeds in the Bifrost MCP runtime environment, add Bifrost credentials with deterministic slugs.

Bifrost stores secret records in gopass under bifrost_mcp/...; the credential slug remains the stable user-facing identifier. Bifrost keeps only non-secret metadata in ~/.config/bifrost_mcp/credentials.json so list/show commands do not need to read every secret.

Default account

Configure one optional default account for every currently available transport:

bifrost-mcp credential set-default

The interactive prompt accepts a username, shared password, and SSH private key. Press Enter to leave an unset field blank; when updating an existing default, Enter preserves its current username/password/key. credential list always displays the configured default account separately from host-attached credential rows (and emits its non-secret metadata as default_credential with --json). create_ssh_session and create_winrm_session may omit username to use the default. Agents can explicitly force use of the default with use_default_credential=True on either session-creation tool or warm_sudo_cache; this bypasses any host-specific credential and requires an explicitly supplied username to match the configured default username. Without that flag, warm_sudo_cache uses the default password only when no host-specific sudo://... record exists and the SSH session username exactly matches the default username. If an SSH or WinRM connection using the default succeeds, Bifrost materializes the applicable default record as an attached per-host credential without overwriting an existing host-specific record.

GPG unlock model

Bifrost intentionally does not accept raw passwords or private keys from agent-facing MCP tools. The MCP server resolves secrets server-side through gopass, which in turn relies on GPG. For interactive desktops and developer machines, the recommended security model is:

  1. Store SSH/sudo credentials in gopass.

  2. Warm gpg-agent from a real terminal when needed:

    export GPG_TTY=$(tty)
bifrost-mcp credential unlock

  3. Let gpg-agent cache the unlock for a bounded time. You usually unlock once per cache window, not before every MCP tool call. After the TTL expires or after reboot, run bifrost-mcp credential unlock again.

The credential unlock command decrypts one existing Bifrost credential only to warm the agent; it does not print secret values. When configured, no-argument bifrost-mcp credential unlock unlocks the default account first; otherwise it auto-selects one deterministic host-bound credential. Credentials encrypted to the same GPG key should then work until the cache expires. Use filters only if you need to target a specific credential:

bifrost-mcp credential unlock --host example-host --user admin
bifrost-mcp credential unlock --purpose ssh
bifrost-mcp credential unlock ssh://admin@example-host

A reasonable ~/.gnupg/gpg-agent.conf is:

default-cache-ttl 1800
max-cache-ttl 7200
pinentry-program /usr/bin/pinentry-curses

Reload it with:

gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

This keeps secrets encrypted at rest, requires an explicit human unlock, and limits the window in which a non-interactive MCP process can decrypt records. For unattended servers, prefer a dedicated service account and a real secret-manager integration or a tightly scoped GPG/pass store. Avoid putting GPG passphrases or SSH passwords in .env, shell history, or Hermes config.

Credential slugs are deterministic and safe to display:

<purpose>://<username>@<canonical-host>

Rules:

  • purpose is ssh, sudo, or winrm.

  • Hosts are lowercase.

  • Include :<port> for non-default SSH ports. WinRM credential slugs omit the conventional HTTP/5985 and HTTPS/5986 ports; include other ports.

  • SSH credentials can have a password record, a key record, or both; key records are preferred automatically.

  • Sudo credentials are password records only.

  • WinRM usernames must use down-level DOMAIN\user format. UPN usernames such as user@example.edu are not supported.

Examples:

ssh://admin@example-host
sudo://admin@example-host
winrm://BYU\administrator@windows-host
ssh://deploy@example-host:2222

Credential CLI

Credentials are managed locally through CLI commands. These commands assume gopass ls succeeds in the same environment that runs bifrost-mcp:

# Password record: prompts securely when run from a terminal. For ssh:// slugs,
# Bifrost also asks for an optional matching sudo password and stores it as
# sudo://<user>@<host> when provided.
bifrost-mcp credential add ssh://admin@example-host --password
bifrost-mcp credential add sudo://admin@example-host --password
bifrost-mcp credential add 'winrm://BYU\administrator@windows-host' --password

# Or read from piped stdin for scripts
printf '%s' 'ssh-password' | bifrost-mcp credential add ssh://admin@example-host --password

# Private key record under the same SSH slug
bifrost-mcp credential add ssh://admin@example-host --key ~/.ssh/id_ed25519

# Metadata only; never prints secrets. Defaults to a human-readable table;
# use --json when scripting.
bifrost-mcp credential list --host example-host
bifrost-mcp credential list --host example-host --json
bifrost-mcp credential show ssh://admin@example-host

# Warm gpg-agent without printing the secret; use once per cache window
bifrost-mcp credential unlock
bifrost-mcp credential unlock ssh://admin@example-host
bifrost-mcp credential unlock --host example-host --user admin

# Remove one record type from an exact slug
bifrost-mcp credential remove ssh://admin@example-host --key
bifrost-mcp credential remove ssh://admin@example-host --password

credential add refuses to overwrite an existing record of the same type. Use credential remove first if rotation is intentional.

Troubleshooting gopass

  • If Bifrost reports that gopass is unavailable, install gopass in the same OS environment that runs bifrost-mcp and confirm command -v gopass works there.

  • If gopass ls fails, initialize the password store with gopass init <gpg-key-id-or-email>, unlock the store if needed, or fix the local GPG/password-store configuration.

  • If gopass works in a shell but not through Codex or Hermes Agent, start the client from the working shell or update the launch environment so PATH, GPG agent, and password-store state are available to the MCP server process.

  • If WSL/Linux and Windows are both present, initialize gopass in the environment whose virtualenv path was registered with Codex or Hermes Agent.

Available MCP Tools

  • list_credentials(host): lists non-secret user metadata for one host, grouped by username.

  • create_ssh_session(host, username, port=22, use_default_credential=False): opens a new interactive SSH session using stored ssh://... credentials. Set use_default_credential=True to force the configured default account.

  • create_winrm_session(host, username, port=5985, use_ssl=False, auth="ntlm", use_default_credential=False): opens a WinRM session using stored winrm://... password credentials. Set use_default_credential=True to force the configured default account.

  • send_input(session_id, text): sends raw text to an existing session.

  • send_control(session_id, key): sends one of ctrl-c, ctrl-d, ctrl-z, enter, or escape.

  • read_output(session_id, clear_buffer=True): reads buffered output from a session.

  • wait_for_output(session_id, pattern, timeout, regex=True, clear_buffer=True): waits until buffered output matches a regex or literal.

  • run_command(session_id, command, timeout=30): runs a command inside the existing transport. For SSH it uses the interactive shell and waits for a sentinel. For WinRM it executes PowerShell script text via pywinrm run_ps() and returns stdout/stderr/exit code.

  • check_sudo_cache(session_id, timeout=10): runs sudo -n -v to check whether sudo is already warm.

  • warm_sudo_cache(session_id, timeout=10, use_default_credential=False): derives sudo://<session-user>@<session-host>, sends the password server-side, and warms sudo with sudo -S ... -v. Set use_default_credential=True to force the matching configured default password.

  • clear_sudo_cache(session_id, timeout=10): invalidates sudo timestamp state with sudo -k.

  • upload_file(session_id, local_path, remote_path, create_parents=False): uploads one MCP-server-local file over SFTP without overwriting.

  • download_file(session_id, remote_path, local_path, create_parents=False): downloads one remote file to an MCP-server-local destination file path without overwriting.

  • resize_session(session_id, width, height): resizes the remote PTY.

  • list_sessions(): returns active session metadata and idle time.

  • close_session(session_id): closes any SSH or WinRM session and removes it from server state.

Versions before this change exposed close_ssh_session; clients must switch to close_session.

Credential-Backed SSH Flow

  1. Call list_credentials(host).

  2. If exactly one SSH user is available, use that username. If zero or multiple SSH users are returned, ask the human which login user to use; do not guess.

  3. Call create_ssh_session(host, username, port=22).

  4. Bifrost MCP derives ssh://<username>@<canonical-host> internally, resolves gopass records exactly, prefers key auth if present, otherwise uses password auth, and returns only non-secret session metadata.

Agent-facing SSH session creation does not accept password, auth_mode, private_key, or private_key_passphrase.

Command Execution And Interaction

Use run_command for ordinary non-interactive shell commands. It runs in the current interactive shell session, preserving state like cd, exported variables, and activated virtual environments. If a timeout occurs, Bifrost MCP returns partial output and leaves the remote command running; use send_control(session_id, "ctrl-c") if interruption is appropriate.

Use send_input, wait_for_output, and send_control for prompts, installers, pagers, REPLs, and terminal programs.

WinRM Support

WinRM sessions are created with stored winrm://... password credentials. Only down-level usernames such as BYU\administrator are supported; UPN usernames such as administrator@ad.byu.edu are rejected.

bifrost-mcp credential add 'winrm://BYU\administrator@windows-host' --password
create_winrm_session(host="windows-host", username="BYU\\administrator", port=5985, use_ssl=false, auth="ntlm")

Supported in v1:

  • create_winrm_session

  • run_command

  • list_sessions

  • close_session

use_ssl=False uses HTTP, and the API's default port=5985 matches the conventional HTTP endpoint. For the conventional HTTPS endpoint, set both use_ssl=True and port=5986; enabling SSL does not change the port automatically. HTTPS validates the target certificate through the Bifrost runtime's configured CA trust bundle/store. For private PKI, install the issuing CA there; do not bypass certificate validation. Basic authentication must only be used with use_ssl=True; Basic over HTTP is unsafe.

When using run_command on a WinRM session, pass PowerShell script text directly:

Get-CimInstance Win32_LogicalDisk -Filter 'DriveType=3' |
  Select-Object DeviceID, Size, FreeSpace |
  ConvertTo-Json -Compress

Do not wrap it in powershell -Command .... Bifrost already uses pywinrm run_ps(), so nesting PowerShell causes quoting foot-guns like outer-shell expansion of $_.

Not supported in v1 for WinRM:

  • send_input

  • send_control

  • resize_session

  • read_output

  • wait_for_output

  • check_sudo_cache

  • warm_sudo_cache

  • clear_sudo_cache

  • upload_file

  • download_file

These return structured unsupported_operation errors instead of pretending WinRM behaves like an interactive SSH PTY.

Operator-only real WinRM verification

This is a manual operator gate, not an automated agent test. Run it only against an authorized Windows endpoint whose certificate is trusted by the Bifrost runtime:

# The prompt reads the password without echoing it.
bifrost-mcp credential add 'winrm://BYU\administrator@windows-host' --password

Then make these MCP calls:

create_winrm_session(host="windows-host", username="BYU\\administrator", port=5986, use_ssl=true, auth="ntlm")
run_command(session_id="...", command="hostname")
run_command(session_id="...", command="$PSVersionTable.PSVersion.ToString()")
send_input(session_id="...", text="test")
close_session(session_id="...")

Verify session creation succeeds without disabling certificate validation, both commands return expected output, send_input returns unsupported_operation, and the session closes successfully. Never record the password in the command, logs, or test evidence.

Sudo Cache Warming Flow

  1. Optionally call check_sudo_cache(session_id).

  2. If sudo needs a password, call warm_sudo_cache(session_id).

  3. Bifrost MCP derives sudo://<session-user>@<canonical-host> internally and retrieves that password server-side. If it is absent, Bifrost uses the configured default password only when the session username exactly matches the default username. It then runs:

sudo -S -p '[bifrost-mcp sudo password] ' -v && printf '\n__BIFROST_MCP_SUDO_OK__\n' || printf '\n__BIFROST_MCP_SUDO_FAILED__\n'

This warms the sudo timestamp cache with sudo -v; it does not enter a root shell and does not return the sudo password.

File Transfer

local_path is local to the Bifrost MCP server process filesystem, not necessarily the chat client. V1 supports files only, not recursive directories.

Uploads and downloads refuse to overwrite destination files. Set create_parents=True to create missing destination parent directories; otherwise missing parents return structured errors.

upload_file(session_id, "/tmp/local.tgz", "/home/user/local.tgz", create_parents=False)
download_file(session_id, "/var/log/app.log", "/tmp/app.log", create_parents=True)

Transport Architecture

Bifrost currently implements SSH sessions through SSHHandler. Internal session storage is transport-neutral so future transports such as WinRM can register sessions with the same metadata and lifecycle shape.

Future WinRM support should add a separate WinRMHandler that satisfies the same internal session protocol. It should not emulate a PTY unless the WinRM backend can actually support equivalent behavior; shell-like operations such as send_input, wait_for_output, and resize_session must either return structured unsupported_operation errors or be exposed through WinRM-specific tools.

WinRM is not SSH-over-HTTP. Before adding tools, decide per operation:

  • run_command: likely supported as a command/script execution primitive.

  • send_input: likely unsupported unless an interactive shell channel is implemented.

  • wait_for_output: likely unnecessary for one-shot WinRM command execution.

  • resize_session: unsupported.

  • SFTP upload/download: requires a separate file-transfer strategy, not SFTP.

  • sudo tools: SSH/Linux-specific; do not apply to WinRM.

Host Key Handling

Bifrost MCP uses Paramiko host-key handling with an accept-new policy:

  • first-seen hosts are added automatically

  • changed host keys still fail

  • known hosts are stored in a dedicated file under the runtime user's ~/.ssh directory

Not Implemented In This Plan

The following features remain deferred by design: host allowlist, audit logging, command mediation/policy enforcement, broad policy subsystem, additional remote-management transports, and Paramiko exec_command.

Available Tools

16 tools
check_sudo_cacheC

Check whether sudo cache is warm without prompting.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior2/5

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

No annotations provided, so description carries full burden. It indicates no prompting but does not specify side effects (e.g., whether it modifies state), return value, or stability. Ambiguity about whether cache state change is possible.

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?

Single sentence is concise and conveys core purpose, but lacks structure (e.g., broken into sections) and omits essential details that would justify brevity.

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

Completeness2/5

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

Despite having an output schema (not shown), description remains incomplete: fails to explain parameters, usage context, or return format. Missing details may lead to incorrect parameter values.

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

Parameters1/5

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

Schema has 0% description coverage; description adds no meaning to parameters (session_id, timeout). Parameters are crucial for invocation but completely undocumented.

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?

The description clearly states the tool checks whether sudo cache is warm without prompting, which distinguishes it from siblings like warm_sudo_cache and clear_sudo_cache. However, it lacks precise definition of 'warm'.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives (e.g., before running commands). The phrase 'without prompting' hints at a non-interactive check but no explicit when-not or alternative tools are mentioned.

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

clear_sudo_cacheC

Clear remote sudo timestamp cache with sudo -k.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations, the description bears full responsibility. It states the action but does not disclose important behavioral details such as required permissions, impact on sudo operations, failure conditions, or whether it modifies server state.

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?

The description is a single concise sentence, front-loaded with the action. However, it is too minimal and could be expanded slightly without losing conciseness.

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

Completeness2/5

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

Despite the tool's simplicity and the presence of an output schema, the description lacks parameter explanations and behavioral context, leaving the agent without enough information to use the tool effectively.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not explain the meaning or usage of the two parameters (session_id required, timeout optional). The agent must infer from parameter names alone.

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 the verb 'clear' and the resource 'remote sudo timestamp cache', and mentions the command 'sudo -k', which distinguishes it from siblings like check_sudo_cache and warm_sudo_cache.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives such as check_sudo_cache or warm_sudo_cache. There is no mention of prerequisites or when to avoid clearing the cache.

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

close_ssh_sessionC

Close an active SSH session and remove it from server state.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It discloses the main outcome ('remove it from server state') but lacks details on side effects, required permissions, error conditions, or whether it can be undone.

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 description is very short (one sentence), which is concise, but it does not front-load critical information. It is adequate but lacks additional detail.

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

Completeness2/5

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

Given the presence of an output schema and a single parameter, the description provides minimal context. It does not explain the return value, error handling, or prerequisites, leaving the agent underinformed.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not mention the only parameter session_id. A brief explanation of what session_id represents or how to obtain it would be expected at this coverage level.

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 the action ('Close an active SSH session') and the effect ('remove it from server state'). It distinguishes well from siblings like create_ssh_session and list_sessions.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives, nor any prerequisites or conditions. The description implies it is for closing a session, but does not specify when not to use it or what to do if the session is already closed.

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

create_ssh_sessionC

Open a new interactive SSH session using server-side stored credentials.

ParametersJSON Schema
NameRequiredDescriptionDefault
hostYes
portNo
usernameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits but only mentions 'interactive SSH session' and 'server-side stored credentials'. It misses details on connection failure, timeout, session lifetime, or how credentials are resolved.

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 a single efficient sentence with no redundant words, fitting for a tool with simple purpose.

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

Completeness2/5

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

Description is too brief given the tool's complexity. It omits side effects, prerequisites, session management details, and how it interacts with sibling tools like send_input or read_output.

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

Parameters1/5

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

Schema description coverage is 0%, yet the description adds no parameter-level details. Although parameter names are self-explanatory, the description fails to compensate for the lack of schema annotations.

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 the tool opens an interactive SSH session using server-side credentials, specifying the verb 'open', resource 'SSH session', and distinguishing it from non-interactive or WinRM-based alternatives.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus siblings like create_winrm_session or run_command. The description lacks context for selection criteria.

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

create_winrm_sessionC

Open a new WinRM session using server-side stored credentials.

ParametersJSON Schema
NameRequiredDescriptionDefault
authNontlm
hostYes
portNo
use_sslNo
usernameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

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

No annotations provided; description is too brief. It hints at authentication ('server-side stored credentials') but does not disclose session lifecycle, error handling, or whether credentials are validated upfront. Score reflects lack of detail for an unsupervised agent.

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?

Single sentence, no redundancy. However, it is too minimal—missing critical usage context and parameter details. Not purely concise; it omits necessary information.

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

Completeness2/5

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

With 5 parameters (2 required, 3 with defaults), no schema descriptions, and no behavioral details, the description fails to equip an agent to use the tool correctly. Output schema exists but not referenced. Incomplete for a moderately complex creation tool.

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

Parameters1/5

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

Schema description coverage is 0%; neither schema nor description explains parameters. Required 'host' and 'username' are obvious from names, but 'auth', 'port', and 'use_ssl' have no semantics clarified. The description adds no value beyond parameter names.

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 the action ('Open') and resource ('WinRM session'), and mentions using server-side stored credentials, which distinguishes it from sibling tools like create_ssh_session.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives (e.g., create_ssh_session). No context on prerequisites, when not to use, or typical use cases.

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

download_fileC

Download a remote file to an MCP-server-local path over SFTP.

ParametersJSON Schema
NameRequiredDescriptionDefault
local_pathYes
session_idYes
remote_pathYes
create_parentsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

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

No annotations provided; description omits behavioral details such as file overwrite behavior, directory creation (create_parents not mentioned), permissions, or path constraints. Ambiguous phrase 'MCP-server-local path' needs clarification.

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?

Single sentence is concise but misses key details; slight expansion would improve clarity without sacrificing brevity.

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

Completeness2/5

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

Despite simple function, missing important context: session prerequisite, error handling, file overwrite policy, and output schema usage. Incomplete for agent decision-making.

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

Parameters2/5

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

Schema description coverage is 0%; description only lists parameter names without explaining their roles, formats, or defaults. For example, 'create_parents' default false is not described.

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 the action (download), resource (remote file), destination (MCP-server-local path), and protocol (SFTP). It effectively distinguishes from sibling tools like upload_file.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives (e.g., other transfer methods). Missing prerequisites like requiring an active session or specifying SFTP authentication.

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

list_credentialsB

List non-secret stored credential metadata for one host.

ParametersJSON Schema
NameRequiredDescriptionDefault
hostYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description must fully disclose behavior. It mentions 'non-secret' indicating no secrets are returned, but lacks details on read-only nature, authentication needs, or implications of listing credentials.

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?

Single sentence efficiently conveys the action and scope, with no extraneous information. Front-loaded with the main verb and resource.

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

Completeness3/5

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

For a simple tool with output schema, the description is minimally adequate but doesn't explain what 'metadata' includes (e.g., fields like username, type). Could be more complete given no annotation support.

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

Parameters2/5

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

Schema coverage is 0%, so description should compensate. It only states 'for one host', not clarifying format (e.g., IP, hostname) or additional constraints, providing minimal added meaning.

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?

Description clearly states the tool lists non-secret stored credential metadata for one host, specifying the verb 'list' and resource 'non-secret stored credential metadata', and differentiates from sibling tools like check_sudo_cache.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives, such as when to check sudo cache or when to manage sessions. No exclusions or prerequisites mentioned.

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

list_sessionsA

List all active remote sessions managed by this MCP server.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior2/5

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

No annotations are provided, so the description must carry behavioral transparency. It implies a read-only operation but does not explicitly state that it does not modify state or require special privileges.

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?

A single sentence of 11 words that is direct and front-loaded. No unnecessary information.

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 tool with no parameters and an output schema, the description is complete. It specifies the scope ('all active remote sessions managed by this MCP server').

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?

The input schema has no parameters, so the description naturally cannot add parameter semantics. Baseline for 0 params is 4.

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 uses the specific verb 'List' and resource 'active remote sessions', clearly distinguishing it from sibling tools like create_ssh_session or close_ssh_session.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool vs alternatives. The description only states what it does, without context on prerequisites or when to prefer it over list_credentials or other listing tools.

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

read_outputA

Read buffered output from an active SSH session and optionally clear it.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYes
clear_bufferNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations, the description must disclose behavioral traits. It states reading and optional clearing but does not clarify that the tool does not wait for output, the behavior if the session is closed, or what happens when the buffer is empty. The transparency is minimal but not misleading.

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 a single, front-loaded sentence with only 10 words. Every word is meaningful, and there is no redundancy. It achieves maximum information density.

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?

Given the tool's simplicity (2 parameters) and the existence of an output schema, the description covers the essential purpose. However, it could explicitly note that reading is non-blocking and that the buffer content is returned. The completeness is almost adequate but lacks a small nuance.

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

Parameters2/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 compensate. It only hints at the clear_buffer parameter ('optionally clear it') but provides no explanation for session_id. Default values are not mentioned. The parameter semantics are insufficiently explained.

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 the action ('Read'), the resource ('buffered output'), and the condition ('from an active SSH session') with an optional clearing behavior. This distinguishes it from sibling tools like send_input (writes) or wait_for_output (waits).

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus alternatives. It does not mention that it reads the current buffer without waiting, which is key to differentiating from wait_for_output. The description lacks usage context.

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

resize_sessionC

Resize the active SSH session pseudo-terminal.

ParametersJSON Schema
NameRequiredDescriptionDefault
widthYes
heightYes
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only states 'resize', implying mutation, but does not explain side effects, required session state, failure modes, or rate limits. Minimal transparency.

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?

The description is a single sentence with no wasted words. However, extreme brevity sacrifices necessary detail; a bit more structure would improve clarity without losing conciseness.

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

Completeness1/5

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

Given 3 required parameters, no schema descriptions, no annotations, and an output schema (not shown), the description is severely incomplete. It does not clarify parameter units, required session state, return value, or behavior on failure.

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

Parameters1/5

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

Schema description coverage is 0%, and the description adds no meaning to the three parameters (width, height, session_id). No units, constraints, or explanations are given, leaving the agent to guess the format or valid range.

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 the action ('Resize') and the resource ('active SSH session pseudo-terminal'). It is distinct from sibling tools which cover session creation, command execution, file transfer, etc.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. Does not mention prerequisites (e.g., active session), nor does it describe scenarios where resizing is appropriate. Sibling tools exist for session management but no differentiation is provided.

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

run_commandA

Run a command in the existing session. SSH uses the interactive shell; WinRM expects PowerShell script text and runs it via pywinrm run_ps().

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYes
timeoutNo
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries full burden. It discloses that SSH uses an interactive shell and WinRM expects PowerShell script text via pywinrm, which adds useful behavioral context. However, it omits other traits like side effects, permission requirements, or error handling, leaving gaps in transparency.

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 extremely concise: two sentences clearly stating purpose and adding key behavioral distinction. Every sentence earns its place, with no redundant or extraneous information.

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

Completeness3/5

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

Given the tool's complexity (session-based execution, multiple protocols) and existing output schema, the description covers core behavior but lacks context like session creation prerequisite, error scenarios, or connection to sibling tools. It is minimally complete but could better integrate with the broader tool ecosystem.

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

Parameters2/5

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

Schema description coverage is 0%, yet the description does not mention any parameter (command, timeout, session_id) explicitly. It only implies session_id via 'existing session.' No details on command format, timeout semantics, or parameter constraints are provided, failing to compensate for the schema's lack of documentation.

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 the tool's purpose: 'Run a command in the existing session.' It distinguishes between SSH and WinRM by specifying the execution environment (interactive shell vs PowerShell script text), making the purpose specific and unambiguous. Among sibling tools, this is distinct as it targets command execution in an existing session.

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?

The description provides protocol-specific guidance (SSH vs WinRM) but does not explicitly explain when to use this tool over alternatives like send_input or create_ssh_session. It assumes the agent knows to use an existing session but offers no when-not-to or alternative recommendations.

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

send_controlB

Send a supported terminal control key to an active SSH session.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYes
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the full burden. It does not disclose supported keys, destructive behavior, error handling, or prerequisites like session state, leaving significant gaps.

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?

The description is a single clear sentence with no waste. However, it is too brief to be fully useful; adding one sentence about key examples or usage would improve without compromising conciseness.

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

Completeness3/5

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

Given only 2 parameters and no annotations, the description is minimal. The existence of an output schema reduces the need to explain return values, but the lack of guidance on supported keys and required session state leaves it incomplete.

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

Parameters2/5

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

Schema coverage is 0% and no parameter descriptions exist, so the description must compensate. It only mentions 'supported terminal control key' without specifying what keys are valid, leaving ambiguity for the agent.

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 the tool sends a terminal control key to an active SSH session, using a specific verb and resource. It distinguishes from siblings like send_input and run_command.

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?

The description implies use for control keys but does not explicitly state when to use this over siblings like send_input or run_command. No when-not-to-use or alternative guidance is provided.

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

send_inputC

Send raw text to an active SSH session.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

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

No annotations exist, so the description must disclose behavioral traits. It does not indicate whether input is buffered, whether a newline is appended, or what happens if the session is closed. The existence of an output schema is noted but unexplained.

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 a single, clear sentence that is appropriately front-loaded. Every word earns its place; there is no redundancy or missing structure.

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

Completeness3/5

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

Given the tool's simplicity and the presence of an output schema, the description is minimally adequate. However, it could better contextualize the tool among its siblings (e.g., mentioning that it sends input to an interactive session).

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

Parameters2/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 compensate. It does not explain the meaning or expected format of 'text' or 'session_id' beyond their names. No details on encoding, special characters, or required format for the text parameter.

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?

The description clearly states the verb 'Send', the resource 'raw text', and the target 'active SSH session'. It distinguishes from sibling tools like send_control and run_command, but could be more specific about what 'raw text' entails (e.g., whether a newline is appended).

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like send_control or run_command. The description only states what the tool does, not the context or preconditions for its use.

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

upload_fileC

Upload an MCP-server-local file to the remote host over SFTP.

ParametersJSON Schema
NameRequiredDescriptionDefault
local_pathYes
session_idYes
remote_pathYes
create_parentsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

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

Without annotations, the description carries full burden but only states it uploads over SFTP. It does not disclose whether files are overwritten, permission requirements, error handling, or the effect of 'create_parents'.

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 a single, front-loaded sentence with no wasted words, conveying the core purpose efficiently.

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

Completeness1/5

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

Despite having an output schema, the description does not explain return values, error conditions, or provide usage context. For a 4-parameter tool with 0% schema coverage, this is severely incomplete.

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

Parameters1/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 add parameter meaning. It fails to explain any parameters beyond their names, leaving 'create_parents' and other arguments ambiguous.

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 the action 'upload', the source 'MCP-server-local file', and the destination 'remote host over SFTP', distinguishing it from the sibling 'download_file'.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like 'run_command' or 'download_file', nor does it mention prerequisites such as an active session.

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

wait_for_outputC

Wait for remote session output matching a regex or literal pattern.

ParametersJSON Schema
NameRequiredDescriptionDefault
regexNo
patternYes
timeoutYes
session_idYes
clear_bufferNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

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

With no annotations, the description bears full responsibility for disclosing behavior. It mentions waiting and pattern matching but omits critical details: blocking until timeout, what happens on no match, and side effects like buffer clearing. The 'clear_buffer' parameter suggests output consumption, which is not addressed.

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 description is a single concise sentence, front-loading the core action. However, it sacrifices necessary details for brevity, making it insufficient for complete understanding given the tool's complexity.

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

Completeness2/5

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

Given the 5 parameters, lack of annotations, and an output schema, the description should cover the wait loop, return value, and buffer behavior. It only covers the basic matching concept, leaving significant gaps for effective tool invocation.

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

Parameters2/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 compensate by explaining parameters. It only hints at 'regex' via the matching mention but does not clarify 'clear_buffer', 'session_id', or timeout behavior. The agent must infer meanings from parameter names alone.

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?

The description clearly states the tool's action ('wait for') and resource ('remote session output') with the matching mechanism ('regex or literal pattern'). It effectively distinguishes from sibling tools like 'read_output', which reads current output without waiting. However, it could be more explicit about the blocking nature and timeout behavior.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like 'read_output' or other session tools. The description lacks context on prerequisites, conditions, or exclusions, leaving the agent to infer usage from the name and siblings.

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

warm_sudo_cacheC

Warm sudo credentials using server-managed gopass sudo password.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It only states that it 'warm[s] sudo credentials using server-managed gopass sudo password.' It does not disclose side effects (e.g., whether it requires a TTY, modifies session state, or has rate limits). The output schema exists but is not referenced, missing an opportunity to clarify return behavior.

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 description is a single sentence with no fluff, but it is overly concise. It could benefit from additional context, such as prerequisites or typical usage, without becoming verbose. The structure is simple and front-loaded, but the brevity sacrifices clarity.

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

Completeness2/5

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

Given the tool's specific purpose and the presence of sibling tools, the description is incomplete. It does not mention prerequisites (e.g., an active SSH session), what happens if the cache is already warm, or how to interpret the output. The output schema is not referenced in the description, leaving the agent without guidance on return values.

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

Parameters1/5

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

The input schema has 0% description coverage, and the description adds no parameter details. It does not explain that 'session_id' likely identifies an SSH session or that 'timeout' is in seconds. The description fails to compensate for the schema's lack of documentation, leaving the agent to guess parameter semantics.

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 the tool's purpose: to warm sudo credentials using a gopass password. The verb 'warm' is specific to the action of pre-authenticating sudo. The tool is distinguished from siblings like 'check_sudo_cache' and 'clear_sudo_cache', which handle different aspects of sudo cache management.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. With siblings like 'check_sudo_cache' and 'clear_sudo_cache', the description should clarify scenarios for each, e.g., proactive warming vs checking status. The current description implies usage but does not explicitly state context or exclusions.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 16 tool updatesv0.1.0
    • First observedcheck_sudo_cache
    • First observedclear_sudo_cache
    • First observedclose_ssh_session
    • First observedcreate_ssh_session
    • First observedcreate_winrm_session
    • First observeddownload_file
    • First observedlist_credentials
    • First observedlist_sessions
    • First observedread_output
    • First observedresize_session
    • First observedrun_command
    • First observedsend_control
    • First observedsend_input
    • First observedupload_file
    • First observedwait_for_output
    • First observedwarm_sudo_cache
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 16 tools

Disambiguation5/5

Every tool targets a distinct action: session creation (SSH vs WinRM), session management, file transfer, sudo cache handling, and command execution. No two tools have overlapping purposes, making selection unambiguous for an agent.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_ssh_session, warm_sudo_cache). The few exceptions like read_output still adhere to the pattern, ensuring predictability.

Tool Count5/5

With 16 tools covering session lifecycle, file transfer, credential listing, and sudo cache management, the count is well-scoped for the server's domain. Each tool serves a clear purpose without redundancy or excessive granularity.

Completeness4/5

The tool set covers core workflows: create/close/list sessions, run commands, transfer files, and manage sudo cache. However, missing a close_winrm_session tool and lacking credential management beyond listing are minor gaps that agents may need to work around.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Simple SSH MCP Server

    bhayanak
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI assistants full SSH/SFTP remote operations — session management, command execution, interactive shells, file transfers, port forwarding, and system diagnostics.
    2
    MIT

  • mcp-remote-ssh

    faizbawa
    A
    license
    A
    quality
    A
    maintenance
    MCP server giving AI agents full SSH access with persistent sessions, structured command output, SFTP file transfer, and port forwarding.
    18
    10
    MIT

  • ssh-mcp

    slepp
    A
    license
    A
    quality
    C
    maintenance
    An MCP server that gives AI agents SSH access to remote machines through your local OpenSSH client, enabling remote command execution, file transfer, persistent shell sessions, and port forwarding.
    17
    23
    MIT

  • mcp-ssh-interactive

    qnxqnxqnx
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that enables AI agents to run fully interactive SSH sessions (via tmux) and execute commands like a human operator, with persistent sessions and multiple concurrent connections.
    6
    MIT