Using KSail with Claude, Cursor, and Windsurf

KSail’s MCP (Model Context Protocol) server exposes all cluster and workload commands as structured tools that AI assistants can invoke. This guide shows how to connect Claude Desktop, Cursor, and Windsurf to KSail so you can manage Kubernetes clusters using natural language.

Note

For a full reference of the MCP server’s available tools, configuration options, and troubleshooting, see the MCP Server reference page.

Prerequisites

• KSail installed and available in PATH
• Docker running (required for local cluster operations)
• An MCP-compatible AI client (see setup steps below)

Verify KSail is reachable from your shell:

ksail mcp --help

Client Setup

Claude Desktop

Add KSail to your Claude Desktop MCP server configuration.

Configuration file location:

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Edit (or create) the config file and add the ksail entry to mcpServers:

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

After saving, restart Claude Desktop. The KSail tools will appear in Claude’s tool picker.

Note

On macOS, Claude Desktop may not inherit your shell’s PATH. If KSail is installed via brew or a custom path, use the full binary path (e.g., /usr/local/bin/ksail or /opt/homebrew/bin/ksail). Run which ksail to find it.

{
  "mcpServers": {
    "ksail": {
      "command": "/opt/homebrew/bin/ksail",
      "args": ["mcp"]
    }
  }
}

Cursor

Add KSail to Cursor’s MCP configuration. Cursor supports both project-level and global MCP servers.

Project-level (shared with team, checked into version control):

Create or edit .cursor/mcp.json in your project root:

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

Global (available in all Cursor projects):

Edit ~/.cursor/mcp.json:

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

After saving, restart Cursor or reload the MCP configuration from the Cursor settings panel (Cursor Settings → MCP). The KSail tools will be listed as available servers.

Note

Cursor executes MCP servers from the workspace root directory, so KSail will find ksail.yaml automatically if it exists at the project root.

Windsurf

Add KSail to Windsurf’s MCP configuration.

Open Windsurf Settings (Cmd+, on macOS / Ctrl+, on Windows/Linux) and navigate to MCP → Add MCP Server, or edit your Windsurf MCP config file directly:

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

After saving, restart the Cascade AI session or reload MCP servers from the Windsurf settings. The KSail tools will be listed as available.

Note

If KSail is not on Windsurf’s PATH, provide the full binary path. Run which ksail to find it.

VS Code (Copilot)

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

1. Install the KSail extension from the VS Code Marketplace.
2. Open a workspace with a ksail.yaml file (or run KSail: Init Cluster from the Command Palette to create one).
3. Switch GitHub Copilot to agent mode — Copilot can now invoke KSail commands directly.

For manual configuration or if you prefer not to use the extension, add KSail to VS Code’s settings.json:

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

Example Prompts

Once connected, you can manage Kubernetes clusters with natural language. Here are some prompts to get started:

Cluster management

Prompt	Tool invoked
”Create a Vanilla Kubernetes cluster with Flux and Cilium”	cluster_write (init → create)
“List all my KSail clusters”	cluster_read (list)
“Show me the status of the dev cluster”	cluster_read (info)
“Update the staging cluster to match the latest config”	cluster_write (update)
“Delete the dev cluster”	cluster_write (delete)

Workload operations

Prompt	Tool invoked
”Get all pods in the default namespace”	workload_read (get)
“Show logs for the api-server pod”	workload_read (logs)
“Apply all manifests in the k8s/ directory”	workload_write (apply)
“Validate my Kubernetes manifests”	workload_read (validate)
“Scale the api deployment to 3 replicas”	workload_write (scale)
“Generate a Deployment manifest for my-app”	workload_read (gen_deployment)

Secret management

Prompt	Tool invoked
”Encrypt the secrets.yaml file with SOPS”	cipher_write (encrypt)
“Import my SOPS age key from the key file”	cipher_write (import)

Tips

• Available tools: KSail exposes 5 MCP tools grouped by permission level. For the complete tool catalog with subcommands and flags, see the MCP Server reference.
• Multiple environments: Combine with the --config flag in your prompts — for example, “Apply manifests using the staging config” will work if you reference the config file path in your prompt and KSail finds it.
• Cluster creation takes time: Inform your AI assistant that cluster creation can take 2–5 minutes. Most MCP clients have configurable tool timeouts.
• Security: The MCP server runs with the full permissions of the ksail process. Only connect trusted AI clients. See the MCP Server security note for details.