Kubernetes MCP server — what it can actually reach, and what it should not

On this page#

• What a kubernetes mcp server actually gives an agent
• The config, line by line
• Scoping it down
• What breaks in a real repo
• When not to connect it at all
• FAQ

What a kubernetes mcp server actually gives an agent#

A kubernetes mcp server gives an AI agent a controlled path from repository context into cluster state. It should expose discovery, inspection, logs, and narrowly approved operations. It should not become a general-purpose cluster administrator, silently change production resources, read every Secret, or bypass the repository’s normal deployment path.

Model Context Protocol is the interface between the agent and external tools or data. The server publishes capabilities; the client makes them available to the agent. That boundary matters because an agent can only respect permissions that actually exist. A prompt saying “read-only” does not make an administrator credential read-only.

For repository work, the useful capability set is usually small:

• List workloads in one namespace.
• Read Deployments, Pods, Services, Jobs, and Events.
• Fetch logs from selected workloads.
• Inspect rollout and health status.
• Compare live state with manifests or generated output in the repository.
• Restart or delete a Pod only when the controller will recreate it and the operator explicitly approves.

The dangerous capability set is much larger:

• Reading Secrets across namespaces.
• Creating or modifying RBAC.
• Executing arbitrary commands inside containers.
• Applying unrestricted manifests.
• Deleting namespaces or persistent storage.
• Switching contexts without a visible configuration change.
• Reaching production from a development repository session.

MCP’s client–server architecture makes the trust boundary explicit, but it does not choose that boundary for you. The server process, its kubeconfig, and Kubernetes authorization determine what the agent can actually reach.

My default is simple: observation first, mutation exceptional, production disconnected.

Photo by panumas nikhomkhai on Pexels.

The config, line by line#

Use a dedicated server entry, credential, context, and namespace. Do not point the agent at your normal kubeconfig and hope it selects the right context. The following client configuration is intentionally explicit; it assumes the chosen kubernetes-mcp-server executable is already installed and available on the client’s command path.

{
  "mcpServers": {
    "kubernetes-readonly": {
      "command": "kubernetes-mcp-server",
      "args": [
        "--kubeconfig",
        "/Users/engineer/.kube/agent-readonly",
        "--context",
        "development-readonly",
        "--namespace",
        "payments"
      ],
      "env": {
        "KUBECONFIG": "/Users/engineer/.kube/agent-readonly"
      }
    }
  }
}

The surrounding shape follows the normal MCP model of a client launching and communicating with a server. The official reference-server repository is useful for understanding that pattern, but a reference implementation is not a security policy.

Line by line:

• mcpServers is the client’s registry of available MCP connections.
• kubernetes-readonly is a human-readable safety label. Name the boundary, not merely the technology.
• command identifies the installed server executable. Pin and distribute the implementation through the team’s normal tooling; do not let each engineer discover a different binary.
• --kubeconfig separates agent credentials from personal credentials.
• The absolute path avoids client-specific shell expansion and working-directory surprises.
• --context prevents the server from inheriting whichever context an engineer used last.
• --namespace limits the intended operating area. Kubernetes authorization must enforce the same boundary.
• KUBECONFIG repeats the dedicated credential path for implementations or subprocesses that consult the environment.

Do not commit the kubeconfig, tokens, certificates, or machine-specific paths. Commit a reviewed example with placeholders, document how credentials are issued, and keep the real configuration local.

For a repeatable team setup, the Agent Operating Kit is the relevant PairFoundry path: the valuable artifact is not one engineer’s working JSON, but an operating contract the second engineer can reproduce and audit.

Scoping it down#

Scope the Kubernetes identity before limiting the MCP tool list. Server-side authorization is the real control; hiding a tool in the client is only interface reduction. Grant one namespace, selected resource types, and read verbs first. Add individual mutations only after a concrete workflow proves they are necessary.

Start with this policy shape:

| Boundary | Recommended starting point | What you lose | |---|---|---| | Cluster | One non-production cluster | Cross-cluster diagnosis | | Namespace | One application namespace | Dependency visibility elsewhere | | Resources | Workloads, Services, Events, logs | Secret and infrastructure inspection | | Verbs | Read operations | Automated remediation | | Pod access | Logs only | Interactive debugging inside containers | | Credentials | Dedicated agent identity | Convenience of personal access |

The precise resource and verb names belong in Kubernetes RBAC, which should be reviewed against the Kubernetes documentation. The important rule is that Kubernetes must reject anything outside the declared scope even if the MCP server requests it.

Narrowing access has real costs. Namespace-only visibility can hide a failing shared dependency. Removing Secret reads prevents the agent from verifying a referenced value. Disabling container execution means it cannot run a diagnostic command inside a Pod.

