MCP Server

The KSail MCP (Model Context Protocol) server exposes all KSail commands as tools for MCP-compatible AI assistants and automation systems. This enables AI assistants like Claude Desktop to create, configure, and manage Kubernetes clusters, and lets automation scripts orchestrate complex cluster operations through a universal interface.

KSail can be found in the GitHub MCP Registry — search for io.github.devantler-tech/ksail to discover and install it directly from supported MCP clients.

Prerequisites

KSail CLI installed and in PATH
Docker running (for local cluster operations)
An MCP-compatible client (Claude Desktop, VSCode with KSail extension, or custom MCP client)

Starting the Server

The MCP server runs over stdio and is invoked by MCP clients:

ksail open mcp

The server listens on stdin, exposes supported KSail commands as MCP tools, and exits when the client disconnects. See Integration Examples for typical usage patterns.

Available Tools

The MCP server generates tools from the KSail command tree, consolidating commands by permission level into 5 tools:

Tool	Access	Description	Subcommand parameter
`cluster_read`	Read-only	Manage cluster lifecycle	`command`
`cluster_write`	Write	Manage cluster lifecycle	`command`
`tenant_write`	Write	Manage tenant lifecycle	`tenant_command`
`workload_read`	Read-only	Manage workload operations	`workload_command`
`workload_write`	Write	Manage workload operations	`workload_command`

These commands are not exposed as tools (interactive or long-running commands and shell helpers): completion, help, open, operator.

Each tool takes a subcommand parameter selecting the operation, plus the merged flags of its subcommands. Subcommands marked below also accept positional arguments via the args parameter.

cluster_read

Manage cluster lifecycle — read-only subcommands of ksail cluster. Select the operation via the command parameter.

Subcommand	Description	Accepts `args`
`diagnose`	Diagnose failing cluster resources	Yes
`diff`	Show configuration drift between ksail.yaml and live cluster	Yes
`info`	Display cluster information	Yes
`list`	List clusters	Yes
`repair`	Repair local KSail/Talos state files	Yes

cluster_write

Manage cluster lifecycle — write subcommands of ksail cluster. Select the operation via the command parameter.

Subcommand	Description	Accepts `args`
`backup`	Backup cluster resources	Yes
`create`	Create a cluster	Yes
`delete`	Destroy a cluster	Yes
`init`	Initialize a new project	Yes
`restore`	Restore cluster resources from backup	Yes
`start`	Start a stopped cluster	Yes
`stop`	Stop a running cluster	Yes
`update`	Update a cluster configuration	Yes

tenant_write

Manage tenant lifecycle — write subcommands of ksail tenant. Select the operation via the tenant_command parameter.

Subcommand	Description	Accepts `args`
`create`	Create a new tenant	Yes
`delete`	Delete a tenant	Yes

workload_read

Manage workload operations — read-only subcommands of ksail workload. Select the operation via the workload_command parameter.

Subcommand	Description	Accepts `args`
`describe`	Describe resources	Yes
`explain`	Get documentation for a resource	Yes
`export`	Export container images from the cluster	Yes
`forward`	Forward one or more local ports to a pod	Yes
`gen_clusterrole`	Create a cluster role	Yes
`gen_clusterrolebinding`	Create a cluster role binding for a particular cluster role	Yes
`gen_configmap`	Create a config map from a local file, directory or literal value	Yes
`gen_cronjob`	Create a cron job with the specified name	Yes
`gen_deployment`	Create a deployment with the specified name	Yes
`gen_helmrelease`	Generate a HelmRelease resource	Yes
`gen_ingress`	Create an ingress with the specified name	Yes
`gen_job`	Create a job with the specified name	Yes
`gen_namespace`	Create a namespace with the specified name	Yes
`gen_poddisruptionbudget`	Create a pod disruption budget with the specified name	Yes
`gen_priorityclass`	Create a priority class with the specified name	Yes
`gen_quota`	Create a quota with the specified name	Yes
`gen_role`	Create a role with single rule	Yes
`gen_rolebinding`	Create a role binding for a particular role or cluster role	Yes
`gen_secret_docker-registry`	Create a secret for use with a Docker registry	Yes
`gen_secret_generic`	Create a secret from a local file, directory, or literal value	Yes
`gen_secret_tls`	Create a TLS secret	Yes
`gen_service_clusterip`	Create a ClusterIP service	Yes
`gen_service_externalname`	Create an ExternalName service	Yes
`gen_service_loadbalancer`	Create a LoadBalancer service	Yes
`gen_service_nodeport`	Create a NodePort service	Yes
`gen_serviceaccount`	Create a service account with the specified name	Yes
`get`	Get resources	Yes
`images`	List container images required by cluster components	No
`logs`	Print container logs	Yes
`scan`	Run security scans on Kubernetes manifests	Yes
`validate`	Validate Kubernetes manifests and kustomizations	Yes
`wait`	Wait for a specific condition on one or many resources	Yes

