MCP Server & Automation

Kunobi runs a built-in Model Context Protocol (MCP) server. MCP is an open standard that lets AI clients connect to external tools and data. With it enabled, assistants like Claude Code, OpenAI Codex, Cursor, Windsurf, and Gemini CLI can inspect your connected clusters and - with the right permissions - operate on them, using the same tools Kunobi uses internally.

For the assistant built into Kunobi, see AI Assistant. This page is about exposing Kunobi to external clients.

Enabling the MCP Server

Open Settings → AI & MCP.
Turn on the Enable MCP Server toggle. The server starts immediately on localhost, listening on its configured port (for example 3200).

Setting the Port

Use the Server Port field to choose which port the server listens on. Set it to 0 to use the per-variant default. To change the port, turn the server off, set the new port, and turn it back on.

Each Kunobi variant uses a dedicated default port so multiple variants can run at the same time:

Variant	Default MCP port
Stable	`3200`
Unstable	`3300`
Dev	`3400`
Local	`3500`

Connecting AI Clients

Once the server is running, the fastest way to wire up your clients is the one-command installer:

npx @kunobi/mcp install

This configures MCP for supported AI clients (such as Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex, and GitHub Copilot CLI) in one step. To remove it from a client later, use that client's own command, such as claude mcp remove kunobi or codex mcp remove kunobi.

Read Tools

By default the MCP server exposes read-only tools, so a client can inspect your cluster and Kunobi's state without changing anything:

App info - Kunobi's version, variant, and status.
App state - Kunobi's current state, such as the selected cluster and view.
Kubernetes - inspect resources: get, list, and describe across namespaces.
Kubectl (read-only) - run read-only kubectl queries.
App events - events and activity surfaced in the app.
Resource graph - query relationships between resources (search, expand, paths, and facts).

Write Tools & Cluster Operations

Mutating operations - scaling, restarting, patching, deleting, cordoning and draining nodes, rolling out restarts, reconciling Flux, syncing Argo CD, and similar - are exposed as write tools. They are off unless you deliberately turn them on, and they require Pro.

To enable them, turn on the write-tools option in Settings → AI & MCP with a Pro license active. Until then, external clients can only read.

Approvals

Because write tools can change your cluster, Kunobi can require your approval before an action runs:

Approval threshold - how risky an action must be before it needs approval. By default, actions marked dangerous (like delete) require your confirmation.
Approval timeout - how long Kunobi waits for you to respond before dropping the request.
Temporary auto-approve - grant a short window during which matching actions are approved automatically, for when you're actively working alongside the assistant.

Audit Log

Every action the assistant takes through the MCP server is recorded in an audit log you can search and export. By default it keeps up to 1,000 entries for 30 days; both limits are configurable.

Troubleshooting

The server won't start - the chosen port may be in use; switch back to the default (0) or pick another port, then restart Kunobi.

A client can't connect - confirm the server shows a running status in settings and that the port in the client's configuration matches the one shown. For Claude Code, claude mcp list shows whether the kunobi server is registered.

The port changed after a restart - expected when using the auto-selected default. Point your client at the port shown in settings, or set a fixed port to keep it stable.