AI agents (MCP)

KubeDrive can serve your clusters to AI agents over the Model Context Protocol. The agent asks KubeDrive, and KubeDrive answers with the connections it already has: your kubeconfig, your SSO sessions, your RBAC permissions. The agent never gets a kubeconfig or a token for the cluster.

Reading is free and off until you turn it on, for one agent at a time: a second client (Claude Code and Codex together, say) is served with Pro. Changes by agents are part of KubeDrive Pro, off until you turn them on, and every change waits for your Allow in a window.

Turn it on

Press ⌘K and choose AI Agents….
Click Turn On. The server runs at http://127.0.0.1:47011/mcp, on your computer only.
Tick the clusters agents may read. None are shared until you choose. A shared cluster is remembered with the API server it points at: if your kubeconfig later points that context name at another cluster, agents are refused until you tick it again.

The robot icon in the title bar, next to the theme button, shows the server’s state: grey while it is off, blue with the number of shared clusters while it runs, red if it should run but cannot. It lights up at each call an agent makes; click it to open the AI Agents window, which counts the calls and names the last one. That is how you tell an agent is really connected.

Connect Claude Code

Copy the command from the AI Agents window and run it in Terminal. It looks like this, with your own token:

claude mcp add --transport http kubedrive http://127.0.0.1:47011/mcp \
  --header "Authorization: Bearer kd_…"

Then ask Claude Code things like “why is the checkout deployment in staging not ready?” or “which pods restarted most in the last hour?”.

Connect Codex

Add the entry from the AI Agents window to ~/.codex/config.toml. The Codex CLI, the Codex app and the IDE extension read the same file. It looks like this, with your own token:

[mcp_servers.kubedrive]
url = "http://127.0.0.1:47011/mcp"
http_headers = { "Authorization" = "Bearer kd_…" }

codex mcp add kubedrive --url … adds the server too, but it has no flag for the header, so the token still has to go into the file.

Connect Claude Desktop

Claude Desktop speaks MCP over stdio only, so KubeDrive ships a small bridge, kubedrive-mcp, beside the app. The AI Agents window shows the entry to add to claude_desktop_config.json (Claude → Settings → Developer → Edit Config): the bridge’s path and your token in its environment. The bridge forwards every message to the local server; while KubeDrive is not running, or its AI Agents server is off, it answers with an error that says so.

Connect Cursor and other clients

Add the JSON from the AI Agents window to the client’s MCP settings:

{
  "mcpServers": {
    "kubedrive": {
      "url": "http://127.0.0.1:47011/mcp",
      "headers": { "Authorization": "Bearer kd_…" }
    }
  }
}

Rules for a cluster

Each shared cluster has its own rules: click Rules… in its row. They are checked before anything is read and before the window of a change, so an agent that hits one gets a plain error naming the rule, not a window you would decline.

