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 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 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 5 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_write	Secret mutations (encrypt, decrypt, edit, import)	cipher_operation

Each tool accepts a subcommand parameter that selects the specific operation. The table below shows available subcommands for each tool. Pass additional arguments via args where indicated.

Cluster Operations

Tool	Subcommands
cluster_read	info, list, connect, switch (pass cluster name via args; mutates local kubeconfig current-context)
cluster_write	init, create, update (returns diff output), delete, start, stop, backup, restore

Workload Operations

Tool	Subcommands
workload_read	get, describe, logs, explain, wait (pass target resource(s) via args), images, export (pass optional output path via args), validate (pass optional path via args), gen_deployment, gen_service_clusterip, gen_namespace, gen_helmrelease (pass release name via args), and other gen_* commands
workload_write	apply, create, delete, edit, exec (pass pod and command via args, e.g., ["pod/foo", "--", "sh"]), expose (pass resource type and name via args), scale, reconcile, push, install (pass release name and chart via args), import, watch, rollout_restart, rollout_status, and other rollout_* commands

Secret Management

Tool	Subcommands
cipher_write	decrypt (pass file path via args), encrypt, edit, import (pass file path or age private key via args)

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 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": ["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=["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 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 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.