Enable KubeLedger MCP Server for AI Assistant

A step-by-step guide to enable KubeLedger MCP Server and sample integration with Claude and other MCP-compliant AI clients.

MCP Integration (AI Assistant)

KubeLedger ships with an optional MCP (Model Context Protocol) server that gives MCP-aware AI tools direct access to the underlying analytics data — the consolidated CPU, memory and GPU usage that the web UI is built on. MCP is an open standard adopted by a growing ecosystem: Anthropic’s Claude Desktop and Claude Code, Google’s Gemini CLI, IDE assistants such as Cursor, Windsurf and Cline, the MCP Inspector developer tool, and others.

Where the UI renders a fixed set of dashboards, the MCP exposes ten read-only tools that let an AI assistant combine, filter and aggregate this data into custom rankings, namespace groupings, efficiency assessments, trend comparisons and narrative insights — analyses the UI does not predefine.

The server itself is descriptive only: it never reaches the Kubernetes API or RRD databases, embeds no LLM, and makes no recommendations. It exposes the data; the client provides the reasoning.

Ten tools are available:

Each response carries a metadata block with cost_model, unit, data window, source file and warnings. See kubeledger-mcp-spec.md for the full specification.

1. Enable the MCP container at deploy time

The MCP container is opt-in — disabled by default. Enable it via the Helm chart:

helm upgrade --install kubeledger ./manifests/kubeledger/helm \
  -n kubeledger \
  --set mcp.enabled=true

Enabling adds a second container mcp to the pod (same image, command python3 -u ./mcp_server.py), mounts the static/data/ volume read-only, and adds a named port mcp (default 5484) on the existing Service.

NetworkPolicy. MCP v1 has no authentication at the tool layer — access control relies entirely on Kubernetes NetworkPolicy. The chart ships a default-deny policy covering both the dashboard and the MCP ports. Declare authorized sources via networkPolicy.allowedSources (dashboard) and networkPolicy.mcpAllowedSources (MCP); see the documented options and examples in manifests/kubeledger/helm/values.yaml. To disable the policy entirely and rely on cluster-level controls instead, set networkPolicy.enabled=false.

2. Reach the MCP service from your workstation

The Service is ClusterIP in v1 — external exposure (Route/Ingress) is out of scope. Use kubectl port-forward to reach it from your laptop:

kubectl port-forward svc/kubeledger 5484:5484 -n kubeledger

Smoke test in another shell:

curl -X POST http://localhost:5484/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Expected response: HTTP 200 with a JSON-RPC envelope listing the negotiated protocolVersion and server capabilities.

3. Connect your MCP client

Every MCP-aware client can be pointed at http://localhost:5484/mcp (Streamable HTTP transport). Only the configuration file differs. Two common configurations are detailed below; for other clients, consult their respective MCP integration docs and use the same URL.

Claude Code (native HTTP)

Create a .mcp.json at the root of the project where you’ll work, or register globally via claude mcp add:

{
  "mcpServers": {
    "kubeledger": {
      "type": "http",
      "url": "http://localhost:5484/mcp"
    }
  }
}

Restart Claude Code; the kubeledger server appears connected with the 10 tools.

Claude Desktop (via mcp-remote bridge)

Claude Desktop currently spawns MCP servers as local subprocesses (stdio only). Use the mcp-remote bridge to relay stdio to HTTP. Edit claude_desktop_config.json (at %APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "kubeledger": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://localhost:5484/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

Prerequisite: a working node + npx on the system PATH. After editing, fully quit Claude Desktop (system tray → Quit, not just close the window) and relaunch.

Other MCP clients

Most clients accept the same http://localhost:5484/mcp endpoint with their own configuration syntax. Examples:

• Gemini CLI — declare the server in ~/.gemini/settings.json under mcpServers (Google’s MCP integration docs).
• Cursor / Windsurf / Cline — add the server in the IDE’s MCP settings, type streamable-http, URL http://localhost:5484/mcp.
• MCP Inspector — npx @modelcontextprotocol/inspector, then connect to http://localhost:5484/mcp with transport Streamable HTTP.

Clients that only speak stdio can use the mcp-remote bridge, same pattern as the Claude Desktop example above.

Example questions to ask the AI

The assistant picks the right tool automatically — ask in plain language:

• “Which ten namespaces consume the most CPU over the past 14 days, excluding system namespaces?”
• “Compare the monthly CPU trajectory of openshift-monitoring against kube-system.”
• “Identify CPU over-provisioned namespaces — those with a usage / requests ratio below 0.5.”
• “Show the hourly memory series for the kube-system namespace over the last 7 days, with min/max/mean.”
• “What proportion of cluster CPU is consumed by openshift-* namespaces today?”

Troubleshooting