# I'm building a read-only context engine for Kubernetes and AI agents > Source: > Published: 2026-06-15 08:03:09+00:00 Kubernetes gives us an incredibly powerful API. It also gives us a familiar debugging ritual: ``` kubectl get pods kubectl describe pod ... kubectl get svc ... kubectl get endpointslices ... kubectl get deployment ... kubectl get events ... kubectl get application.argoproj.io ... ``` Then we mentally stitch the result together. Which 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? Which facts should I paste into an incident, attach to a CI failure, or give to an AI assistant before asking it to reason? I 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. Just structured Kubernetes context. [ kctx](https://github.com/lucasepe/kctx) is a read-only Kubernetes context engine for humans, scripts, and AI agents. It turns live Kubernetes API state into a compact model of: The design goal is intentionally conservative: read cluster state, normalize facts, avoid speculative root-cause claims. That boundary matters. I 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. Most Kubernetes tools are optimized for one of a few jobs: `kubectl` exposes the raw API very wellThose are all useful. I use them too. But 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." For example, when looking at a Service, I often care less about the complete YAML and more about questions like: That is the kind of context [ kctx](https://github.com/lucasepe/kctx) tries to assemble. ``` kctx trace service payments-api --namespace payments ``` For a namespace-level view: ``` kctx health namespace payments ``` For a focused resource view: ``` kctx explain pod api-xyz --namespace payments ``` And when you need a deterministic JSON snapshot for automation or incident review: ``` kctx dump namespace payments > payments-dump.json ``` [ kctx](https://github.com/lucasepe/kctx) does not mutate Kubernetes resources. It does not: That 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. This becomes even more important when AI agents enter the picture. If 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. One of the areas I am experimenting with is exposing `kctx` through the Model Context Protocol. Current serve modes include: ``` kctx serve --mode mcp kctx serve --mode mcp-sse ``` The MCP tools currently cover the same core context operations: `get_namespace_health` `explain_resource` `trace_service` `get_pod_graph` `dump_namespace` The idea is simple: let an AI assistant ask for Kubernetes context without giving it mutation capabilities. Just compact operational facts that can be used as evidence. There 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: [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) Important 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. Another design choice: [ kctx](https://github.com/lucasepe/kctx) does not pretend that every custom resource can be understood generically. Kubernetes discovery can tell you that a CRD exists. It cannot tell you what that CRD means operationally. So [ 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. The current adapter set includes: `Application` `AppProject` `Certificate` That 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. The CLI and HTTP API emit versioned JSON by default. Responses include a schema version and kind, for example: ``` { "schemaVersion": "kctx.io/v1alpha1", "kind": "NamespaceHealth" } ``` The repository includes machine-readable JSON schemas under: ``` schemas/kctx.io/v1alpha1 ``` That part may sound less exciting than graphs or agents, but it is one of the pieces I care about most. If 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. [ kctx](https://github.com/lucasepe/kctx)` is designed to provide operational context, not sensitive data. It avoids returning raw manifests, Secret data, ConfigMap data, raw environment variables, logs, and workload metrics. Supported outputs also pass metadata and Kubernetes messages through a small redaction policy for common secret-bearing keys and text patterns. This is not a magic privacy shield, but it is an intentional boundary in the design. Install: `bash` curl -fsSL https://raw.githubusercontent.com/lucasepe/kctx/main/install.sh | bash Run against your current Kubernetes context: `bash` kctx health namespace default kctx explain pod --namespace default kctx trace service --namespace default kctx graph pod --namespace default --render mermaid kctx dump namespace default Or run the read-only HTTP server: `bash` kctx serve curl http://localhost:8080/health/namespace/default Or install the in-cluster server with Helm: `bash` VERSION=0.3.0 helm upgrade --install kctx \ "https://github.com/lucasepe/kctx/releases/download/v${VERSION}/kctx-${VERSION}.tgz" \ --namespace kctx-system \ --create-namespace Then: `bash` kubectl -n kctx-system port-forward svc/kctx 8080:8080 curl http://localhost:8080/health/namespace/default The 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. I would love feedback from SREs, platform engineers, Kubernetes operators, and people experimenting with AI-assisted operations. In particular: If you try the MCP/SSE path, I am especially interested in: GitHub: [https://github.com/lucasepe/kctx](https://github.com/lucasepe/kctx) If this idea resonates with you, a star would help the project reach more Kubernetes and platform people. But 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. That is the kind of feedback that can make [ kctx](https://github.com/lucasepe/kctx) sharper.