Those losses are acceptable. Restore a capability through a deliberate, reviewable change—not through an administrator credential kept “just in case.”

Also separate read and write identities. A read-only server may stay connected during routine investigation. A mutation-capable server should be a distinct configuration with an unmistakable name, explicit approval, and short-lived credentials. Combining both modes under one friendly tool name is the wrong design.

If your team has not yet standardized agent permissions and repository instructions, start with the PairFoundry foundations track before connecting live infrastructure.

Photo by Lukas Blazek on Pexels.

What breaks in a real repo#

The connection usually fails operationally before it fails technically. The server starts, the agent receives tools, and kubectl-shaped requests return data—yet the workflow is still unsafe or misleading. Two failures recur: repository intent differs from live ownership, and local configuration differs between engineers.

The agent “fixes” state that another controller owns#

A successful mutation is not necessarily a successful fix. If GitOps, an operator, or another controller owns the resource, a direct change will be reverted or create drift. The agent may report completion while the system is already moving back toward declared state.

Use this criterion: if the durable source of truth is outside the MCP action, the action is diagnostic at best. The correct fix belongs in the owning manifest, chart values, operator input, or deployment pipeline.

The safe workflow is:

1. Read live state.
2. Identify the owning controller.
3. Locate the repository source of truth.
4. Propose the repository change.
5. Let the established deployment mechanism reconcile it.

The MCP architecture description explains how tools reach an external system; it does not establish which system owns the desired state. That ownership rule must live in repository instructions.

The second engineer reaches a different cluster#

Machine-local defaults create invisible divergence. One engineer has a development context selected; another last used production. One client expands environment variables; another passes them literally. Both configurations look “basically the same” during review.

Use this criterion: two engineers starting from the documented setup must resolve the same server binary, credential class, cluster, context, namespace, and capability set. If any of those depends on prior shell state, the setup is not reproducible.

Fail closed on missing values. Print the resolved cluster and namespace when the server starts. Give identities and configuration entries environment-specific names. Keep a tested example beside the repository’s agent instructions, without committing credentials.

For broader MCP operating patterns, use the MCP servers hub; for packaged workflows, see the PairFoundry packs overview.

When not to connect it at all#

Do not connect a kubernetes mcp server when the repository does not need live cluster evidence, the available credential cannot be narrowed, or the team lacks a clear ownership and rollback model. A convenient connection is not worth creating an ambiguous path around deployment controls.

Leave it disconnected when:

• The task is local code generation, refactoring, or unit testing.
• Production is the only reachable environment.
• The credential can modify RBAC, Secrets, storage, or namespaces broadly.
• Compliance rules prohibit sending cluster metadata through the selected agent workflow.
• The server’s tool behavior or implementation cannot be pinned and reviewed.
• The repository has no documented source-of-truth boundary.
• Operators cannot distinguish agent actions from human or controller actions.
• A failed mutation has no tested recovery path.

In those cases, provide sanitized logs, Events, or manifest output as explicit inputs. Less automation is better than unclear authority.

Photo by Digital Buggu on Pexels.

Related reading#

• Setting up MySQL MCP server without giving it your whole repo
• Shopify MCP server — what it can actually reach, and what it should not

FAQ#

Should the server use my existing kubeconfig?#

No. Use a dedicated kubeconfig and Kubernetes identity with a single documented context and narrow authorization. Personal kubeconfigs accumulate clusters and privileges over time; they also make the agent’s reach depend on the engineer running it, which destroys reproducibility and complicates incident review.

Is namespace scoping enough for team use?#

No. Namespace scoping is only one layer. Also restrict resource types, verbs, subresources such as logs, cluster selection, credential lifetime, and mutation tools. Verify the restrictions through Kubernetes authorization, because a namespace flag in an MCP configuration is not an enforceable security boundary by itself.

How should we roll back an agent mistake?#

Use the system that owns desired state. Revert the repository change and let the deployment controller reconcile it. For an approved direct operational action, record the before-state and a specific inverse action first. If neither recovery path is available, the agent should not receive mutation access.

How is this different from giving the agent kubectl?#

The security outcome can be identical if both use the same unrestricted credential. MCP can provide structured tools, clearer descriptions, and narrower interfaces, but it does not automatically reduce Kubernetes permissions. The dedicated identity and enforced authorization—not the protocol label—create the meaningful difference.

When is read-only access still too risky?#

Read-only is too risky when it exposes Secrets, sensitive logs, customer identifiers, cross-tenant metadata, or production topology that the agent workflow is not approved to process. “Read-only” prevents mutation; it does not prevent disclosure. In that situation, provide sanitized evidence instead of a live connection.