workload_write

Manage workload operations — write subcommands of ksail workload. Select the operation via the workload_command parameter.

Subcommand	Description	Accepts `args`
`apply`	Apply manifests	Yes
`apply_edit-last-applied`	Edit latest last-applied-configuration annotations of a resource/object	Yes
`apply_set-last-applied`	Set the last-applied-configuration annotation on a live object to match the contents of a file	Yes
`apply_view-last-applied`	View the latest last-applied-configuration annotations of a resource/object	Yes
`cipher_decrypt`	Decrypt a file with SOPS	Yes
`cipher_edit`	Edit an encrypted file with SOPS	Yes
`cipher_encrypt`	Encrypt a file with SOPS	Yes
`cipher_import`	Import an age key to the system’s SOPS key location	Yes
`cipher_rotate`	Rotate data keys for SOPS-encrypted files	Yes
`create`	Create resources	Yes
`create_clusterrole`	Create a cluster role	Yes
`create_clusterrolebinding`	Create a cluster role binding for a particular cluster role	Yes
`create_configmap`	Create a config map from a local file, directory or literal value	Yes
`create_cronjob`	Create a cron job with the specified name	Yes
`create_deployment`	Create a deployment with the specified name	Yes
`create_helmrelease`	Create or update a HelmRelease resource	Yes
`create_ingress`	Create an ingress with the specified name	Yes
`create_job`	Create a job with the specified name	Yes
`create_kustomization`	Create or update a Kustomization resource	Yes
`create_namespace`	Create a namespace with the specified name	Yes
`create_poddisruptionbudget`	Create a pod disruption budget with the specified name	Yes
`create_priorityclass`	Create a priority class with the specified name	Yes
`create_quota`	Create a quota with the specified name	Yes
`create_role`	Create a role with single rule	Yes
`create_rolebinding`	Create a role binding for a particular role or cluster role	Yes
`create_secret`	Create a secret using a specified subcommand	Yes
`create_secret_docker-registry`	Create a secret for use with a Docker registry	Yes
`create_secret_generic`	Create a secret from a local file, directory, or literal value	Yes
`create_secret_tls`	Create a TLS secret	Yes
`create_service`	Create a service using a specified subcommand	Yes
`create_service_clusterip`	Create a ClusterIP service	Yes
`create_service_externalname`	Create an ExternalName service	Yes
`create_service_loadbalancer`	Create a LoadBalancer service	Yes
`create_service_nodeport`	Create a NodePort service	Yes
`create_serviceaccount`	Create a service account with the specified name	Yes
`create_source_git`	Create or update a GitRepository source	Yes
`create_source_helm`	Create or update a HelmRepository source	Yes
`create_source_oci`	Create or update an OCIRepository source	Yes
`create_token`	Request a service account token	Yes
`debug`	Create debugging sessions for troubleshooting workloads and nodes	Yes
`delete`	Delete resources	Yes
`exec`	Execute a command in a container	Yes
`expose`	Expose a resource as a service	Yes
`import`	Import container images to the cluster	Yes
`install`	Install Helm charts	Yes
`push`	Package and push an OCI artifact to a registry	Yes
`reconcile`	Trigger reconciliation for GitOps workloads	Yes
`rollout`	Manage the rollout of a resource	Yes
`rollout_history`	View rollout history	Yes
`rollout_pause`	Mark the provided resource as paused	Yes
`rollout_restart`	Restart a resource	Yes
`rollout_resume`	Resume a paused resource	Yes
`rollout_status`	Show the status of the rollout	Yes
`rollout_undo`	Undo a previous rollout	Yes
`scale`	Scale resources	Yes
`watch`	Watch for file changes and auto-apply workloads	No

