reference mcp tools

⚠️ Auto-generated from the repository — do not edit here. Source: https://github.com/luisgf/ssh-broker/tree/main/docs

MCP tools

The tools exposed by the MCP frontends (cmd/mcp-broker, cmd/mcp-broker-http), with their input schemas — enumerated from the live server (internal/mcpserver.Register). See Tool usage for guidance.

ssh_execute

Execute a single command on a Linux host via SSH with an ephemeral credential. Prefer this tool over ssh_session_open when you only need to run one command or independent commands. Returns stdout, stderr and exit_code. exit_code != 0 means remote command failure, NOT a tool error; treat it like a process that exits with an error. BEFORE calling: use ssh_list_servers to learn the host capabilities. sudo=true ONLY if allow_sudo=true; if allow_sudo=false, DO NOT retry with sudo and inform the user. pty=true ONLY if allow_pty=true and the command needs a TTY (with pty, stdout and stderr are merged). ttl_seconds is optional; omit to use the maximum allowed by the host policy.

• command (string) (required) — command to execute on the host
• dry_run (boolean) — if true, SIMULATE: check whether the command would be allowed by the host policy (allow/deny and whether it requires approval) WITHOUT executing it. Does not connect to the host or produce stdout. Useful to preview before executing.
• pty (boolean) — if true, request a pseudo-terminal (stdout and stderr are merged). Requires allow_pty=true in ssh_list_servers. Use only for commands that need a TTY. If allow_pty=false DO NOT retry.
• server (string) (required) — logical name of the target host (see ssh_list_servers)
• sudo (boolean) — if true, execute with sudo -n (NOPASSWD). Requires allow_sudo=true in ssh_list_servers. If allow_sudo=false DO NOT retry: inform the user that the host does not allow elevation.
• sudo_user (string) — target user for sudo (empty = root). Must be in the host's allowed_sudo_users list.
• ttl_seconds (integer) — ephemeral certificate validity in seconds; omit to use the maximum allowed by the host policy

ssh_list_servers

List the hosts accessible to the caller with their capabilities (hosts outside the user's RBAC groups are not listed). ALWAYS call before ssh_execute or ssh_session_open. Fields per host: allow_sudo=true → the host accepts NOPASSWD sudo elevation (sudo=true may be used); allow_sudo=false → DO NOT attempt sudo, the signer will reject it. allow_pty=true → the host accepts PTY (pty=true or mode=pty may be used); allow_pty=false → DO NOT attempt PTY. jump → name of the bastion through which the host is reached (informational).

ssh_session_close

Close a persistent SSH session and release the connection. Always call when done working with a session; an unclosed session keeps its SSH connection until it is reaped by the idle or maximum-lifetime timeout (not by the certificate TTL).

• session_id (string) (required) — id of the session to close

ssh_session_exec

Execute a command in a session opened with ssh_session_open. Returns stdout, stderr and exit_code. exit_code != 0 means remote command failure, NOT a tool error. The command is preflighted against the current signer policy before execution; audit-mode policy warnings are returned in warnings. If a policy is enabled after a shell/pty session was opened, later commands in that session are rejected. Session state (current directory, environment variables) persists across calls when mode=shell or mode=pty.

• command (string) (required) — command to execute in the session
• session_id (string) (required) — id returned by ssh_session_open

ssh_session_open

Open a persistent SSH session that reuses the connection across commands. Use when you need multiple commands with shared state (e.g. cd to a directory and then operate in it) or interactive programs. For isolated commands prefer ssh_execute (simpler, stronger isolation guarantee). Available modes: exec (default, independent commands), shell (stateful sh: cd and variables persist), pty (shell with TTY for interactive programs). sudo=true ONLY if allow_sudo=true (see ssh_list_servers); if allow_sudo=false DO NOT retry. mode=pty ONLY if allow_pty=true. Every ssh_session_exec is preflighted against the current signer policy, so policy reloads affect already-open sessions. On command-policy hosts, mode=exec is allowed; mode=shell and mode=pty are rejected. Returns session_id for use with ssh_session_exec. IMPORTANT: always close the session with ssh_session_close when done; an open session holds an SSH connection and is otherwise closed only after an idle or maximum-lifetime timeout (it is NOT bound to the certificate TTL).

• mode (string) — exec (default): isolated commands with no shared state. shell: persistent sh, cd and environment variables survive across ssh_session_exec calls. pty: shell with pseudo-terminal for interactive programs (editors, less, etc.); requires allow_pty=true. If allow_pty=false DO NOT use pty.
• server (string) (required) — logical name of the target host (see ssh_list_servers)
• sudo (boolean) — if true, start with sudo -n elevation (NOPASSWD). In mode=shell/pty elevates the whole shell process. In mode=exec prepends sudo to each individual command. Requires allow_sudo=true in ssh_list_servers. If allow_sudo=false DO NOT retry.
• sudo_user (string) — target user for sudo (empty = root). Must be in the host's allowed_sudo_users list.
• ttl_seconds (integer) — connection certificate validity in seconds; omit to use the maximum allowed by the host policy