Reading: all namespaces, or only the ones you list. With a list, every read names one of them, and tools that read the whole cluster (cluster_problems, upgrade_check, rightsizing, top of nodes) are refused. Hide Secrets entirely keeps even their keys and sizes from the agent.
Changes (Pro): everywhere, off, or only in the namespaces you list; nodes are outside a namespace list, so cordon and drain are refused with it.
Actions allowed: a box per write tool. delete, exec and drain are off on every cluster until you turn them on.
Confirmation: every change waits for your Allow, as always; or scale and restart in the listed namespaces run without a window, with “by rule” in the journal (never on a protected cluster); or every change asks for the object’s name, as on a protected cluster.
Propose only: the agent’s change becomes a proposal instead. The agent is told at once (“saved as proposal #12, do not retry”), nothing waits, and the Proposals tab keeps it with its dry-run diff until you apply it, through the same tool and as your own change, or discard it. A proposal says when its object changed since; proposals keep for 7 days. Good for production: the agent does the work, the decision stays with you, on your time.

The row of each shared cluster sums its rules up. Reset to defaults takes a cluster back to reading everywhere and changes with a window.

What agents can do

Tool	What it returns
`list_clusters`	the clusters you shared
`list_resource_types`	type ids such as `pods` or `deployments.apps`
`list_resources`	objects of a type, as `kubectl get` shows them; label and field selectors
`get_resource`	one object as YAML
`get_events`	events of an object or a namespace
`get_logs`	the last lines of a container’s log, or of its previous run
`cluster_problems`	what the cluster overview flags: failing pods, stuck rollouts, nodes, warnings
`diagnose`	why an object is unhealthy, by KubeDrive’s rules: each cause with its evidence and a fix
`broken_links`	links that lead nowhere, as the map shows them: an Ingress to a missing Service or port, a Service that selects no pods, a missing ConfigMap, Secret or PVC, an autoscaler or disruption budget with nothing to act on
`timeline`	what happened to an object and what it is joined to, or to the whole cluster, over a window: events, rollouts, restarts, changes made through KubeDrive, Helm revisions, alerts, newest first (beyond an hour: Pro)
`upgrade_check`	what breaks on a newer Kubernetes version: removed APIs in Helm releases and applied manifests, clients still calling them, nodes too old (Pro)
`rightsizing`	containers at risk (killed for memory, throttled, no requests) and over-requested ones, with suggested requests and limits from Prometheus (Pro)
`top`	CPU and memory of pods or nodes
`check_access`	whether you may do something (`kubectl auth can-i`)

With reading only, agents cannot change anything: there are no tools to apply, scale, delete or exec until you turn changes on. Reading rules above apply to every tool here.

Changes by agents (Pro)

In the AI Agents window, Changes by agents adds tools that change the shared clusters. None of them runs on its own: each call opens a window in KubeDrive with the cluster, the object and the action (the diff of an apply, the command of an exec), and the agent waits up to two minutes for your Allow. Credentials stay hidden in that diff, but a hidden value that changes is marked (changed), so a new Secret value or password cannot pass behind a label. Deny, or no answer, comes back to the agent as an error and nothing is changed. A change the cluster’s rules forbid never reaches the window: the agent is told which rule refused it, and the journal shows it as refused by rule. On a protected cluster, for namespaces and cluster-scoped objects, and for drain, you type the object’s name first, as for KubeDrive’s own buttons. KubeDrive then makes the change with your credentials through the same code the buttons use.

Tool	What it does
`apply`	a server-side dry run of the manifest, the diff for you, then the change
`scale`, `restart`, `rollback`	replicas, a rollout restart, a rollout undo
`delete`	one object, with the propagation you choose
`cordon`, `uncordon`, `drain`	nodes, as `kubectl` does it
`trigger_cronjob`	a Job from a CronJob, now
`port_forward`, `port_forward_stop`	a local port on your computer to a pod, service or workload
`exec`	one command in a container, no shell, outputs capped at 256 KB

Every change tool takes an optional reason, one line in the agent’s words, shown with the change in the window, the sessions and the proposals: ask your agent to always give one.

When an agent is doing a run of changes you trust, tick Also allow everything else on this cluster for 10 minutes in the window: further changes there run without a window for that long, protected ones still ask, and the AI Agents window shows the period with a Stop button. It ends on its own, and with the app.

The window keeps a journal of the last 50 changes agents asked for: the tool, the object and whether you allowed it. The Sessions tab has the whole story: every call of every agent, grouped into sessions (one client’s calls with no 30-minute pause), with the object, the arguments of a read, and for a change what the confirmation window showed you, credentials masked. Results are never kept. The list lives on your computer, next to the settings.

Roll back session… in a session undoes what the agent changed, newest change first: each object goes back to what the history of changes recorded before the agent touched it, with a dry run before each. The plan says what it cannot undo (a command run with exec, a drain, a port forward, a CronJob that ran) and marks objects someone changed since, which stay as they are unless you include them. On a protected cluster you type its name. The roll back runs with your credentials and lands in the history as your own changes.

Privacy and safety

The server listens on 127.0.0.1 only and needs the token. Requests from web pages are refused.
Secret values never leave KubeDrive: a Secret shows its keys and sizes only. Elsewhere KubeDrive masks what looks like a credential: environment values and fields named like PASSWORD or TOKEN (in ConfigMaps and custom resources too), passwords in URLs, bearer tokens, JWTs, cloud keys and private keys, in objects and in logs. This is a heuristic: keep credentials in Secrets.
What the agent reads goes to the agent’s AI provider, as with anything else you show it. Share only clusters you are happy for it to read.
New Token in the AI Agents window turns away every agent set up with the old token. Turn Off stops the server.