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.

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 designed to be invoked by MCP clients:

ksail mcp

The server will:

1. Start and listen for MCP requests on stdin
2. Expose all KSail commands as MCP tools
3. Run until the client disconnects or the process is terminated

Note: The server is designed to be started by MCP clients, not run directly by users. See Integration Examples for typical usage patterns.

Available Tools

The MCP server automatically generates tools from all KSail commands except:

• ksail chat — Interactive chat (use MCP client’s native chat instead)
• ksail mcp — The MCP server itself
• ksail completion — Shell completion (not relevant for MCP)
• ksail help — Built-in help (use MCP tool discovery)

Commands are consolidated by permission into 6 tools:

Tool	Description	Subcommand Parameter
cluster_read	Read-only cluster operations	command
cluster_write	Cluster lifecycle mutations	command
workload_read	Read-only workload operations	workload_command
workload_write	Workload mutations	workload_command
cipher_read	Read-only secret operations	cipher_operation
cipher_write	Secret mutations	cipher_operation

Each tool accepts a subcommand parameter (e.g., command, workload_command, cipher_operation) that selects the specific operation. Flags that apply only to certain subcommands are annotated in their descriptions.

Cluster Operations (cluster_read / cluster_write)

Read operations (cluster_read with command):

• info — Display cluster information
• list — List clusters
• connect — Connect to cluster with k9s
• switch — Switch active cluster context (pass cluster name via args; note: mutates local kubeconfig by updating current-context)

Write operations (cluster_write with command):

• init — Initialize a new project
• create — Create a cluster
• update — Update a cluster configuration (returns diff output showing before/after changes)
• delete — Destroy a cluster
• start — Start a stopped cluster
• stop — Stop a running cluster
• backup — Backup cluster resources
• restore — Restore cluster resources from backup

Workload Operations (workload_read / workload_write)

Read operations (workload_read with workload_command):

• get — Get resources
• describe — Describe resources
• logs — Print container logs
• explain — Get documentation for a resource
• wait — Wait for a condition on resources (pass target resource(s) via args, e.g., ["pod/foo"])
• images — List container images required by cluster components
• export — Export container images to a tar archive (pass optional output path via args)
• validate — Validate Kubernetes manifests (pass optional path via args)
• gen_deployment, gen_service_clusterip, gen_namespace, etc. — Generate resource manifests
• gen_helmrelease — Generate a HelmRelease resource (pass release name via args)

Write operations (workload_write with workload_command):

• apply — Apply manifests
• create — Create resources
• delete — Delete resources
• edit — Edit a resource
• exec — Execute a command in a container (pass pod and command via args, e.g., ["pod/foo", "--", "sh"])
• expose — Expose a resource as a service (pass resource type and name via args, e.g., ["deployment", "my-app"])
• scale — Scale resources
• reconcile — Trigger reconciliation for GitOps workloads
• push — Package and push an OCI artifact (pass optional OCI URI via args)
• install — Install Helm charts (pass release name and chart via args, e.g., ["my-release", "stable/nginx"])
• import — Import container images to the cluster (pass optional tar archive path via args)
• watch — Watch for file changes and auto-apply
• rollout_restart, rollout_status, etc. — Manage rollouts

Secret Management (cipher_read / cipher_write)

Read operations (cipher_read with cipher_operation):

• decrypt — Decrypt a SOPS-encrypted file (pass file path via args)

Write operations (cipher_write with cipher_operation):

• encrypt — Encrypt a file with SOPS (pass file path via args)
• edit — Edit an encrypted file in-place (pass file path via args)
• import — Import an age key (pass the age private key via args)

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

Integration Examples

Claude Desktop

Add KSail to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

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

After restarting Claude Desktop, the KSail tools will be available. Try:

“Create a Vanilla Kubernetes cluster with Cilium CNI”

Claude will use the cluster_write tool (with command: "init" and command: "create") to fulfill your request.

VSCode Extension

The KSail VSCode extension automatically registers the MCP server with VSCode’s native MCP infrastructure.

No manual configuration needed — the extension handles server registration, process lifecycle, and working directory setup.

Once installed:

1. Open a workspace containing a ksail.yaml file (or run KSail: Init Cluster to create one)
2. Use GitHub Copilot in agent mode
3. Copilot can now execute KSail commands directly

Example workflow:

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run Copilot: Chat
3. In agent mode, ask: “Create a K3s cluster and deploy my manifests from ./k8s”
4. Copilot uses the KSail MCP tools to execute the commands

Custom MCP Client

If you’re building your own MCP client:

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

async with stdio_client(StdioServerParameters(command="ksail", args=["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"})
        print(result.content)

Note: Tools are consolidated into read/write pairs (e.g., cluster_read, cluster_write). Use the subcommand parameter to select the specific operation. Check the MCP SDK documentation for your language.

Configuration

The server uses stdio for communication (compatible with all MCP clients), 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. Tools execute with the same permissions as the user running the server.

Security Note: The MCP server executes commands with your full permissions. Only run it with trusted MCP clients.

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 chat for interactive, conversational workflows with a rich TUI
• Use ksail 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) → cipher_write (encrypt). Use the same connection pattern shown in Custom MCP Client.

See Also

• AI Chat — Interactive chat powered by GitHub Copilot
• CLI Flags Reference — MCP command flags
• VSCode Extension — VSCode integration with automatic MCP setup
• Model Context Protocol — Official MCP specification