Skip to content

MCP tools and permissions ​

Documentation · Client setup

This reference lists Plous's agent tools. For a guided setup, use plous-debug or the assistant panel.

Available tools ​

Standalone setup names its server plous_debug. The panel normally uses plous, with a suffix in Codex if needed. The built-in agent uses the same tool implementations. See Standalone target discovery for the standalone server's context lookup.

TaskToolsResults
Inspect objectskubernetes_resources_read, helm_releases_read, argo_resources_read, flux_resources_readResources, releases, controller status
Read Helm configurationhelm_configuration_readFiltered values, manifests, hooks
Read logskubernetes_logs_readPod or workload log excerpts
Run diagnosticskubernetes_exec_run, kubernetes_diagnostic_runExplicitly enabled commands or temporary tests
Read usagekubernetes_usage_readCurrent Pod, Node, or workload usage and budgets
Compare Helm revisionshelm_diff_readDifferences between stored revisions
Read app recordsworkspace_read, history_readWorkspace and Activity data, saved messages and evidence
Open Plous viewsui_read, kubernetes_show, helm_show, history_showCurrent view information and navigation results. Panel sessions only.

_read tools return information. _show tools open a view. _run tools can change cluster or application state.

Argument rules:

  • kubernetes_logs_read, kubernetes_usage_read, and helm_diff_read take no operation argument.
  • kubernetes_show accepts view=resource, list, or logs.
  • Other show tools take no view argument. helm_show opens revision comparisons, not release lists.
  • For Helm comparisons, revision is the after revision and compare_revision is the before revision.

Resource and history calls include a purpose. Cluster calls use the captured connection identity. Supplying another identity does not grant access. Integration-owned schemas validate arguments before execution. See the tool registry and history implementation.

Monitor evidence ​

All integrations use the same selected cluster. Their statuses describe different things. A Helm release record or controller's Ready condition does not prove current Pod health.

ToolImportant limits
kubernetes_usage_readReads current metrics without opening a chart. Reports times, missing measurements, and completeness. Cannot recover unsaved chart history.
kubernetes_logs_readRequires a Pod or supported workload and an explicit container. Reads at most 16 Pods, 500 lines per Pod, and 64 KiB combined. Reports failed or skipped Pods.
helm_diff_readAn explicit comparison needs two distinct positive stored revisions. Otherwise it compares with the predecessor. Revision 1 uses an empty baseline.

Workload logs follow controller ownership and check Pod identities before and after collection. Excerpts are not complete log history.

See the Kubernetes, Helm, Argo CD, and Flux guides for integration details.

Historical evidence ​

History contains results that were saved. It is not a continuous archive of resource contents. A current read cannot recover a value that was never recorded.

Search matches identify candidate records, not resource counts. Counts and comparisons report incomplete or unknown inputs.

Active diagnostics ​

Enable these through diagnostic setup. Both require a purpose, the selected Kubernetes connection_id, and its default namespace.

ToolRequired inputsBehavior
kubernetes_exec_runPod name, exact uid, container, and command argument arrayOne command in an existing container. No added shell, stdin, or TTY.
kubernetes_diagnostic_runtest (http, dns, or tcp), target, and port for TCPOne built-in probe in a temporary Job using the configured image. Plous builds the command.

timeout_seconds defaults to 30 and accepts 1–120. Output is limited to 64 KiB. Temporary cleanup can take another 10 seconds.

HTTP targets need a full HTTP(S) URL without embedded credentials. Tests do not follow redirects or retry.

Plous records requests before running them and saves results before returning them. A transport or storage failure must not cause an automatic retry of an operation that may already have changed state.

Standalone target discovery ​

A standalone server follows kubeconfig’s current context unless configured with --context. Call kubernetes_context_read with an empty argument object to get the current context, default namespace, and connection IDs.

Scope and delivery ​

Each standalone call captures a single target. Reads may use any namespace allowed by those Kubernetes credentials. Diagnostic operations stay in the captured default namespace.

General chat and history-only views have no live cluster tools. To change a pinned standalone target, update its arguments and reconnect. To change the panel's target, close and reopen its session.

Plous validates and serializes calls, then saves results before delivery. Fatal storage, history, or target errors disable further tool access. A native CLI remains open so you can inspect the error.

Native sessions have no Plous-imposed process deadline or session-wide tool-call cap. The CLI manages model calls and spending. Built-in agent budgets are described in Configuration.

MCP connection details ​

ModeTransportConfiguration
StandaloneNewline-delimited stdin/stdout, with no listening portClient setup
Inside PlousTemporary loopback HTTP endpoint with a per-session bearer tokenAutomatic. Ends when the native session closes.

Do not copy the panel's endpoint or token into global client settings.

The local MCP connection does not make model inference local. Cluster data can go to the CLI's configured provider.

Plous view tools preserve focus and edits. They return opened, blocked, or failed and do not send keystrokes or write resources. Their navigation results are stored separately from searchable cluster evidence.

See AI implementation for the adapter and tool contracts.

Protocol behavior ​

PropertySupport
ProtocolJSON-RPC 2.0, one request per message
AuthenticationPanel HTTP uses a fresh bearer token and rejects Origin headers. Stdio uses subprocess pipes.
InitializationProtocol version 2025-03-26, tools capability
Requestsinitialize, ping, tools/list, tools/call
Notificationsnotifications/initialized, plus cancellation of a matching active request
DiscoveryTool descriptions, schemas, and read/diagnostic annotations
ResultsText content. View tools return navigation results.
Other featuresNo resources or prompt templates

Request IDs must be strings or integers. A tool-call ID cannot be reused in the same session. Inspect tool content for errors even when transport succeeds.

Unsupported methods return JSON-RPC errors. After a fatal tool failure, later calls receive a closed-session response.

Schemas use an object root with operation-specific constraints under dependentSchemas. See the bridge, launch configuration, and client checks for implementation details.