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 7 tools:

Tool	Access	Description	Subcommand parameter
cluster_read	Read-only	Manage cluster lifecycle	command
cluster_write	Write	Manage cluster lifecycle	command
project_read	Read-only	Manage GitOps project files	command
project_write	Write	Manage GitOps project files	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, steer-agent.

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
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

project_read

Manage GitOps project files — read-only subcommands of ksail project. Select the operation via the command parameter.

Subcommand	Description	Accepts args
env_list	List the cluster environments declared in the workspace	No

project_write

Manage GitOps project files — write subcommands of ksail project. Select the operation via the command parameter.

Subcommand	Description	Accepts args
env_add	Clone an existing cluster environment into a new one	Yes
init	Initialize a new project	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
network	Inspect live network traffic flows via Cilium Hubble	No
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
intercept	Intercept a Deployment’s inbound traffic to a local process (reverse dev bridge)	Yes
mirror	Mirror a Deployment’s inbound traffic locally (read-only pcap capture)	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

Note

readOnlyHint: true means the tool performs no cluster or infrastructure mutations. However, some *_read subcommands may still produce local side effects — for example, cluster_read switch updates the kubeconfig current-context, and workload_read export writes a tar archive to disk. Review the subcommand behavior before relying on this hint for auto-approval.

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

1. Check the client configuration syntax (JSON formatting)
2. Restart the MCP client after changing configuration
3. 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.