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 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 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 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 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 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
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 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 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` 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 <pod-name> --namespace default
kctx trace service <service-name> --namespace default
kctx graph pod <pod-name> --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
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 sharper.