Skip to main content

MCP Support in Headlamp

Headlamp MCP support makes Kubernetes easier to understand by bringing specialized expertise directly into the UI. MCPs surface insights next to workloads and applications instead of in separate tools or terminals. Teams gain clarity without losing context. By keeping expertise close to the resources it explains, MCP support helps teams troubleshoot faster and make better decisions in their day-to-day Kubernetes work.

What Is MCP​

The Model Context Protocol, or MCP, is an open standard that defines how an AI system connects to external tools and data through a consistent interface.

MCP uses a client-server model. An AI application acts as the host and connects to one or more MCP servers. Each server exposes capabilities that the host can discover and use.

MCP servers can provide tools that perform actions, resources that supply data, and prompts that guide interactions. The host can list available capabilities and call them using structured inputs. Results are returned in a structured form.

Why Use MCPs in Headlamp​

Kubernetes teams often switch between dashboards, terminals, and scripts to understand what is happening. Each switch breaks focus and slows action.

With MCPs in Headlamp, expertise shows up where Kubernetes work already happens. Insight appears alongside pods, namespaces, and applications. Results stay tied to the resources on screen instead of being shown somewhere else.

This reduces context switching and makes investigations faster. It also makes answers easier to trust, since the insight is grounded in the same Kubernetes context you are viewing.

Requirements​

  • Headlamp Desktop — MCP server support is currently available only in the Headlamp desktop application.
  • The AI Assistant plugin enabled and at least one AI provider configured.
  • Access to an MCP server that can run locally.

Setting Up MCP Support​

Enable MCP Servers​

  1. Open Settings in Headlamp.
  2. Go to AI Assistant.
  3. Find the MCP Servers section.
  4. Turn MCP servers on.

Configuring MCP Servers​

When adding a server you provide a name, a command, optional arguments, and any required environment variables. After you save, Headlamp starts the server and discovers the tools it provides.

Navigate to the AI Assistant settings to add and manage MCP servers. Each server is configured with:

  • Name — A unique identifier for the server.
  • Command — The executable to run (e.g., flux-operator-mcp).
  • Args — Command-line arguments (e.g., serve --kube-context HEADLAMP_CURRENT_CLUSTER).
  • Environment Variables — Optional env vars required by the server (e.g., KUBECONFIG).

Note: HEADLAMP_CURRENT_CLUSTER is a Headlamp-specific placeholder, not a shell environment variable. When starting an MCP server, Headlamp replaces this placeholder with the name of the currently selected cluster before running the command, so you should only reference it in the Args field where command-line arguments are defined.

You can configure servers using the form-based UI or by editing the JSON configuration directly.

enable MCP Servers add MCP server MCP configuration

Example MCP Servers​

Each of the servers below runs as a local command, which is what the desktop app expects. Install the tool first, then add it from the AI Assistant settings using the fields above.

Flux Operator MCP surfaces Flux sources, Kustomizations, and HelmReleases.

  • Name — flux
  • Command — flux-operator-mcp
  • Args — serve --kube-context HEADLAMP_CURRENT_CLUSTER

As noted above, HEADLAMP_CURRENT_CLUSTER is not something you set yourself. Headlamp replaces it with the name of the selected cluster when it starts the server.

K8sGPT analyzes cluster issues and returns AI-assisted explanations. The serve --mcp command runs its MCP server over stdio, which needs no environment variables or extra configuration.

  • Name — k8sgpt
  • Command — k8sgpt
  • Args — serve --mcp

Inspektor Gadget exposes eBPF gadgets for tracing DNS, TCP connections, process execution, and more. It needs either a gadget discoverer or an explicit list of gadgets, otherwise it will not start.

  • Name — inspektor-gadget
  • Command — ig-mcp-server
  • Args — -gadget-discoverer=artifacthub
  • Example (pin specific gadgets) — -gadget-images=trace_dns:latest,trace_tcp:latest loads only the listed gadgets instead of discovering all of them

Each project keeps its own install steps and flags up to date, so check its page for the latest options.

Managing MCP Tools​

Once a server is connected, Headlamp lists the tools it exposes.

  • Enable or disable individual tools per server.
  • View tool descriptions and input schemas.
  • Track tool usage statistics.
  • Use bulk operations to enable or disable all tools at once.

This keeps interactions predictable and helps teams use MCPs with confidence.

Using MCPs in Chat​

After setup, MCPs are used through normal chat prompts.

For example:

  1. What is happening with this deployment?
  2. Why is this workload out of sync?
  3. Show all Flux resources in this namespace.

The assistant selects the right tool and presents results next to the Kubernetes resources you are already viewing.

Limitations​

  • MCP server support is currently available only in Headlamp Desktop.
  • MCP servers must be available as local commands, since the desktop app runs them as local processes.
  • Available tools depend on the servers you connect.

Get Started​

MCP support brings expert knowledge directly into the Kubernetes UI. Insight stays close to workloads and applications so teams can understand issues faster and act without switching tools.

Open Headlamp Desktop, enable MCP support, connect a server, and start using expertise where Kubernetes work already happens.