Skip to main content
Choose the execution environment first, then the tool for each operation. A Host gives the agent commands on one machine. Central gives it a container with the CLIs needed to operate an external control plane. Assigned MCP and HTTP API plugins can be used alongside either environment.

​
Tool selection decision tree

For single-machine operations, this shell branch assumes a simple CLI and no additional service authentication. The Host’s configured connection credentials still apply. Configure Central for control-plane commands, even when the command affects only one remote resource. Host agents retain access to authorized cloud or database CLIs already installed and configured on their Host when no suitable plugin is assigned. Central remains the configuration choice for a new dedicated control-plane command environment.

​
Choose the tool

Use run_shell for a simple pre-installed CLI with usable help and no service authentication. Prefer a plugin for a control-plane CLI when any of these applies:
  • It requires authentication to an external service.
  • Its help does not explain the commands and arguments the agent needs.
  • It is a custom or internal tool whose behavior the agent cannot infer reliably.
Choose a suitable MCP plugin first. Suitable means that its documented tools and input schemas cover the requested operation and that you can scope its access to the agent. An MCP that lacks the operation does not take precedence over an HTTP API plugin that supports it. When no suitable MCP is available, configure an HTTP API plugin with API documentation and structured request arguments. Use Plugins to configure and assign the integration. A plugin’s presence alone does not make it the right tool for every step, and access to live data alone does not take precedence over the simple CLI branch.

​
Combine plugins and shell commands

A task can call an assigned plugin and run shell commands in its configured Host or Central. Use shell commands for helpers, additional tools or capabilities that the plugin lacks. For example, an MCP can retrieve an inventory while a shell command formats a local file. Fallback uses only authorized access and commands available in the configured environment. A missing response from a modifying call does not establish that it failed; do not repeat the operation through another tool without establishing its outcome. For Kubernetes, we recommend containers/kubernetes-mcp-server, deployed in your cluster and added by its URL, such as http://kubernetes-mcp.<namespace>.svc:8080/mcp. Pin its image to a version you have tested, for example quay.io/containers/kubernetes_mcp_server:v0.0.67, rather than a moving tag. Run it read-only (read_only = true in its configuration file) and deny Secrets (denied_resources), and give its service account a Role that grants only get, list and watch, on the resources and in the namespaces your agents need to read. An installation that lets agents change the cluster through it turns read_only off, and must still deny Secrets: keep denied_resources = [{ group = "", version = "v1", kind = "Secret" }] in its configuration file (the setting as of v0.0.67), and leave secrets out of its service account’s Role. Whatever a tool returns, a Secret’s values included, goes into the task’s trace, is stored with the task and is sent to the model provider. This server has no sign-in of its own in that setup, so keep its Service reachable only inside the cluster: the engine reaches an internal address over plain HTTP without any setting.

​
Configuration and scope

An agent never creates a Central, installs a plugin or changes its own execution target. If the required environment or access is missing, the agent reports the configuration needed. Configure and test it before creating a new task. Give each agent only the plugins and credentials its operations need. Keep unrelated tools out of the context. The stored credential catalog lists secrets managed by 2501. It does not inventory authentication already configured on a Host, such as a CLI profile, environment or instance role.