MCP clients can discover available tools dynamically and toggle them on/off as needed. Each tool includes its name, a description, and a JSON schema with the subcommand selector enum and merged flags.

Tool Annotations

All tools carry MCP behavioral annotations that allow clients to make smarter decisions:

Annotation	Read tools (`*_read`)	Write tools (`*_write`)
`readOnlyHint`	`true` — no cluster or infrastructure mutations	`false`
`destructiveHint`	`false`	`true` — clients should warn before running
`idempotentHint`	`true`	`false`
`openWorldHint`	`true` — may interact with external systems such as clusters or registries	`true` — may affect external systems

Clients that support MCP annotations (such as Claude Desktop) use these hints to distinguish read-only operations from destructive or non-idempotent actions, while recognizing that both read and write tools may interact with external systems.

Tool Responses

All MCP tools return a structured JSON envelope, making responses easy to parse programmatically:

Success:

{
  "status": "success",
  "command": "ksail cluster info",
  "output": "..."
}

Error:

{
  "status": "error",
  "command": "ksail cluster info",
  "error": "docker is not running",
  "output": "..."
}

Field	Present when	Description
`status`	Always	`"success"` or `"error"`
`command`	Always	Full command path (e.g. `"ksail cluster info"`)
`output`	Optional	Captured stdout/stderr from the command
`error`	Error only	Human-readable error message

Integration Examples

For step-by-step setup instructions for each AI client — including PATH configuration, example prompts, and a tool reference — see Using KSail with AI Assistants.

Many MCP clients, including Claude Desktop, Cursor, and Windsurf, use the following mcpServers configuration pattern:

{
  "mcpServers": {
    "ksail": {
      "command": "ksail",
      "args": ["open", "mcp"]
    }
  }
}

The KSail VSCode extension handles MCP registration automatically — no manual configuration needed.

Custom MCP Client

If you’re building your own MCP client:

import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async with stdio_client(StdioServerParameters(command="ksail", args=["open", "mcp"])) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        print([t.name for t in tools.tools])
        result = await session.call_tool("cluster_read", arguments={"command": "info"})
        response = json.loads(result.content[0].text)
        if response["status"] == "success":
            print(response.get("output", ""))
        else:
            print(f"Error: {response['error']}")

See Tool Responses for the full JSON envelope format.

Configuration

The server uses stdio for communication, runs commands in the current working directory (set by the client), keeps the connection alive for 30 seconds after the last request, and returns results in pages of 100 items for large lists.

Security Note: Only run the MCP server with trusted MCP clients; any connected client can invoke KSail tools that execute commands with the full permissions of the user running ksail open mcp, so a compromised or misconfigured client could perform arbitrary cluster or filesystem operations on your behalf.

Troubleshooting

Server won’t start

Ensure KSail is installed and in your PATH:

which ksail
# Should return the path to ksail binary

Tools not appearing in MCP client

Check the client configuration syntax (JSON formatting)
Restart the MCP client after changing configuration
Check client logs for connection errors

Commands fail with “Docker not running”

Cluster operations require Docker:

docker ps
# Should list running containers without errors

Tool execution timeout

Some operations (cluster creation, workload deployment) can take several minutes. Ensure your MCP client has appropriate timeout settings.

Working directory issues

The server executes commands relative to the working directory set by the MCP client. For Claude Desktop and other clients that don’t set a working directory, ensure:

You’re in a directory with a ksail.yaml file when using cluster commands
Or use absolute paths in tool arguments

The VSCode extension automatically sets the working directory to the workspace root.

Advanced Usage

Combining with AI Chat

The MCP server is complementary to the AI Chat feature:

Use ksail open chat for interactive, conversational workflows with a rich TUI
Use ksail open mcp to expose KSail to external AI assistants like Claude Desktop

You can use both simultaneously — the chat command is excluded from MCP tools to avoid conflicts.

Automation Scripts

Use MCP tool calls in automation frameworks to orchestrate sequences of KSail operations — for example, cluster_write (init → create) → workload_write (apply, then cipher_encrypt). Use the same connection pattern shown in Custom MCP Client.