How to Configure Claude Code Kubernetes MCP Server
You set up a claude code kubernetes mcp server by linking the agent to your cluster API. You register the Model Context Protocol server in your local agent settings with a cluster role. Teams often use their own local admin credentials to get this working fast. When roles are too broad, the AI agent can delete pods or read cluster secrets by mistake. A safer setup uses a restricted role with read-only rules for specific namespaces. How a claude code kubernetes mcp server works Claude Code tal
Your coding agents run with your access.
Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.
You set up a claude code kubernetes mcp server by linking the agent to your cluster API. You register the Model Context Protocol server in your local agent settings with a cluster role. Teams often use their own local admin credentials to get this working fast. When roles are too broad, the AI agent can delete pods or read cluster secrets by mistake. A safer setup uses a restricted role with read-only rules for specific namespaces.
How a claude code kubernetes mcp server works
Claude Code talks to external tools and APIs through the Model Context Protocol. The MCP server sits on the user machine and translates agent requests into cluster API calls. You must verify that you trust each MCP server before you link it to your setup. Separately, the agent can run shell commands through its built-in Bash tool. In manual mode, the Bash tool asks for user approval before running non-read-only commands.
On the cluster side, native role-based rules control what the MCP server can do. A Role sets permissions inside one namespace. A ClusterRole sets rules across the whole cluster, including nodes and all namespaces. A RoleBinding grants those permissions to a user or service account in one namespace. A ClusterRoleBinding grants access across the entire cluster. In Kubernetes, permissions are purely additive, which means there are no deny rules. You start with zero access and add allowed verbs and resources one by one. Some cluster APIs use subresources, such as pod logs or pod exec sessions. You must grant permissions for these subresources explicitly in your role rules.
Planning role boundaries for AI agents
Start by creating a dedicated service account for the MCP server. Do not let the agent reuse a developer's personal admin token. Bind the service account to a Role in a single namespace when possible. If the agent only checks pod status, grant read verbs on pods and pod logs. Avoid granting access to the pod exec subresource unless the task requires command execution. Also avoid granting read rules on cluster secrets. Even if you block secrets, pod logs can still hold sensitive data.
What native cluster roles solve and what they miss
Native cluster roles decide who can call a specific API endpoint. If you bind the MCP server to a read-only role, it cannot delete deployments. That stops the worst accidents before they happen. It also keeps the agent inside the namespaces you choose.
Kubernetes API Server Access + Claude Code Security: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Still, static roles leave a big operational gap during live debugging. First, the MCP server needs a kubeconfig file on the user's laptop. That local file holds keys or tokens that someone or an agent could read. Second, cluster roles are all-or-nothing for each resource type. If the agent can read pod logs, it gets every line in those logs. Production logs often print customer emails, phone numbers, and card numbers in plain text. Native roles do not rewrite matched fields in results before the agent reads them. Third, if you grant pod exec access for debugging, the agent can run any shell command inside the container. Cluster RBAC checks if the session can start, not which commands run inside it. Finally, shared service accounts make it hard to tie actions back to one user.
Add request guardrails and response masking beside Kubernetes
Cluster roles and service accounts govern who reaches the Kubernetes API. Still, a broad role or agent can delete workloads or print sensitive values from ConfigMaps and logs. In practice, hoop.dev sits inline beside the API server as a sidecar for your Kubernetes API. For every production API call an agent or human sends, hoop.dev decides whether to pass, mask, block, or escalate it for review alongside RBAC.
With hoop.dev Kubernetes controls, guardrails allow listing Secret names while refusing reads of Secret data before execution, and data masking redacts matched keys in returned JSON responses and log streams in memory. Furthermore, hoop.dev holds SOC 2 Type II and is MIT licensed on GitHub.
Frequently asked questions
Can Claude Code reach a cluster without an MCP server?
Yes, Claude Code can run standard cluster CLI commands through its built-in Bash tool. In manual mode, it asks for user approval before running commands that are not on its safe read-only list.
Should I use a Role or a ClusterRole for the MCP server?
Use a Role with a RoleBinding when the agent only works in one namespace. Use a ClusterRole only when the agent must inspect nodes or check pods across every namespace.
Why do pod logs still create a risk with read-only roles?
A read-only role stops changes to the cluster, but it still returns full log output. If an app logs emails, phone numbers, or card numbers, those values go straight into the agent prompt.
Related guides
In this post