It is a Kubernetes MCP server that lets MCP clients inspect and operate Kubernetes clusters safely via configurable access modes and security flags.
Read-only by default: list contexts, namespaces, pods, deployments, services, nodes, and events; get pod details/logs; fetch arbitrary resources by apiVersion/kind/name.
Mutating operations when enabled: scale, restart, and update deployment images; create namespaces; apply manifests.
Admin operations when enabled: delete resources and exec into pods.
Multi-cluster support: target different kube-config contexts, optionally restricted by a context allowlist.
Security controls: namespace allowlists, protected system namespaces, dry-run mode, JSON audit logging, and independent opt-ins for delete, apply, and exec.
Allows MCP clients to inspect and operate Kubernetes clusters, with tools for listing contexts, namespaces, pods, deployments, services, nodes, and events, fetching pod logs, scaling and restarting deployments, setting deployment images, creating namespaces, applying manifests, deleting resources, and executing commands in pods, governed by configurable access modes and security flags.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-kubernetes list pods in the staging context for the web namespace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for Kubernetes. It lets an MCP-capable client (Claude Desktop, Claude Code, etc.) inspect and operate Kubernetes clusters across multiple contexts — with behaviour controlled entirely by flags.
The design goal is safe by default: it starts read-only, can be scoped to an allowlist of namespaces and contexts, protects system namespaces from mutation, and gates the dangerous operations (delete, apply, exec) behind explicit opt-ins.
Multi-cluster — every tool accepts an optional context; scope which contexts are usable with an allowlist.
Access modes — read-only → read-write → admin, layered so a mode never exposes tools above its level.
Security flags — namespace allowlist, protected namespaces, context allowlist, plus independent opt-ins for delete / apply / exec, dry-run, and JSON audit logging (see below).
Standard auth — uses your kube-config (or in-cluster service account). No credentials are stored by the server.
Related MCP server: k8s-mcp-go
Concern | Flag | Default | Effect |
What can the server do at all? |
|
|
|
Which namespaces are in scope? |
| (all) | When set, any operation on a namespace outside the list is refused. |
Which namespaces are read-only forever? |
|
| Can be read but never mutated or deleted, regardless of mode. |
Which clusters are reachable? |
| (all) | When set, only these kube-config contexts may be targeted. |
Can it delete? |
|
|
|
Can it apply manifests? |
|
|
|
Can it exec into pods? |
|
|
|
Preview without touching the cluster |
|
| Write/admin tools validate + log intent, then return without calling the API. |
Audit trail |
|
| Emits a JSON line to stderr per guarded operation ( |
Interactive confirmation | (automatic) | — | Destructive & high-impact actions prompt the human to approve via MCP elicitation before running; clients without elicitation fall back to the |
The layers are independent — e.g. admin mode with all three opt-ins false can restart and scale deployments but can neither delete resources nor exec into pods.
Read (read-only+): list_contexts, list_namespaces, list_pods, get_pod, get_pod_logs, list_deployments, list_services, list_nodes, list_events, get_resource
Write (read-write+): scale_deployment, restart_deployment, set_deployment_image, create_namespace, apply_manifest (needs K8S_ALLOW_APPLY)
Admin (admin): delete_resource (needs K8S_ALLOW_DELETE), exec_in_pod (needs K8S_ALLOW_EXEC)
Published on npm as @dockndevai/mcp-kubernetes. No clone or build needed — your MCP client runs it on demand with npx. Start in read-only mode; see .env.example for every variable and docs/CLIENTS.md for the full per-client guide.
Claude Code (CLI)
claude mcp add kubernetes -e KUBECONFIG_PATH="/Users/you/.kube/config" -e K8S_MODE="read-only" -- npx -y @dockndevai/mcp-kubernetesClaude Desktop · Cursor · Windsurf — same block in claude_desktop_config.json, .cursor/mcp.json, or ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"kubernetes": {
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-kubernetes"
],
"env": {
"KUBECONFIG_PATH": "/Users/you/.kube/config",
"K8S_MODE": "read-only"
}
}
}
}OpenAI Codex CLI — in ~/.codex/config.toml:
[mcp_servers.kubernetes]
command = "npx"
args = ["-y", "@dockndevai/mcp-kubernetes"]
env = { KUBECONFIG_PATH = "/Users/you/.kube/config", K8S_MODE = "read-only" }VS Code (GitHub Copilot, Agent mode) — in .vscode/mcp.json:
{
"servers": {
"kubernetes": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-kubernetes"
],
"env": {
"KUBECONFIG_PATH": "/Users/you/.kube/config",
"K8S_MODE": "read-only"
}
}
}
}Prefer the published package above. To run from a clone:
npm install
npm run build
node dist/index.js # with the environment variables setnpm run dev # watch mode
npm test # unit tests for the security policy
npm run typecheckThis server ships a server.json for the official MCP registry and an mcpName for npm ownership validation. See PUBLISHING.md for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.
MIT
Fetch the full representation of a single pod.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pod name | |
| context | No | kube-config context to target (defaults to current-context) | |
| namespace | Yes | Namespace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat these. The added value is the word 'full', implying comprehensive details, but it doesn't disclose response size, pagination, or error behavior. Given annotations cover safety, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the core action. It is efficient with no wasted words, though it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetch tool with full schema coverage and no output schema, the description is adequate but minimal. It does not mention the response structure, error cases, or how it differs from list/get_resource, leaving some ambiguity given the wide sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: all three parameters have descriptions ('Pod name', 'Namespace', 'kube-config context...'). The description adds no additional semantics beyond what the schema provides, so baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'full representation of a single pod', which is specific. However, it does not differentiate from sibling tools like 'list_pods' or 'get_resource', though the name itself makes the primary purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single pod's details, but does not explicitly state when to use this versus alternatives like 'get_resource' or 'list_pods'. No exclusions or alternatives are mentioned, leaving the agent to infer based on the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch recent logs from a pod container.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pod name | |
| context | No | kube-config context to target (defaults to current-context) | |
| previous | No | Fetch logs from the previous terminated container | |
| container | No | Container name (defaults to first container) | |
| namespace | Yes | Namespace | |
| tailLines | No | Lines from the end (default 200) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only the word 'recent', which is redundant because the schema's tailLines property already documents the default of 200 lines from the end. No additional behavioral context (e.g., default container selection behavior) is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action ('Fetch recent logs') and the resource ('pod container'). Every word earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only log-fetching tool, the description plus the fully annotated schema and safety annotations provide enough to call it correctly. It lacks mention of the plain-text output format or potential log volume, but these are not critical for invocation correctness. A higher score would require the description to handle more operational nuance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the structured data already documents all six parameters. The description's 'recent' loosely maps to tailLines but adds no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch recent logs from a pod container' uses a specific verb and resource, clearly distinguishing this from sibling tools like get_pod (pod metadata) and list_pods (enumeration). An agent can immediately identify what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied by the verb 'Fetch' and the resource 'logs', but the description does not explicitly state when to prefer this tool over alternatives, nor does it mention exclusions. Sibling tools like get_pod exist for other pod details, but no routing guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an arbitrary Kubernetes object by apiVersion/kind/name (e.g. apiVersion=apps/v1, kind=Deployment).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | e.g. Pod, Deployment, Ingress | |
| name | Yes | Resource name | |
| context | No | kube-config context to target (defaults to current-context) | |
| namespace | No | Namespace (omit for cluster-scoped resources) | |
| apiVersion | Yes | e.g. v1, apps/v1, networking.k8s.io/v1 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'Read' adds no new safety information. It does add the targeting method (apiVersion/kind/name) but discloses no additional behavioral traits like return format or error handling. With annotations covering the safety profile, the description contributes only marginal context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff or redundancy. The action, target, and example are presented in order of importance, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has five parameters, all documented in the schema, and the annotations cover the safety profile. The description gives a clear example and sufficient targeting instructions. While it omits explicit return format details, the output schema is absent and 'read' implies returning the object, so the description is adequately complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all five parameters, so the baseline is 3. The description provides a concrete example (apiVersion=apps/v1, kind=Deployment) that clarifies parameter formatting, which is a small value-add beyond the schema, but not enough to raise the score above 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Read'), a specific resource ('an arbitrary Kubernetes object'), and the identifying parameters (apiVersion/kind/name). It explicitly differentiates itself from siblings like get_pod and list_* tools by emphasizing 'arbitrary', making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'arbitrary' implies this tool is for resources not covered by sibling get_pod or list_* tools, but the description does not explicitly state when to use it over alternatives. It provides only implicit guidance and no direct comparison to siblings, leaving the decision to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the contexts (clusters) available in the loaded kube-config.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the useful scoping detail that it reads from the loaded kube-config, but it does not go deeper into behavior such as error cases or connection requirements. This is acceptable for a simple zero-parameter list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence that front-loads the action and resource. It contains no filler or redundancy and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool with safety annotations, the description is nearly complete. It clarifies the resource type and source (kube-config). Some extra context about the exact output format could help, but the absence is not a major gap given the straightforward nature of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (vacuously). The description adds no parameter meaning, but none is needed; per the baseline for zero-parameter tools, this is well handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with the resource 'contexts (clusters)' and clarifies the scope as 'available in the loaded kube-config'. This clearly distinguishes it from sibling list tools like list_namespaces and list_pods, which operate on different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the tool's purpose obvious enough that an agent can infer when to use it (when kube-config contexts are needed), but it provides no explicit guidance on when not to use it or how it compares to alternatives. The sibling names imply different resource types, yet no direct routing instruction is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List deployments in a namespace with replica status.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | kube-config context to target (defaults to current-context) | |
| namespace | Yes | Namespace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'with replica status' as a small output detail, but it does not disclose error behavior, pagination, authentication requirements, or side effects. The additional behavioral context beyond the annotations is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8–10 words that front-loads the core verb and object, and the placement of the scope and output detail are efficient. No words are wasted or redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and simple parameters. The description states what it lists and that replica status is included, but it does not explain the output shape or potential failure cases, like what happens if the namespace does not exist. For a read-only list with full parameter coverage, the description is adequate but leaves some Return detail to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema thoroughly documents both parameters. The description echoes that it lists 'in a namespace', reinforcing the namespace parameter's role, but adds no extra semantics about the context parameter or parameter formats. This meets the baseline for a fully described schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'deployments', scopes it to 'a namespace', and adds a specific detail: 'with replica status'. This differentiates it from sibling list tools like list_pods and list_namespaces by resource type, and the addition of replica status makes the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case by stating what it does, but it provides no explicit guidance on when to choose it over alternatives such as list_pods, list_services, or get_resource. There are no exclusion conditions or references to sibling tools, leaving selection largely to inference from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent events in a namespace — useful for diagnosing failures.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | kube-config context to target (defaults to current-context) | |
| namespace | Yes | Namespace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it read-only, idempotent, and non-destructive, so the description carries less burden. It adds the notion of 'recent' events, implying a time window, but does not elaborate on ordering, limits, or what exactly constitutes 'recent.' No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no redundancy, the core purpose and usage hint are front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool, the description is sufficient. It identifies the action, resource, and scope, and the annotations cover safety. It lacks details about response format or limits, but given no output schema and simplicity, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully documented in the schema (100% coverage), so the description adds no additional meaning. It does not explain the context parameter's default behavior beyond what schema says, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb and resource ('List events within a namespace'), with an explicit purpose ('diagnosing failures'). It is distinct from sibling list tools like list_pods, list_services, etc., because it specifically targets events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes the tool is 'useful for diagnosing failures,' giving a context for when to use it. However, it does not explicitly state when not to use it or point to alternatives, so it is slightly above baseline but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List namespaces in the cluster. Namespaces outside the allowlist are filtered out.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | kube-config context to target (defaults to current-context) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds meaningful behavioral context beyond the annotations by noting that namespaces outside the allowlist are filtered out, which is an important result-scoping behavior for an agent and is not expressed in the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the core operation, the second adds the crucial filtering constraint. It is front-loaded, has no redundant phrases, and every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only listing tool with one optional, fully documented parameter and strong annotations, the description covers the operational context. It tells the agent the cluster scope and the allowlist filtering, which is the only non-obvious behavior; no output schema means the tool's list-return nature is self-evident from the name and description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single optional 'context' parameter is fully documented in the input schema. The description adds no parameter-specific information, and the baseline of 3 is appropriate when the schema carries the documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List namespaces') and immediately identifies scope ('in the cluster') and the allowlist filtering behavior. This clearly distinguishes it from sibling tools like list_deployments, list_services, and list_contexts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need the list of allowed namespaces in the cluster) but does not explicitly name alternatives or provide when-not guidance. The allowlisting note provides some contextual usage information, but no direct comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List cluster nodes with readiness and kubelet version.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | kube-config context to target (defaults to current-context) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover the safety profile: readOnlyHint and idempotentHint true, destructiveHint false. The description adds that the result includes readiness and kubelet version, which is some useful factual context beyond the annotations. However, it could disclose more: how result sets are scoped/ordered, and any dependency on a valid kube-config context beyond the default. Thus it passes the lower bar for annotated tools but doesn't go further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence that carries the essential content: what is listed and which fields are shown. There is no filler, no restating of the tool title, and no repetitive phrasing. Every word earns its place, and the most informative element ('readiness and kubelet version') is placed right after the resource identifier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only a single optional parameter, no output schema, and a straightforward read-only behavior, this does not require much more complexity. The description provides the key result content, the schema documents the only parameter, and the annotations cover the safety semantics. It could elaborate a little on the form of the response (e.g., a list of names with fields), but it is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the context parameter's intended use and default behavior are fully documented in the input schema. The description does not need to repeat that. The default-to-current-context detail in the schema already tells the agent what choosing or omitting the parameter does, so assigning above the baseline is warranted for a fully self-contained parameter contract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource ('cluster nodes') and a specific verb ('List'), and goes further by naming the exact fields returned (readiness and kubelet version). This is immediately distinguishable from the sibling tools, which all target different cluster resources such as pods, deployments, services, and namespaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the description: an agent can infer this is the right tool when it needs to inspect node status at the cluster level. However, it never explicitly names when to prefer this tool over alternatives (e.g., list_pods for pod-level health, get_resource for targeted details), and it gives no when-not guidance. This is exactly 'implied usage' rather than explicit usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pods in a namespace with status, readiness, restarts, and node.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | kube-config context to target (defaults to current-context) | |
| namespace | Yes | Namespace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description aligns with these but adds context by specifying the output fields (status, readiness, restarts, node). It doesn't contradict annotations. The description is consistent and provides a bit of behavioral context beyond the annotations, but it doesn't disclose potential issues like the effect of the context parameter defaulting or any rate limits. Given the annotations cover safety, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose and includes essential details (scope and output fields). There is no wasted wording, and it is appropriately sized for the tool's simplicity. Every word earns its place, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, 0 nested, no output schema), the description is complete enough. It states what it does aligned with the annotations Dimensions and covers the key aspects: scope (namespace) and output fields. It doesn't explain return values, but since there is no output schema and the description lists the fields returned, that is sufficient. It doesn't mention pagination or limits, but for this type of tool, that's minor. Overall, it's adequate for safe and effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning both parameters (context and namespace) have descriptions. The tool description adds that the listing is 'in a namespace' and includes specific fields, which overlaps with the namespace parameter description. It doesn't add syntax details for the context parameter beyond what's in the schema. The description does clarify the purpose of namespace, but this is minimal enhancement; baseline 3 is appropriate because the schema already covers parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('List pods') on a specific resource ('pods') scoped to a namespace, including the fields returned (status, readiness, restarts, node). It is distinct from siblings like get_pod (which implies a single pod) and list_deployments. However, it doesn't explicitly differentiate from list_services or list_nodes, but the resource name itself is clear enough. The verb 'List' is specific and matches the tool name, avoiding tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use it (list pods in a namespace) and implicitly that it's a listing operation, contrasting with get_pod which retrieves a single pod. However, it doesn't explicitly mention when not to use it, such as when needing labels or filters, or when to use list_services or list_deployments. The mention of 'in a namespace' gives context, but there's no explicit alternative routing, leaving some inference needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List services in a namespace with type and cluster IP.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | kube-config context to target (defaults to current-context) | |
| namespace | Yes | Namespace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds value by specifying what records are returned ('type and cluster IP'), which is behavioral information not present in the annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no filler. It front-loads the action and resource, then adds the useful output details, so every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with strong annotations and fully described parameters, the description covers the essential purpose, scope, and output fields. It is slightly incomplete in that it does not mention any output structure beyond two fields or note default behavior for the optional context parameter, but those are minor gaps given the schema already documents context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so both parameters (context and namespace) are already documented. The description reinforces the namespace scoping but adds no new meaning beyond the schema, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), a clear resource ('services'), and a scope ('in a namespace'), and adds the return fields 'type and cluster IP'. It is unambiguous about what the tool does, but it does not explicitly contrast itself with the sibling list tools (e.g., list_pods, list_deployments), so it stops just short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus the sibling list tools or get_resource. The description implies its use case through the resource name, but it does not state context, exclusions, or alternatives, leaving the agent to infer when this list operation is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1get_pod1 field changedInput schema / additionalPropertiesRemoved value: -falseget_pod_logs1 field changedInput schema / additionalPropertiesRemoved value: -falseget_resource1 field changedInput schema / additionalPropertiesRemoved value: -falselist_deployments1 field changedInput schema / additionalPropertiesRemoved value: -falselist_events1 field changedInput schema / additionalPropertiesRemoved value: -falselist_namespaces1 field changedInput schema / additionalPropertiesRemoved value: -falselist_nodes1 field changedInput schema / additionalPropertiesRemoved value: -falselist_pods1 field changedInput schema / additionalPropertiesRemoved value: -falselist_services1 field changedInput schema / additionalPropertiesRemoved value: -falsev0.1.0get_podget_pod_logsget_resourcelist_contextslist_deploymentslist_eventslist_namespaceslist_nodeslist_podslist_servicesScored across 10 tools
Each tool targets a distinct resource or action: list contexts, namespaces, pods, deployments, services, nodes, events, and specific getters for pod details, logs, and arbitrary resources. No two tools have overlapping purposes; get_resource is clearly defined as a generic read that complements the specific ones.
All tools follow a consistent verb_resource pattern: list_* for enumerations and get_* for single-object retrieval. Names use lowercase snake_case consistently, with clear pluralization for list operations and singular for get operations, including a mixed get_pod_logs that still fits the pattern.
Ten tools is well-scoped for a Kubernetes read-only server, covering core resource types (pods, deployments, services, nodes, events) plus generic access. Each tool has a clear purpose and the count is neither overwhelming nor too thin.
The server provides comprehensive read coverage for common Kubernetes resources, including list/get operations, logs, events, and arbitrary object retrieval via get_resource. It lacks write operations (create/update/delete), but this appears intentional for a diagnostic-focused tool, leaving only minor gaps like lack of pod exec or resource watches.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Provides read access to your GKE and Kubernetes resources.
Managed Keycloak from any MCP client: clusters, realms, apps, SSO, users, domains, audit events.
Authenticated MCP server for ClearPolicy policy and compliance workflows.
