Kubernetes-MCP-Guard

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

🛡️ Kubernetes MCP Guard

Bridging the gap between AI Agents and Production Infrastructure with a Security-First Gateway.

🎯 The Problem

Giving AI agents direct access to Kubernetes is risky. Without a safety layer, an LLM "hallucination" or a prompt injection could accidentally delete a production namespace or leak sensitive secrets.

🚀 The Solution

Kubernetes-MCP-Guard is a high-performance gateway built on .NET 10 and the Model Context Protocol (MCP). It provides a secure, audited, and human-gated interface that allows AI agents (like Claude Code or Open WebUI) to interact with your clusters without compromising safety.

💎 Key Business Value

Human-in-the-Loop Governance: AI can propose changes, but only a human can approve the final execution plan — via a separate browser-based approval flow that the MCP client cannot intercept or answer on the human's behalf.
Enterprise-Grade Security: Integrated with OAuth-aware authentication and Namespace-scoped RBAC to ensure the AI only sees what it is allowed to see.
AI Safety & Auditing: Built-in prompt-injection guardrails and full audit logging for compliance and troubleshooting
Cutting-Edge Stack: Architected using the latest .NET 10 features and the industry-standard MCP protocol.

🗺️ System Architecture

The following diagram illustrates the secure request flow from the AI client through the Guardrails and into the Kubernetes cluster.

---
title: Kubernetes-MCP-Guard Flow
---
flowchart TB
    Client["MCP client<br/>Codex / Open WebUI / LibreChat"]

    subgraph Gateway["HTTP MCP Gateway"]
        Auth["OAuth JWT auth"]
        Guardrails["Prompt-injection guardrails"]
        Audit["Guardrail audit log"]
        Auth --> Guardrails
        Guardrails --> Audit
    end

    subgraph Server["Kubernetes MCP Server"]
        Tools["Typed Kubernetes tools"]
        ReadOnly["Bounded read-only observability"]
        Plans["Approval-gated mutation plans"]
        Tools --> ReadOnly
        Tools --> Plans
    end

    subgraph Kubernetes["Kubernetes boundary"]
        RBAC["Namespace-scoped RBAC"]
        API["Kubernetes API"]
        RBAC --> API
    end

    Client --> Auth
    Guardrails --> Tools
    ReadOnly --> RBAC
    Plans --> RBAC

🔐 How Approval-Gated Mutations Work

The diagram below shows what happens when an AI agent tries to make a change to your cluster. The key point: the AI cannot approve its own requests. Approval happens in your browser, on a completely separate channel with its own login.

