How to Configure Pydantic AI Kubernetes MCP Server

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up a pydantic ai kubernetes mcp server, link your agent to the tool server and bind a least-privilege Kubernetes role. Next, give the server a scoped credential so the agent can read cluster state and run allowed tasks. Many teams start by giving the tool server a broad admin role during tests. That quick shortcut often stays in place when the app moves to production. If an agent uses an admin role, one bad prompt can delete workloads across every namespace. A safe setup pairs your agent

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.

To set up a pydantic ai kubernetes mcp server, link your agent to the tool server and bind a least-privilege Kubernetes role. Next, give the server a scoped credential so the agent can read cluster state and run allowed tasks.

Many teams start by giving the tool server a broad admin role during tests. That quick shortcut often stays in place when the app moves to production. If an agent uses an admin role, one bad prompt can delete workloads across every namespace. A safe setup pairs your agent framework with strict cluster rules from day one.

How a pydantic ai kubernetes mcp server works with RBAC

The setup has three parts that work together. First, your Python agent shapes requests and checks tool inputs against clear types. Second, the Model Context Protocol server translates those tool calls into standard Kubernetes API requests. Third, the Kubernetes API server checks the identity and role of the server before it runs any request.

Kubernetes role-based access control uses roles and bindings to manage permissions. In Kubernetes, rules are purely additive, which means there are no deny rules. You start with zero access and add only the actions the agent needs. A standard Role sets permissions inside one single namespace. A ClusterRole is not tied to one namespace and can cover nodes or resources across all namespaces.

To grant these rules to your server, you create a binding. A RoleBinding gives permissions inside one namespace and can point to a Role or a ClusterRole. A ClusterRoleBinding grants access across the whole cluster. For most agent tasks, you should bind the server identity to one namespace with a RoleBinding.

You also need to watch out for subresources in the API. Kubernetes writes subresources with a slash, such as the log or exec endpoints on pods. If your agent only needs to read pod logs, grant access to that subresource alone. Do not grant exec access unless the agent must run commands inside containers.

How to scope agent tool calls in your cluster

Before you turn on the server, list the exact tasks the agent will do. Most support agents only need to read pod statuses, check events, and read logs. Build a Role in a test namespace that allows only read verbs on those items. Then bind that Role to the service account that runs your MCP server.

Kubernetes API Server Access + AI Agent Security: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

On the Python side, register the MCP server as a toolset for your agent. The agent reads the tool schemas from the server and learns which calls it can make. When a user asks a question, the model picks a tool and sends structured arguments. The MCP server receives the call and queries the Kubernetes API using its bound service account. If the model tries to delete a deployment, the API server blocks the call based on the Role.

What native roles solve and where they fall short

Native Kubernetes roles are great at deciding which API endpoints a service account can reach. They stop an agent from touching namespaces or resource types outside its binding. This forms a strong base for cluster safety.

Still, static roles only check who logs in and which API path they hit. They cannot inspect what an individual command or payload does in flight. For example, if a role allows pod exec, the API server allows any shell command inside that pod. Similarly, if an agent reads pod logs, native roles cannot rewrite sensitive data inside that text. Logs often contain user emails, phone numbers, card numbers, or national IDs. Without in-flight checks, those raw strings flow straight back into the model context.

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 runs beside the API server as a sidecar for your Kubernetes API and checks every request and response alongside RBAC.

With hoop.dev Kubernetes controls, guardrails can allow listing Secret names while refusing reads of Secret data before execution. 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

Should I use a Role or a ClusterRole for an AI agent?

Use a standard Role and RoleBinding whenever your agent works in a single namespace. Only use a ClusterRole if the agent must inspect nodes or read state across all namespaces.

How do I let an agent read pod logs without giving it shell access?

In your Kubernetes role rules, grant get and list verbs on the pods log subresource. Leave the pods exec subresource out of the role so the agent cannot open a shell.

Why can native Kubernetes RBAC not block specific shell commands inside a pod?

Kubernetes RBAC checks permissions at the API resource and verb level when a request arrives. Once it approves a pod exec request, it does not inspect the shell commands sent over the stream.

The query runs. The emails stay hidden.