# MCP Server for Kubernetes Troubleshooting Scenarios: Available Prompts and Implementation Guide

> Troubleshoot Kubernetes issues with the MCP server. Learn about the k8s-diagnose prompt for efficient pod and node diagnostics across namespaces.

- Repository: [Suyog Sonwalkar/mcp-server-kubernetes](https://github.com/flux159/mcp-server-kubernetes)
- Tags: how-to-guide
- Published: 2026-03-02

---

**The MCP server for Kubernetes troubleshooting scenarios provides a single built-in `k8s-diagnose` prompt that enables systematic diagnostics of pods and nodes through keyword-based search across all namespaces or specific ones.**

The `flux159/mcp-server-kubernetes` repository implements a Model Context Protocol (MCP) server that exposes specialized prompts for Kubernetes troubleshooting scenarios. These prompts guide AI assistants and operators through structured diagnostic workflows by leveraging the server's read-only inspection capabilities.

## Available Prompts in the MCP Server for Kubernetes

The server currently exposes one dedicated troubleshooting prompt designed for comprehensive Kubernetes diagnostics.

### The k8s-diagnose Prompt

The **`k8s-diagnose`** prompt is the primary interface for Kubernetes troubleshooting scenarios within the MCP server. Registered in [`src/prompts/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/prompts/index.ts), this prompt accepts structured arguments to target specific resources and returns a detailed diagnostic workflow.

**Prompt Arguments:**

- **`keyword`** (required): A search term used to filter pod or node names. The server uses this to identify target resources for diagnosis.
- **`namespace`** (optional): Specifies the Kubernetes namespace to search. Defaults to `"all"`, enabling cluster-wide diagnostics across every namespace.

**Prompt Description:** "Diagnose Kubernetes Resources."

When invoked via a `GetPromptRequest`, the server constructs a comprehensive diagnostic plan that includes health checks, state assessment, log analysis, and dependency mapping. This workflow guides the AI assistant or human operator through systematic troubleshooting of the identified resources.

### Prompt Registration Architecture

The prompt system is initialized through the **`registerPromptHandlers`** function in [`src/prompts/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/prompts/index.ts). During server startup, this function registers two critical request handlers with the MCP server:

1. **ListPromptsRequest**: Handles `prompts/list` method calls, returning the available prompt definitions including `k8s-diagnose` with its argument schema.
2. **GetPromptRequest**: Handles `prompts/get` method calls, generating the diagnostic workflow content when clients request the `k8s-diagnose` prompt with specific arguments.

## How to Use the Kubernetes Troubleshooting Prompt

### Listing Available Prompts

To discover the available prompts for Kubernetes troubleshooting scenarios, clients can invoke the list method:

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { ListPromptsResultSchema } from "@modelcontextprotocol/sdk/types.js";

const transport = new StdioClientTransport({
  command: "bun",
  args: ["src/index.ts"],
});

const client = new Client(
  { name: "my-client", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);

const prompts = await client.request(
  { method: "prompts/list" },
  ListPromptsResultSchema
);

console.log(prompts.prompts);

```

**Expected Output:**

```json
[
  {
    "name": "k8s-diagnose",
    "description": "Diagnose Kubernetes Resources.",
    "arguments": [
      { "name": "keyword", "description": "A keyword to search pod/node names.", "required": true },
      { "name": "namespace", "description": "Optional: Specify a namespace to narrow down the search.", "required": false }
    ]
  }
]

```

### Invoking the k8s-diagnose Prompt

To execute Kubernetes troubleshooting scenarios against specific resources, use the get prompt method with the required arguments:

```typescript
import { GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const response = await client.request(
  {
    method: "prompts/get",
    params: {
      name: "k8s-diagnose",
      arguments: { keyword: "frontend", namespace: "production" }
    }
  },
  {} as any
);

console.log(response.messages[0].content.text);

```

The returned text contains a structured diagnostic workflow that guides the AI through health checks, log analysis, and dependency verification for the matched pods or nodes.

## Implementation Details and Source Code

### Key Source Files

The Kubernetes troubleshooting prompt system is implemented across the following critical files:

| File | Role |
|------|------|
| **[[`src/prompts/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/prompts/index.ts)](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/prompts/index.ts)** | Registers the `k8s-diagnose` prompt and implements the `ListPromptsRequest` and `GetPromptRequest` handlers. |
| **[[`tests/prompts.test.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/tests/prompts.test.ts)](https://github.com/flux159/mcp-server-kubernetes/blob/main/tests/prompts.test.ts)** | Unit tests verifying prompt availability and schema validation. |
| **[[`src/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/index.ts)](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/index.ts)** | Server bootstrap that invokes `registerPromptHandlers` with the `Server` instance and `KubernetesManager`. |
| **[[`src/utils/kubernetes-manager.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts)](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts)** | Provides the underlying Kubernetes cluster connection used for resource inspection during diagnostic workflows. |

### Safety and Operational Modes

The `k8s-diagnose` prompt is designed as a **read-only** diagnostic tool. Because the server filters destructive tools based on environment variables, this prompt remains safe to use in both destructive and non-destructive operational modes. It performs only inspection and guidance operations without modifying cluster state.

## Summary

- The **MCP server for Kubernetes troubleshooting scenarios** exposes a single built-in prompt: **`k8s-diagnose`**.
- Located in [`src/prompts/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/prompts/index.ts), the prompt accepts a required `keyword` argument and an optional `namespace` argument defaulting to `"all"`.
- The prompt returns a structured diagnostic workflow guiding AI assistants through health checks, log analysis, and dependency mapping.
- Implementation relies on `registerPromptHandlers` to manage `ListPromptsRequest` and `GetPromptRequest` protocols.
- The prompt is read-only and safe for production use regardless of the server's destructive tool configuration.

## Frequently Asked Questions

### What is the primary troubleshooting prompt available in the MCP server for Kubernetes?

The primary prompt is **`k8s-diagnose`**, registered in [`src/prompts/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/prompts/index.ts). It is the sole built-in prompt designed specifically for Kubernetes troubleshooting scenarios, providing a structured diagnostic workflow for analyzing pod and node health.

### How do I specify a namespace when using the k8s-diagnose prompt?

You can provide the **`namespace`** argument when invoking the prompt via `GetPromptRequest`. If omitted, it defaults to `"all"`, which searches across every namespace in the cluster. To target a specific namespace, pass the namespace name as a string value.

### Is the k8s-diagnose prompt safe to use in production environments?

Yes. The `k8s-diagnose` prompt performs only **read-only** inspection and guidance operations. Because the server filters destructive tools based on environment variables, this prompt remains safe regardless of whether the server is running in destructive or non-destructive mode.

### Where is the prompt logic implemented in the source code?

The prompt logic is implemented in **[`src/prompts/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/prompts/index.ts)**, where the `registerPromptHandlers` function sets up the `ListPromptsRequest` and `GetPromptRequest` handlers. The prompt is initialized in **[`src/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/index.ts)** during server startup, and underlying Kubernetes connectivity is provided by **[`src/utils/kubernetes-manager.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts)**.