Labsco
MCP SERVER

Kubernetes-MCP-Guard

by mirusser

AI agents can propose Kubernetes fixes; a human approves the exact plan in a browser before anything is applied.

Agent Guardrails, Content Safety & Audit
Summary
Approval is necessary but not sufficient — the gates run again at execution time.

The design point worth understanding is that a human's approval does not authorise a blank cheque: when the client retries execution, the gateway revalidates the grant, the digests, the validity window, a second dry run and live-state drift before the adapter writes. So a plan approved against one cluster state will not silently apply against a different one. That, plus reviewing a stored snapshot rather than model-supplied text, is what separates this from an approval prompt.

What it is

A gateway that sits between MCP clients and a Kubernetes cluster and refuses to let a model mutate anything directly. Every write starts as a plan built from a server-side dry run, gets bound to a digest, and waits for a human to approve it in a separate browser session under OAuth. Three agents — Observer, Planner, Executor — run as independent processes with their own service identities and narrow scopes, so the component that detects a problem is not the component that can fix it.

What you get
  • Read-only inspection: `get_allowed_namespaces`, `get_k8s_status`, `get_k8s_events`, `get_pod_logs`, `get_k8s_resource`
  • Diagnostics that gather the related objects for you: `get_deployment_diagnostics`, `get_pod_diagnostics`, `get_service_diagnostics`
  • Planning, not mutating: `request_apply_manifest`, `request_delete_manifest`, `request_scale_deployment`, `request_restart_deployment`, `request_set_deployment_image` each dry-run the change and produce a plan
  • Approval flow: `execute_approved_plan` first returns a browser URL, then executes once a grant exists; `get_plan_status` and `wait_for_plan_approval` track it
  • `propose_plan` is the Planner's entry point, and sends an approval access code to the configured operator email
  • The browser renders the stored review snapshot, not text the model supplied
  • Guardrail and approval events are written as separate JSONL audit streams
  • The gateway does not expose shell execution, kubectl passthrough, exec, attach, port-forward, Secret reads or cluster-scoped writes
Requirements

Docker Compose v2, kubectl, minikube and git for the quickstart, plus an OpenRouter API key in `InfraGate__OpenRouter__ApiKey` for the LLM-backed agents. `make quickstart` brings up a Keycloak-backed OAuth path, a PostgreSQL approval store and the published gateway image; building from source additionally needs the .NET 10 SDK. Clients connect over HTTP MCP at `http://127.0.0.1:3001/mcp` and authenticate with OAuth, requesting `mcp:tools.read` or `mcp:tools.write`. The project describes itself as experimental and not production-certified.

Setup effort

One command plus a key — claude mcp add-json --scope user infra-gate \ '{"type":"http","url":"http://127.0.0.1:3001/mcp","oauth":{"scopes":"mcp:tools.read"}}', then supply credentials