MCP Server

The KubeSense MCP (Model Context Protocol) Server enables AI assistants like Claude, ChatGPT, and other MCP-compatible clients to query and analyze your Kubernetes telemetry data — logs, traces, and metrics — using natural language.

Overview

The MCP server acts as a bridge between AI clients and the KubeSense platform. It exposes a set of read-only tools over the MCP protocol that allow AI assistants to discover available telemetry fields, search raw data, and run aggregated analyses across your entire observability stack.

Key capabilities:

• Search and filter logs and traces using SQL-like syntax
• Run aggregated analyses with grouping, percentiles, and time-series breakdowns
• Execute PromQL queries against your metrics
• Combine multiple datasources (logs, traces, metrics) in a single query with formula support
• Discover available fields, metrics, and labels dynamically

Authentication

The MCP server uses Bearer token authentication with KubeSense API keys.

1. The AI client sends an initialize request with an Authorization: Bearer <api-key> header
2. The server validates the API key against the KubeSense platform
3. A session is created and all subsequent requests use the mcp-session-id header
4. Sessions are automatically cleaned up when the client disconnects

API keys are stored only in-memory and never written to disk or logs.

Generating an API Key

To connect an AI client to the MCP server, you need a KubeSense API key. Navigate to Settings > API Key Management and click Generate API Key.

Copy the generated key and use it as the Bearer token when configuring your AI client.

Available Tools

Discovery Tools

These tools help the AI client understand what data is available before querying.

get-trace-or-log-fields

Lists available columns and fields for traces or logs within a time range. Includes both default fields and custom attributes.

Parameters:

get-available-metrics

Searches for available metric names. Supports keyword filtering to narrow results.

Parameters:

get-metric-labels

Fetches available labels for a specific metric, useful for building PromQL queries.

Parameters:

Search Tools

Search tools return raw records (up to 10 rows) and support SQL-like WHERE clause filters.

search-logs

Browse raw log records with filtering and field selection.

Parameters:

Default log fields: workload, namespace, cluster, pod_name, container_name, node_name, level, format, body_length

search-traces

Browse raw trace/span records with filtering and field selection.

Parameters:

Default trace fields: pod_name, namespace, cluster, workload, container_name, node_name, role, status, protocol_type, operation_name, duration, return_code

Analysis Tools

Analysis tools run aggregated queries and return summarized results. They support both range (time-series) and instant (single point-in-time) query types.

analyze-logs

Run aggregated analysis over logs with support for counting, averaging, summing, percentiles, and grouping.

Parameters:

analyze-traces

Run aggregated analysis over traces, useful for latency statistics and error rate breakdowns.

Parameters:

analyze-metrics

Execute PromQL queries with summary statistics (min, max, avg, latest, total).

Parameters:

analyze-telemetry

The most powerful tool — combines multiple datasources (logs, traces, metrics) in a single query with formula support.

Parameters:

Each query in the queries map can be a logs, traces, metrics, or formula datasource. Formulas reference other queries by label, e.g., (A/B)*100.

Filter Syntax

Log and trace tools support SQL-like WHERE clause filters:

namespace = "default" AND level = ERROR
protocol_type = HTTP OR status = error
pod_name IN ("service-a", "service-b")
duration > 1000
message LIKE "%timeout%"

Supported operators: =, !=, >, >=, <, <=, IN, NOT IN, LIKE, NOT LIKE

Custom attributes: Prefix with @ for custom fields — @custom_field = value

Connecting AI Clients

Claude Desktop

Add the following to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "kubesense": {
      "url": "https://<kubesense-host>/mcp",
      "headers": {
        "Authorization": "Bearer <your-kubesense-api-key>"
      }
    }
  }
}

Claude Code

Add the MCP server to your Claude Code configuration:

claude mcp add --transport http kubesense-mcp "https://<kubesense-host>/mcp" --header "Authorization: Bearer <token>" --scope user

See MCP installation scopes for more on the --scope option.

Cursor

Add the MCP server in Cursor via Settings > Tools & Integrations > MCP Tools > Add new global MCP server, or add it directly to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kubesense-mcp": {
      "url": "https://<kubesense-host>/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can connect to the server's HTTP endpoint at /mcp. The server uses MCP's Streamable HTTP transport. Send an Authorization: Bearer <api-key> header with the initialize request.

Example Queries

Once connected, you can ask your AI assistant natural language questions like:

• "Show me all error logs from the payments namespace in the last hour"
• "What's the p99 latency for the checkout service over the past 24 hours?"
• "Compare error rates between the canary and stable deployments"
• "Find traces where duration is over 5 seconds and group by service"
• "Show me the ratio of 5xx errors to total requests as a percentage"

MCP Skills

KubeSense provides a set of pre-built MCP skills that extend your AI assistant with ready-to-use Kubernetes troubleshooting and analysis workflows. These skills act as prompt templates that guide the AI through common operational tasks using the MCP tools described above.

Explore the available skills and installation instructions in the kubesense-mcp-skills repository.