---
title: Out-of-Band Approval Flow
---
flowchart TB
    classDef ai      fill:#e8f0fe,stroke:#4285f4,color:#1a1a2e,font-size:13px
    classDef browser fill:#e6f4ea,stroke:#34a853,color:#1a1a2e,font-size:13px
    classDef gate    fill:#fff3e0,stroke:#fb8c00,color:#1a1a2e,font-size:13px
    classDef k8s     fill:#fce4ec,stroke:#e53935,color:#1a1a2e,font-size:13px

    subgraph AI["① AI / MCP Channel"]
        direction TB
        A1["🤖 AI agent requests a change e.g. scale deployment to 3 replicas"]
        A2["Gateway validates identity; server dry-runs and creates a pending plan locked with a SHA-256 hash"]
        A3["⛔ AI receives an approval URL only.
         It cannot approve on your behalf"]
        A4["AI calls apply again once human has approved"]
    end

    subgraph OOB["② Your Browser  —  separate login, separate session"]
        direction TB
        B1["🔗 You open the approval URL in your browser"]
        B2["You log in with OAuth independent of the AI session"]
        B3["Browser shows the real plan rendered by the Gateway from disk not by the AI"]
        B4["You review: operation, namespace, affected objects, expiry time"]
        B5["✅ You click Approve  or  ❌ Deny"]
    end

    K8s["☸️ Kubernetes Change is applied only after both channels agree"]

    A1 --> A2 --> A3
    A3 -.->|"URL shown to AI, opened by you"| B1
    B1 --> B2 --> B3 --> B4 --> B5
    B5 -->|"Approval recorded with identity binding"| A4
    A4 --> K8s

    class A1,A2,A3,A4 ai
    class B1,B2,B3,B4,B5 browser
    class K8s k8s

_{Even if the AI agent is compromised, it cannot self-approve. The approval must come from your browser session a channel the AI has no control over.} _{Simplified architectural graph. Full version here}

🛠️ Technical & Architectural Highlights

AI Integration & Safety: Deep implementation of Model Context Protocol (MCP), handling tool contracts, out-of-band approval workflows, and mitigating prompt-injection risks within model-visible data.
Security & Identity: Implemented OAuth 2.0 resource-server patterns, including scope enforcement, identity-based audit logging, and strict Least-Privilege RBAC for Kubernetes interactions.
Cloud-Native Engineering: Advanced usage of the Official Kubernetes .NET Client, utilizing Server-Side Apply (SSA) for dry-run planning, real-time Pod log streaming, and namespace isolation.
Modern .NET 10 Stack: Built with a focus on Clean Architecture, leveraging Dependency Injection, high-performance Async/Await patterns, and a modular project structure that separates Auth, Gateway, and Core logic.
Product Mindset: Prioritized a "small operational surface" and human-readable audit logs, ensuring the tool is as safe for a human SRE as it is powerful for an AI agent.

🏗️ Implementation Details:

Exposes Kubernetes operations through the Model Context Protocol (MCP), with a stdio Kubernetes server behind a local HTTP gateway.
Uses the Kubernetes API via KubernetesClient; it does not shell out to kubectl for runtime operations.
Adds OAuth authentication at the gateway, including MCP protected-resource metadata, insufficient-scope challenges, and browser approval sessions.
Applies prompt-injection guardrails around model-visible tool input/output, with warn, redact, and audit behavior.
Keeps mutation paths approval-gated: create a plan first, approve it in the Gateway browser UI, then apply the exact approved plan.
Limits Kubernetes blast radius with namespace-scoped RBAC and typed, bounded tool surfaces.

📦 Container Images

Images are automatically built, scanned, and published to multiple registries for every release.

Registry	Gateway (Core)	Dev Issuer (Auth)
GitHub (GHCR)	`ghcr.io/mirusser/kubernetes-mcp-guard-gateway:<tag>`	`ghcr.io/mirusser/kubernetes-mcp-guard-devissuer:<tag>`
Docker Hub	`mirusser/kubernetes-mcp-guard-gateway:<tag>`	`mirusser/kubernetes-mcp-guard-devissuer:<tag>`

Versioning: Use specific tags (e.g., :v0.1.0) for production stability. The :latest tag tracks the most recent stable release.

Example pull:

docker pull ghcr.io/mirusser/kubernetes-mcp-guard-gateway:latest

⚡ Quick Start

Option 1 — Run from published images (no build required)

Prerequisites: Docker Compose v2, minikube, git.

git clone https://github.com/mirusser/Kubernetes-MCP-Guard.git

cd Kubernetes-MCP-Guard

./scripts/create-demo-kubeconfig.sh --compose
TAG=latest docker compose -f deploy/mode-c/compose.release.yaml up

Replace latest with a specific release tag (e.g. v0.1.0) for a stable run. Available tags are listed on the Releases page.

Connect Codex CLI:

Add this block to ~/.codex/config.toml (create the file if it does not exist):

[mcp_servers.infra-gate]
url = "http://127.0.0.1:3001/mcp"
oauth_resource = "http://127.0.0.1:3001/mcp"
scopes = ["mcp:tools"]

Then log in:

codex mcp login infra-gate # authenticate 
codex # run codex

Connect Claude Code:

# 1. Add/register the MCP server
claude mcp add-json --scope user infra-gate \
  '{"type":"http","url":"http://127.0.0.1:3001/mcp","oauth":{"scopes":"mcp:tools"}}'

# 2. Start Claude Code
claude

# 3. Inside Claude Code, open MCP manager/auth flow
/mcp

After successful log in you may start with:

Explain briefly what are the capabilities of MCP server: infra-gate

Option 2 — Build and run from source

Prerequisites: .NET 10 SDK, Docker Compose v2, minikube, git.

./scripts/create-demo-kubeconfig.sh --compose
docker compose -f deploy/mode-c/compose.yaml up --build

Connect Codex the same way as Option 1.

Other run modes and full setup details are in the Setup Guide.

🧰 Current Capabilities

🛡️ Gateway Protections

Layer	Behavior
Authentication	OAuth 2.1 JWT for MCP plus browser OAuth cookie for approvals
Prompt-injection guardrails	Warn and redact suspicious model-visible input/output
Audit logging	JSONL guardrail audit with identity resolution
MCP compliance	Streamable HTTP transport, protected-resource metadata, step-up authorization

🔎 Read-Only Observability

Tool	Purpose
`get_allowed_namespaces`	Namespace allow-list the server is configured to access
`get_k8s_status`	Deployments, Services, ConfigMaps, Pods, and ReplicaSets in a namespace
`get_k8s_events`	Bounded `events.k8s.io/v1` cluster diagnostics
`get_pod_logs`	Bounded Pod log reads (tail lines + byte cap)
`get_k8s_resource`	Focused resource summary — no Secret values, ConfigMap data, or raw manifests
`get_deployment_diagnostics`	Deployment health, related Pods, ReplicaSets, and Events
`get_pod_diagnostics`	Pod status, conditions, container state, and Events
`get_service_diagnostics`	Service endpoints, backing Pods, and Events

✅ Approval-Gated Mutations

Tool	Purpose
`request_apply_manifest`	Dry-run and plan a server-side apply for `Deployment`, `Service`, or `ConfigMap`
`request_delete_manifest`	Dry-run and plan a resource deletion
`request_scale_deployment`	Dry-run and plan a replica count change
`request_restart_deployment`	Dry-run and plan a rollout restart
`request_set_deployment_image`	Dry-run and plan a container image update
`apply_approved_plan`	Repeat dry-run, then apply an exact-hash-verified, user-approved plan

🎬 See It In Action

End-to-end walkthrough of the approval-gated workflow against a deliberately broken Deployment: docs/demo-failing-deployment.md. Uses the demo manifests under examples/failing-deployment/.

Compatibility

Area	Supported / tested
.NET	.NET 10
Kubernetes	minikube / local cluster initially
MCP transport	HTTP MCP endpoint at `/mcp`
OIDC	DevIssuer (dev), Keycloak documented; Entra ID later
Container registries	GHCR, Docker Hub
Platforms	linux/amd64 initially

🧭 Explore The Project

Developer runbook: docs/devs-readme.md
Setup guide: docs/setup-guide.md
Configuration reference: docs/configuration.md
MCP compliance notes: docs/MCP-compliance.md
Security model: docs/security-model.md
Tool permissions matrix: docs/tool-permissions.md
Production OIDC guide: docs/production-oidc.md
Public roadmap: docs/roadmap.md
Kubernetes MCP server: src/InfraGate.McpServer/README.md
HTTP MCP gateway: src/InfraGate.McpGateway/README.md
Gateway auth: src/InfraGate.McpGateway.Auth/README.md
Local dev OAuth issuer: src/InfraGate.DevIssuer/README.md

_{Naming note: The public name is Kubernetes MCP Guard. The internal codename InfraGate appears in .slnx, project folders, env-var prefixes (INFRA_GATE_*), and Docker labels. They refer to the same project; the rename is gradual and does not change runtime behavior.}

⚖️ Governance & Policies

License: Apache-2.0
Security policy: SECURITY.md
Contributing guide: CONTRIBUTING.md
Changelog: CHANGELOG.md
Release process: docs/releasing.md

Related Servers

Alpha Vantage MCP Server

sponsor

Access financial market data: realtime & historical stock, ETF, options, forex, crypto, commodities, fundamentals, technical indicators, & more

Vibe-Coder

A server for a structured, LLM-based coding workflow, from feature clarification and planning to phased development and progress tracking.

Qase MCP Server

An MCP server for interacting with the Qase test management platform.

GitHub Issue Reproduction MCP Server

An intelligent MCP server that automates the reproduction of GitHub issues for AWS CDK projects.

Universal Crypto MCP

Enable AI agents to interact with any EVM blockchain through natural language.

Elementor MCP Server

Perform CRUD operations on Elementor page data for a target WordPress website.

Nereid - Mermaid charts

Create and explore Mermaid diagrams in collaboration with AI agents

MCP Server Creator

A meta-server for dynamically generating MCP server configurations and Python code.

Azure DevOps

An MCP server for interacting with Azure DevOps agents and queues.

MCP Stdio Server

An MCP server using stdio transport, offering file system access, a calculator, and a code review tool. Requires Node.js.

MCP_Agent:RE

Fetches requirements and defect data from the TAPD platform to provide data support for AI clients.