mait.sh1.69.2

Private beta: features and content may change. No warranty; use at your own risk.

Docs / Agent tools (MCP)

MCP Kubectl

Inspect Kubernetes workloads through structured tools and a kubectl-style command line.

For developers, cluster operators, and agents diagnosing Kubernetes workloads through reviewed credentials.

Read from the top for the basics; the later sections go deeper.

Edge
All components

What it doesBasics

  • Four read-only MCP tools: kubectl_get_pod_status, kubectl_deploy_status, kubectl_cluster_health, and kubectl_resource_summary
  • Thirty-nine kubectl-compatible CLI commands across configuration, inspection, deployment, debugging, and cluster-operation families
  • Structured pod and deployment status
  • Cluster health with optional node metrics
  • Namespace or cluster-wide resource summaries
  • Dynamic resource discovery and three MCP transports

First useBasics

  1. Confirm the intended cluster context and inspect a workload you are permitted to read.
  2. Check cluster health before narrowing to a deployment or pod.
  3. Use the direct CLI for detail beyond the four focused MCP tools.
  4. Restart the MCP Kubectl server process after kubeconfig, credential, or context changes.

Everyday tasksEveryday use

Diagnose deployment health

An agent must distinguish a workload problem from a cluster-wide problem.

  1. Call kubectl_cluster_health with include_metrics false using the intended context.
  2. Call kubectl_deploy_status with an explicit deployment and namespace.
  3. Call kubectl_get_pod_status for that namespace, then move to CLI detail only when required.

What you getThe agent narrows from cluster state to workload state without parsing a broad terminal table first.

How to check: Cluster, deployment, and pod status results record the diagnostic path.

Verify a local application after scaling

In an owned evaluation namespace, you want to see whether a web application continues serving after moving from one replica to two.

  1. Confirm the cluster context, namespace, workload identity and original replica count; check available capacity.
  2. Use the documented CLI scale operation to request two replicas for that evaluation deployment.
  3. Inspect rollout status and desired, updated, ready and available replicas, then check the application through its actual hostname and HTTPS route.
  4. Restore the original replica count when the evaluation ends and verify the application again.

What you getYou have checked both the requested replica change and the application response in the local environment.

How to check: Retain before-and-after replica state and the expected application response.

Inventory an unfamiliar namespace

An agent needs a bounded view before deciding which workload to inspect.

  1. Call kubectl_resource_summary with the namespace and resource_types explicitly set.
  2. Confirm an unexpected zero with a direct CLI get and authorization check for the same type and namespace.

What you getThe agent scopes subsequent inspection from a compact inventory.

How to check: The structured summary and direct verification output show both the initial signal and confirmation.

Settings to decideAdvanced

Credentials and context
KUBECONFIG resolves the first colon-separated path, then ~/.kube/config, then in-cluster credentials. Restart the MCP Kubectl server process after kubeconfig, credential, or context changes.
Namespace semantics
Pod and deployment tools default to namespace default. Resource summary without namespace is cluster-wide. Pass namespace explicitly whenever scope matters.
CLI or MCP surface
Use kubectl_get_pod_status, kubectl_deploy_status, kubectl_cluster_health, and kubectl_resource_summary for read-only composition. Use the CLI for broader inspection and operator-authorized mutation.
MCP transport
stdio is the editor-spawned default. Unix requires an explicit socket path. HTTP defaults to 127.0.0.1:8080. Reserve stdout exclusively for JSON-RPC in stdio mode.
Environment and output
KUBECONFIG selects credentials; EDITOR and VISUAL support edit workflows; RUST_LOG controls stderr tracing. CLI output formats are table, wide, json, yaml, and name.
Compatibility and protection
The client targets Kubernetes API 1.36 resources and kubectl 1.36.4 behavior. Each MCP call has a fixed 60-second protection timeout, and tool failures are reported in is_error.
Optional metrics
kubectl_cluster_health accepts include_metrics. With metrics-server installed, the result adds node_metrics.

CommandsAdvanced

$ mcp-kubectl cli config current-context
$ mcp-kubectl cli get nodes
$ mcp-kubectl cli get pods -n default
$ mcp-kubectl serve # stdio; register command + ["serve"] in the MCP client
$ kubectl_cluster_health({"include_metrics":false})
$ kubectl_deploy_status({"deployment":"web","namespace":"default"})
$ kubectl_get_pod_status({"namespace":"default"})
$ kubectl_resource_summary({"namespace":"default","resource_types":["pods","services","deployments"]})

Problems and fixesHelp

What you seeCheckFix
No cluster can be reached.Inspect KUBECONFIG, current context, in-cluster variables, and API reachability.Supply a valid reviewed configuration and restart the process so its cached client is rebuilt.
A query returns Forbidden.Check the active identity, context, namespace, and RBAC verb/resource grant.Use an appropriately scoped identity or request the minimum required RBAC change.
A resource summary unexpectedly reports zero.Run a direct CLI query and authorization check for the same resource and namespace.Correct permissions or target selection before treating the zero as an empty inventory.
An MCP health query fails after its fixed timeout.Verify API reachability and latency outside the composition call.Restore cluster connectivity or use a focused CLI diagnostic.
What you see
No cluster can be reached.
Check
Inspect KUBECONFIG, current context, in-cluster variables, and API reachability.
Fix
Supply a valid reviewed configuration and restart the process so its cached client is rebuilt.
What you see
A query returns Forbidden.
Check
Check the active identity, context, namespace, and RBAC verb/resource grant.
Fix
Use an appropriately scoped identity or request the minimum required RBAC change.
What you see
A resource summary unexpectedly reports zero.
Check
Run a direct CLI query and authorization check for the same resource and namespace.
Fix
Correct permissions or target selection before treating the zero as an empty inventory.
What you see
An MCP health query fails after its fixed timeout.
Check
Verify API reachability and latency outside the composition call.
Fix
Restore cluster connectivity or use a focused CLI diagnostic.

All MCP Kubectl problems and fixes →

Good to knowHelp

  • MCP Kubectl is installed separately from the MAIT image.
  • The four MCP tools are read-only; apply, delete, drain, taint and exec run through the CLI.
  • Your Kubernetes credentials, context, namespace and RBAC set its access.