Kubernetes-MCP-Guard

AI-safe approval plan gated Kubernetes operations through MCP with OAuth, RBAC, audit, guardrails.

Human-approved, AI-driven Kubernetes remediation through a guarded MCP gateway.

Observer detects anomalies.
Planner proposes an evidence-backed plan.
Human reviewer approves out-of-band.
Executor runs only the approved digest-bound plan.
Everything is auditable.

When something breaks, the system can collect evidence, propose a bounded fix, dry-run it, package it into a reviewable plan, and wait for a human to approve.

It is a security-first bridge between AI agents and Kubernetes, with out-of-band, OAuth-authenticated, human-in-the-loop (HITL), plan-based approval for every gateway-exposed mutation.

AI agents can help diagnose infrastructure problems, but giving them direct mutation access is risky. Kubernetes MCP Guard explores a safer pattern: agents may observe, dry-run, and propose bounded remediations, while humans approve the exact digest-bound plan before any Kubernetes write occurs.

https://github.com/user-attachments/assets/4e06b4ee-db80-4d74-96cc-38dfbb413042
- A Deployment is intentionally broken.
- The Observer detects the unhealthy workload.
- The Planner proposes a bounded remediation.
- An approval access code is sent to the configured operator by email.
- An authenticated human approves the exact plan in the browser.
- The Executor applies the approved mutation.

The walkthrough indocs/demo-failing-deployment.mdshows the full flow against a deliberately broken Deployment.

- Plan before mutate:every gateway-exposed write starts as arequest_plan built from Kubernetes server-side dry-run evidence.
- Separate review channel:the MCP client receives an approval URL, while approval happens through/approvals/in a browser OAuth session.
- Digest-bound approval:execution is bound to an Intent Digest for the executable mutation and a Review Digest for the human-reviewed snapshot.
- Durable grant model:an approved Approval Challenge records a Challenge Outcome and issues an Approval Grant consumed by pre-execution gates.
- Narrow Kubernetes scope:namespace allow-lists, namespace-scoped RBAC, supported-kind checks, and bounded read tools keep the operational surface small.
- Auditable controls:guardrail and approval events are written as JSONL streams with identity, digest, grant, and execution context.
- Structured multi-agent coordination:Observer, Planner, and Executor are independent processes (agents) that communicate over theA2A protocol(viaa2a-dotnet), each with a separate OAuth service identity and a narrow gateway scope. The Planner owns a durable per-anomaly Task that persists across restarts and enforces one-remediation-per-anomaly without cross-service locking.

SeeCONTEXT.md,docs/mutation-approval-profile.md,docs/mutation-approval-flow.md.

--- title: Security Boundaries --- flowchart TB subgraph outer["🌐 Internet / Operator"] Human["👤 Operator\nbrowser · OAuth PKCE"] McpClient["🤖 MCP Client\nCodex · Claude Code"] end subgraph gateway["🛡️ Gateway — OAuth JWT required"] direction LR Guard["🔍 Guardrails\n+ ToolScopeGuard"] ApprovalUI["📋 Approval UI\n/approvals/"] ApprovalCore["🔐 Approval Core\nplan · challenge · grant · digest"] end subgraph agents["🤖 Agent Tier — client_credentials · narrow scopes"] direction LR Obs["🔎 Observer\nmcp:tools.readonly"] Plan["📋 Planner\nmcp:tools.propose + readonly"] Exec["🛠️ Executor\nmcp:tools.execute"] Obs <-->|"A2A"| Plan <-->|"A2A"| Exec end subgraph private["🔒 Private Subprocess — no public port"] McpServer["⚙️ McpServer\nKubernetes tools"] end K8s(("☸️ Kubernetes API\n(namespace-scoped RBAC)")) Human -->|"review snapshot · approve/deny"| ApprovalUI --> ApprovalCore McpClient -->|"Bearer JWT · mcp:tools.read/write"| Guard -->|"scope-filtered tool call"| ApprovalCore agents -->|"Bearer JWT · service identity"| Guard ApprovalCore -->|"stdio · service token"| McpServer -->|"KubernetesClient"| K8s

Current implementation notes are tracked indocs/mutation-approval-profile.md#current-repository-fit.

Prerequisites:Docker Compose v2,kubectl,minikube, andgit.

Reviewdocs/configuration.mdbefore changing runtime settings.

git clone https://github.com/mirusser/Kubernetes-MCP-Guard.git cd Kubernetes-MCP-Guard export InfraGate__OpenRouter__ApiKey="<openrouter-api-key>" make quickstart

Use source mode when you want the gateway, Observer, Planner, and Executor built from local code. This path also requires the[.NET 10 SDKand an OpenRouter API key for the LLM-backed agents.

export InfraGate__OpenRouter__ApiKey="<openrouter-api-key>" make quickstart-source

…