MCP and the AI agent
kcore has two ways to let a model work on a cluster. Both use the same tools and the same rule: the model asks questions, shows a plan, and changes nothing until a person says yes.
- kcore MCP is a server for editors and chat clients that speak the Model Context Protocol: Cursor, VS Code, Claude Desktop, Zed, Continue.
kctl agentis a chat page in thekctlbinary. Nothing else to install.
The rule: ask, plan, apply
kcore_advisereturns the questions an operator still has to answer: image URL, checksum, network, SSH key, node, disk. The model must put them to you. It does not guess.kcore_planshows the diff against the controller: create, update, or refused because a field is immutable.kcore_apply,kcore_delete, andkcore_operationrun only after you approve. Apply is an upsert: it creates what is missing, updates mutable fields, and rejects immutable changes.
Node installs partition disks. They need the exact phrase wipe the selected disks in the spec, typed by the operator.
Tools
| Tool | What it does |
|---|---|
kcore_catalog | Resource kinds and which fields can change. |
kcore_advise | Questions to ask before a change. Read-only. |
kcore_plan | Local diff, plus a controller read. |
kcore_apply | Declarative apply after confirm: true. |
kcore_read | Get and describe calls. |
kcore_delete | Delete, or cancel a cluster update that has not finished. |
kcore_operation | Power, migrate, drain, cordon, approve a node, set the cluster version (canary by default), approve, promote, cancel, or roll back an update, install a node. |
kcore_rpc | Any unary controller, node agent, Provisioning, or Vault RPC. Calls that are not a get, list, classify, check, or plan need confirm: true. |
With kcore_rpc the same assistant that creates a VM can list a Provisioning machine, read a Vault inventory, or start a restore, with the same approval step.
kcore MCP in an editor
The server runs on your machine over stdio and reads ~/.kcore/config, the file kctl uses. It presents your client certificate to the controller, so the roles you have are the roles the model has. It can also bootstrap a first cluster, writing the CA, controller certificate, and client certificate into ~/.kcore.
{
"mcpServers": {
"kcore": {
"command": "npx",
"args": ["-y", "kcore-mcp"]
}
}
}
Needs Node.js 20 or newer. KCORE_CONFIG points at another config file. KCORE_PROVISIONING sets the default Provisioning address. The Vault address defaults to 127.0.0.1:9191. The same server ships as a Cursor plugin with an operator skill that tells the agent to ask, plan, then apply, and as a VS Code extension for Copilot agent mode.
kctl agent
kctl agent
kctl agent --role read-only
kctl agent --role vm-admin --port 8123 --no-browser
A browser tab opens on 127.0.0.1. Sessions are on the left, the chat is in the middle, and each tool call is a card. A change shows an approval card with the exact request. You can approve, decline, or stop. You can say “create a VM for the build runner”, and the agent asks for the image, network, and key in a form with pick lists filled from the cluster.
- Models. OpenAI (ChatGPT sign-in or API key), Anthropic (API key), DeepSeek (API key), OpenCode.
- Clusters. Every context in
~/.kcore/configis a cluster. A session is bound to one cluster and saved with it. - Least privilege.
--role read-onlyor--role vm-adminruns the agent as its own operator,agent-<login>, with a certificate of its own. Controller roles limit it whatever the model writes. - Plan view. The plan renders as a diff in a sandboxed frame. The frame has no network and cannot approve anything.
What keeps it safe
- The model never sees a
confirmargument. The session sets it only after you approve. - The agent listens on loopback only, with a one-time 256-bit session token. Reach it from another machine through an SSH tunnel.
- Certificates and provider keys stay in the
kctlprocess and in files at mode 0600. The browser holds only the session token. - Tool output is redacted (key data, cloud-init secrets, tokens) before it reaches the transcript or the page.
- Everything the agent does is an ordinary controller call as an operator, so it is in the audit log.
Limits
- Your prompts and tool results go to the model provider you chose. Pick a provider you are allowed to send them to. A read-only role limits what can be changed, not what is read.
- Pick lists exist for networks, SSH keys, nodes, VMs, and images. Ceph members and node disks are text fields.
- Without
--roleor--as, the agent uses your context’s identity. Use a role for anything but a single-operator lab.