{"slug": "i-m-building-a-read-only-context-engine-for-kubernetes-and-ai-agents", "title": "I'm building a read-only context engine for Kubernetes and AI agents", "summary": "Developer lucasepe built kctx, a read-only Kubernetes context engine designed to provide structured operational facts for humans, scripts, and AI agents. The tool compiles live cluster state into compact models, enabling queries like service tracing and namespace health without mutating resources. It also supports the Model Context Protocol for safe AI agent integration.", "body_md": "Kubernetes gives us an incredibly powerful API.\n\nIt also gives us a familiar debugging ritual:\n\n```\nkubectl get pods\nkubectl describe pod ...\nkubectl get svc ...\nkubectl get endpointslices ...\nkubectl get deployment ...\nkubectl get events ...\nkubectl get application.argoproj.io ...\n```\n\nThen we mentally stitch the result together.\n\nWhich workload owns this Pod? Which Service routes to it? Are there ready endpoints? Is the namespace unhealthy because of one bad Deployment, a missing backend, warning Events, or something else?\n\nWhich facts should I paste into an incident, attach to a CI failure, or give to an AI assistant before asking it to reason?\n\nI started building [ kctx](https://github.com/lucasepe/kctx) because I wanted a small tool for that missing middle layer: not raw YAML, not a dashboard, not an auto-remediation system.\n\nJust structured Kubernetes context.\n\n[ kctx](https://github.com/lucasepe/kctx) is a read-only Kubernetes context engine for humans, scripts, and AI agents.\n\nIt turns live Kubernetes API state into a compact model of:\n\nThe design goal is intentionally conservative:\n\nread cluster state, normalize facts, avoid speculative root-cause claims.\n\nThat boundary matters.\n\nI do not want [ kctx](https://github.com/lucasepe/kctx) to be a tool that confidently invents explanations. I want it to provide the evidence layer that humans, automation, and AI agents can use before reasoning.\n\nMost Kubernetes tools are optimized for one of a few jobs:\n\n`kubectl`\n\nexposes the raw API very wellThose are all useful. I use them too.\n\nBut during debugging, there is still a recurring gap between \"I can query every object\" and \"I have a compact operational picture of what is connected to what.\"\n\nFor example, when looking at a Service, I often care less about the complete YAML and more about questions like:\n\nThat is the kind of context [ kctx](https://github.com/lucasepe/kctx) tries to assemble.\n\n```\nkctx trace service payments-api --namespace payments\n```\n\nFor a namespace-level view:\n\n```\nkctx health namespace payments\n```\n\nFor a focused resource view:\n\n```\nkctx explain pod api-xyz --namespace payments\n```\n\nAnd when you need a deterministic JSON snapshot for automation or incident review:\n\n```\nkctx dump namespace payments > payments-dump.json\n```\n\n[ kctx](https://github.com/lucasepe/kctx) does not mutate Kubernetes resources.\n\nIt does not:\n\nThat is not because remediation is uninteresting. It is because I think the context layer should be boring, auditable, and safe before anything else is built on top of it.\n\nThis becomes even more important when AI agents enter the picture.\n\nIf an agent needs Kubernetes context, I would rather give it a narrow read-only tool that returns structured facts than hand it broad cluster access and hope the prompt is enough of a safety boundary.\n\nOne of the areas I am experimenting with is exposing `kctx`\n\nthrough the Model Context Protocol.\n\nCurrent serve modes include:\n\n```\nkctx serve --mode mcp\nkctx serve --mode mcp-sse\n```\n\nThe MCP tools currently cover the same core context operations:\n\n`get_namespace_health`\n\n`explain_resource`\n\n`trace_service`\n\n`get_pod_graph`\n\n`dump_namespace`\n\nThe idea is simple: let an AI assistant ask for Kubernetes context without giving it mutation capabilities.\n\nJust compact operational facts that can be used as evidence.\n\nThere is also an MCP/SSE release test guide for anyone who wants to try this with a local kind cluster, the released Helm chart, Online Boutique, ngrok, Codex, Claude Code, or ChatGPT Developer Mode:\n\n[https://github.com/lucasepe/kctx/tree/main/docs/kctx-mcp-sse-release-test-guide.pdf](https://github.com/lucasepe/kctx/tree/main/docs/kctx-mcp-sse-release-test-guide.pdf)\n\nImportant note: the MCP/SSE endpoint is read-only, but built-in AuthN/AuthZ is not production-ready yet. Treat it as local-lab or trusted-network tooling for now, or put it behind an external access-control layer.\n\nAnother design choice: [ kctx](https://github.com/lucasepe/kctx) does not pretend that every custom resource can be understood generically.\n\nKubernetes discovery can tell you that a CRD exists. It cannot tell you what that CRD means operationally.\n\nSo [ kctx](https://github.com/lucasepe/kctx) uses explicit adapters for ecosystem-specific resources. An adapter can translate a CRD into the same core model used by the rest of the project: resource identity, compact status, related entities, relations, signals, and graph nodes or edges.\n\nThe current adapter set includes:\n\n`Application`\n\n`AppProject`\n\n`Certificate`\n\nThat approach is slower than saying \"we support every CRD\", but I think it is more honest. If a tool is going to describe operational context, it should know what it is describing.\n\nThe CLI and HTTP API emit versioned JSON by default.\n\nResponses include a schema version and kind, for example:\n\n```\n{\n  \"schemaVersion\": \"kctx.io/v1alpha1\",\n  \"kind\": \"NamespaceHealth\"\n}\n```\n\nThe repository includes machine-readable JSON schemas under:\n\n```\nschemas/kctx.io/v1alpha1\n```\n\nThat part may sound less exciting than graphs or agents, but it is one of the pieces I care about most.\n\nIf humans are the only users, text output can be enough. If scripts, CI systems, incident tooling, and AI agents are also users, the output needs a contract.\n\n[ kctx](https://github.com/lucasepe/kctx)` is designed to provide operational context, not sensitive data.\n\nIt avoids returning raw manifests, Secret data, ConfigMap data, raw environment variables, logs, and workload metrics.\n\nSupported outputs also pass metadata and Kubernetes messages through a small redaction policy for common secret-bearing keys and text patterns.\n\nThis is not a magic privacy shield, but it is an intentional boundary in the design.\n\nInstall:\n\n`bash`\n\ncurl -fsSL https://raw.githubusercontent.com/lucasepe/kctx/main/install.sh | bash\n\nRun against your current Kubernetes context:\n\n`bash`\n\nkctx health namespace default\n\nkctx explain pod <pod-name> --namespace default\n\nkctx trace service <service-name> --namespace default\n\nkctx graph pod <pod-name> --namespace default --render mermaid\n\nkctx dump namespace default\n\nOr run the read-only HTTP server:\n\n`bash`\n\nkctx serve\n\ncurl http://localhost:8080/health/namespace/default\n\nOr install the in-cluster server with Helm:\n\n`bash`\n\nVERSION=0.3.0\n\nhelm upgrade --install kctx \\\n\n\"https://github.com/lucasepe/kctx/releases/download/v${VERSION}/kctx-${VERSION}.tgz\" \\\n\n--namespace kctx-system \\\n\n--create-namespace\n\nThen:\n\n`bash`\n\nkubectl -n kctx-system port-forward svc/kctx 8080:8080\n\ncurl http://localhost:8080/health/namespace/default\n\nThe project is still under active development. It is useful today, but I am still hardening packaging, production deployment guidance, auth boundaries for server mode, and client compatibility around MCP/SSE.\n\nI would love feedback from SREs, platform engineers, Kubernetes operators, and people experimenting with AI-assisted operations.\n\nIn particular:\n\nIf you try the MCP/SSE path, I am especially interested in:\n\nGitHub:\n\n[https://github.com/lucasepe/kctx](https://github.com/lucasepe/kctx)\n\nIf this idea resonates with you, a star would help the project reach more Kubernetes and platform people.\n\nBut even more useful: open an issue, tell me where the model feels wrong, or share a debugging scenario where structured context would have saved time.\n\nThat is the kind of feedback that can make [ kctx](https://github.com/lucasepe/kctx) sharper.", "url": "https://wpnews.pro/news/i-m-building-a-read-only-context-engine-for-kubernetes-and-ai-agents", "canonical_source": "https://dev.to/lucasepe/im-building-a-read-only-context-engine-for-kubernetes-and-ai-agents-40nh", "published_at": "2026-06-15 08:03:09+00:00", "updated_at": "2026-06-15 08:11:04.806172+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["lucasepe", "kctx", "Kubernetes", "Model Context Protocol", "MCP", "SSE", "Helm", "ngrok"], "alternates": {"html": "https://wpnews.pro/news/i-m-building-a-read-only-context-engine-for-kubernetes-and-ai-agents", "markdown": "https://wpnews.pro/news/i-m-building-a-read-only-context-engine-for-kubernetes-and-ai-agents.md", "text": "https://wpnews.pro/news/i-m-building-a-read-only-context-engine-for-kubernetes-and-ai-agents.txt", "jsonld": "https://wpnews.pro/news/i-m-building-a-read-only-context-engine-for-kubernetes-and-ai-agents.jsonld"}}