MCP server

Kubyl runs a local MCP server, on by default, at http://127.0.0.1:7421/mcp (also on [::1]). An MCP client such as Claude Code gets every cluster Kubyl is connected to, with the same tools, masking and RBAC as an agent thread. Kubyl has to be running.

Connect a client#

• Claude Code. Run MCP: Copy Claude Code Command in the palette and paste the command into a terminal.
• Other clients. Run MCP: Copy Client Config (JSON) and put the result in the client's MCP settings.
• Claude Desktop. Install the kubyl-0.10.0.mcpb extension (double-click it, or drag it into Claude Desktop's extension settings). It asks for the access token (MCP: Copy Token, or Copy token in MCP: Show Server) and the port. The extension needs Node.js 18 or newer.

A status bar item shows the state: green for running, grey for standby, red for failed and yellow when a change waits for you. It is hidden while the server is off.

Tools#

The tools are those of AI agents: cluster_info, list_resources, get_resource, describe, events, logs, top, query_prometheus, alerts, can_i and api_resources. Differences for outside clients:

• list_clusters lists the connected clusters.
• Every tool takes an optional cluster, because there is no thread to say which one you mean.
• logs returns 500 lines when the client does not say.
• Output is limited by agent.max_tool_output_kib, as for agents.

Changes from outside clients#

Changes are off by default (mcp.writes: "off"). With mcp.writes: "ask" the server offers the same five change tools as an agent thread (apply_manifest, patch_resource, delete_resource, scale_resource, restart_resource), and each change opens an approval dialog in Kubyl with the diff. Production clusters need the cluster's name typed. Dry run, version and UID checks, the refusal of Secrets, Helm release storage and read-only clusters, and the 10 minute timeout work as described in Allow changes.

Security#

• Local only. The server listens on loopback. A request with an Origin header, with a Host that is not loopback (DNS rebinding) or with the wrong token is refused.
• Token. One bearer token, made once and kept in the OS keychain, so client configs survive restarts. Regenerate it if it leaks.
• Masking and RBAC. Secret values are masked the same way as for agents, and every call uses your own credentials.
• What the client sees goes to its provider. Any data a client reads is sent wherever that client sends its context.
• Several Kubyl instances. If another Kubyl that accepts the same token already holds the port, this one waits in standby and takes over when it quits. A port held by anything else is reported as an error, never swapped for another one.

Settings#

Keys live under mcp in settings.json. Changes apply without a restart. See Settings.

{
  "mcp": {
    "enabled": true,
    "port": 7421,
    "writes": "off"
  }
}