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

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, 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. 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:

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:

[
  {
    "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:

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)	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)	Unit tests verifying prompt availability and schema validation.
[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)	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, 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. 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, where the registerPromptHandlers function sets up the ListPromptsRequest and GetPromptRequest handlers. The prompt is initialized in src/index.ts during server startup, and underlying Kubernetes connectivity is provided by src/utils/kubernetes-manager.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}