Skip to content

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.

k8s_apply

Create or update a Kubernetes object from a JSON manifest (server-side apply). REQUIRES an allow rule for verb=apply; the action may be approval-gated (a human must approve before it runs). Use dry_run=true to preview the BROKER policy decision. The manifest's apiVersion/kind/metadata must match the resource/group/namespace/name arguments.

  • cluster (string) (required) — logical name of the target cluster (see k8s_list_clusters)
  • dry_run (boolean) — if true, SIMULATE the policy decision without applying (this is the BROKER policy dry-run, not the API server's --dry-run)
  • group (string) — API group; omit for core resources
  • manifest (string) (required) — the object manifest as a JSON document (server-side apply). Must include apiVersion, kind, and metadata.name/namespace matching the fields above.
  • name (string) (required) — object name; must match metadata.name in the manifest
  • namespace (string) — namespace; omit only for cluster-scoped resources
  • resource (string) (required) — lowercase plural resource of the manifest, e.g. deployments

k8s_delete

Delete one Kubernetes object. REQUIRES an allow rule for verb=delete; the action may be approval-gated. Use dry_run=true to preview the policy decision without deleting.

  • cluster (string) (required) — logical name of the target cluster (see k8s_list_clusters)
  • dry_run (boolean) — if true, SIMULATE: report whether the action would be allowed by the cluster policy (allow/deny/approval) WITHOUT calling the API server
  • group (string) — API group; omit for core resources (pods, services...). The broker fills it in from the cluster's resource table.
  • name (string) (required) — object name
  • namespace (string) — namespace; omit only for cluster-scoped resources (nodes, namespaces, persistentvolumes)
  • resource (string) (required) — lowercase plural resource, e.g. pods, deployments, services, configmaps

k8s_get

Get one Kubernetes object as JSON. REQUIRES an allow rule for this verb/resource in the cluster policy; if the broker returns not allowed, DO NOT retry — inform the user. Use dry_run=true to preview whether the action is permitted.

  • cluster (string) (required) — logical name of the target cluster (see k8s_list_clusters)
  • dry_run (boolean) — if true, SIMULATE: report whether the action would be allowed by the cluster policy (allow/deny/approval) WITHOUT calling the API server
  • group (string) — API group; omit for core resources (pods, services...). The broker fills it in from the cluster's resource table.
  • name (string) (required) — object name
  • namespace (string) — namespace; omit only for cluster-scoped resources (nodes, namespaces, persistentvolumes)
  • resource (string) (required) — lowercase plural resource, e.g. pods, deployments, services, configmaps

k8s_list

List Kubernetes objects of a resource type as JSON, optionally filtered by label/field selectors. Omit namespace to list across all namespaces the ServiceAccount can read. REQUIRES an allow rule; use dry_run=true to preview.

  • cluster (string) (required) — logical name of the target cluster (see k8s_list_clusters)
  • dry_run (boolean) — if true, SIMULATE the policy decision without calling the API server
  • field_selector (string) — field selector, e.g. status.phase=Running
  • group (string) — API group; omit for core resources
  • label_selector (string) — label selector, e.g. app=nginx,tier=frontend
  • limit (integer) — maximum number of items to return
  • namespace (string) — namespace to list in; omit to list across all namespaces the ServiceAccount can read
  • resource (string) (required) — lowercase plural resource, e.g. pods, deployments

k8s_list_clusters

List the Kubernetes clusters accessible to the caller (clusters outside the user's RBAC groups are not listed). ALWAYS call before the other k8s_* tools to learn the available cluster names.

k8s_logs

Read a pod's container logs (plain text). REQUIRES an allow rule for verb=logs; use dry_run=true to preview.

  • cluster (string) (required) — logical name of the target cluster (see k8s_list_clusters)
  • container (string) — container name; omit for a single-container pod
  • dry_run (boolean) — if true, SIMULATE the policy decision without fetching logs
  • namespace (string) (required) — namespace of the pod
  • pod (string) (required) — pod name
  • since_seconds (integer) — only logs newer than this many seconds
  • tail_lines (integer) — number of lines from the end to return (default 200)

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_get_file

Read a file from a Linux host via SSH with an ephemeral credential. Returns the content as text, or base64 (base64=true in the result) when the file is not valid UTF-8. REQUIRES allow_file_transfer=true on the host (see ssh_list_servers); if false DO NOT retry, the signer will reject it. The read runs as the host's configured SSH user (no sudo); the file must be readable by that user. A file larger than max_bytes (default: the broker's file_transfer_max_bytes, 512 KiB) is an ERROR, not a truncation. The content's sha256 is recorded in the audit log.

  • max_bytes (integer) — read at most this many bytes; a larger file is an error, not a truncation. Omit for the broker's configured limit.
  • path (string) (required) — absolute path of the file to read on the host
  • server (string) (required) — logical name of the target host (see ssh_list_servers)
  • 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. allow_file_transfer=true → ssh_put_file and ssh_get_file may be used; allow_file_transfer=false → DO NOT attempt file transfers, the signer will reject them. jump → name of the bastion through which the host is reached (informational).

ssh_put_file

Write a file on a Linux host via SSH with an ephemeral credential. Creates or OVERWRITES the destination file with the given content. Use content_base64=true for binary data (the content field is decoded before writing). REQUIRES allow_file_transfer=true on the host (see ssh_list_servers); if false DO NOT retry, the signer will reject it. The write runs as the host's configured SSH user (no sudo); the destination must be writable by that user. On hosts with a command policy the transfer command (cat > path) must also be allowed by the policy. Content is limited by the broker's file_transfer_max_bytes (default 512 KiB). The content's sha256 is recorded in the audit log.

  • content (string) (required) — file content. Text as-is, or base64 with content_base64=true for binary data.
  • content_base64 (boolean) — if true, content is base64-encoded and is decoded before writing (required for binary files)
  • mode (string) — optional octal permissions to chmod after writing, e.g. 0644 or 0755
  • path (string) (required) — absolute destination path on the host; the file is created or overwritten
  • server (string) (required) — logical name of the target host (see ssh_list_servers)
  • ttl_seconds (integer) — ephemeral certificate validity in seconds; omit to use the maximum allowed by the host policy

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; target and bastion access, end-user groups, sudo, sudo_user, PTY, and the host's physical route are revalidated, and 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 revalidate target and bastion access, end-user groups, sudo, sudo_user, PTY, and the host's physical route for 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