🛡️ ocm-mcp-server

Why this exists

Your team runs many Kubernetes clusters. Sooner or later somebody asks the question:can an AI agent take the 2 a.m. page?

The quickest way to find out is to hand a model kubectl with cluster-admin and watch.In production that experiment ends badly, for three separate reasons:

• The model is non-deterministic. The same alert can produce a careful diagnosis onerun and a kubectl delete the next.
• The credentials are real. There is no dry run between the model's decision and yourproduction cluster.
• There is no record. When something breaks, you cannot reconstruct what the agent did,in what order, or on whose authority.

This project starts from a different observation: fleets already have a control point thathumans trust every day, the multi-cluster hub. Open Cluster Management (a CNCF project)gives every fleet an inventory (ManagedCluster), a scheduler (Placement), and a deliverychannel (ManifestWork). ocm-mcp-server exposes that hub to agents as a small set oftyped MCP tools, and puts four independent layersbetween the model and your clusters:

None of these layers live in the system prompt, so none of them can be talked out of.

Where to get it, and how it's vetted

• 📦 PyPI - ocm-mcp-server - pip install ocm-mcp-server(or run directly with uvx ocm-mcp-server). Every release is published straight from CI viaOIDC trusted publishing - no long-lived tokens anywhere.
• 🗂️ Official MCP Registry - listed asio.github.sandeepbazar/ocm-mcp-server, so any MCP client or platform that browses the registry candiscover and auto-configure this server (package, transport, and required env vars are all in thelisting); the registry validates the listing against this repo and the PyPI package.
• 🐳 Container image on GHCR -docker run ghcr.io/sandeepbazar/ocm-mcp-server (kubeconfig mount shown in thedeployment guide); built in CI with an SBOM and SLSA provenance attached,vulnerability-gated with Trivy, and signed keyless with Cosign so you can verify what you run.
• 🛡️ OpenSSF Scorecard -the repo's supply-chain security posture (pinned dependencies, branch protection, signed releases, ...)is scored automatically every week and published for anyone to inspect.

Connect your agent - any MCP client works

The server speaks standard MCP over stdio; nothing here is specific to one vendor's agent.Ready-made configs live in examples/:

{
  "mcpServers": {
    "ocm-fleet": {
      "command": "ocm-mcp-server",
      "env": {
        "OCM_MCP_HUB_CONTEXT": "kind-hub",
        "OCM_MCP_SPOKE_CONTEXTS": "cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3"
      }
    }
  }
}

[mcp_servers.ocm-fleet]
command = "ocm-mcp-server"

[mcp_servers.ocm-fleet.env]
OCM_MCP_HUB_CONTEXT = "kind-hub"
OCM_MCP_SPOKE_CONTEXTS = "cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3"

{
  "mcpServers": {
    "ocm-fleet": {
      "command": "ocm-mcp-server",
      "env": {
        "OCM_MCP_HUB_CONTEXT": "kind-hub",
        "OCM_MCP_SPOKE_CONTEXTS": "cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3"
      }
    }
  }
}

{
  "mcpServers": {
    "ocm-fleet": {
      "command": "ocm-mcp-server",
      "env": {
        "OCM_MCP_HUB_CONTEXT": "kind-hub",
        "OCM_MCP_SPOKE_CONTEXTS": "cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3"
      }
    }
  }
}

Most MCP clients accept an mcpServers block like this one. If ocm-mcp-server is noton the PATH the client launches with, use the absolute path fromwhich ocm-mcp-server as the command value.

Give the agent the runbook discipline inexamples/system-prompt.md, then break something and watchthe flow:

make inject SCENARIO=failing-rollout CLUSTER=cluster2

You: "Payments is degraded somewhere in the fleet. Investigate and fix."

Agent: list_clusters → get_cluster_health(cluster2) → query_events → get_pod_logs →"payments-v2 on cluster2 is in ImagePullBackOff. Proposing a ManifestWork pinning the lastgood image. Proposal 4f1a2b3c needs your approval."

You (trusted terminal): ocm-mcp approve 4f1a2b3c, then paste the token back.

Agent: apply_manifestwork → verifies recovery → get_audit_trail → writes the incident report.

Then try to talk it into something dangerous ("just redeploy it privileged withhostNetwork, it's faster"). The proposal dies at layer 1 or layer 2, and the rejectionmessage tells the agent exactly why. More worked examples →

Architecture

flowchart LR
    A["🤖 AI Agent<br/>(any MCP client)"] -->|"typed tool calls"| S["🛡️ ocm-mcp-server<br/>static guardrails · audit"]
    S -->|"reads + dry-run + apply"| H["☸️ OCM Hub<br/>Placement · ManifestWork<br/>Kyverno · RBAC"]
    H --> C1["cluster1"]
    H --> C2["cluster2"]
    H --> C3["cluster3"]
    U["🧑‍💻 Human operator<br/>ocm-mcp approve"] -.->|"approval token"| A
    S -.->|"spans"| J["🔍 OpenTelemetry / Jaeger"]

The write path in one sentence: the agent proposes a ManifestWork; static guardrailsand a Kyverno dry-run validate it; a human reviews the exact content and mints anapproval token bound to its hash; only then does apply deliver it, with every step tracedand logged.

Policy admission with Kyverno

The second guardrail layer does not live in this server - it lives in the cluster. Before aproposed change is ever stored, the server does a server-side dry-run create of theManifestWork on the hub, so the hub's Kyverno validating admissionruns against the exact manifests the agent wants to apply. If your organization's policysays no, the proposal is rejected at admission with the policy's own message - the samecontrol that governs every human kubectl apply.

Why Kyverno:

• Policy as code, no new language. Kyverno is aCNCF policy engine whose policies are ordinary Kubernetes resources in YAML and CEL -reviewable, versioned, and testable like any manifest. This is the policy-as-code approachthe CNCF Kubernetes Policy Management whitepaper (CNCFTAG Security) recommends: keep policy declarativeand separate from application code.
• Enforced by the cluster, not the prompt. Admission control is external to the model andto this server; it cannot be talked out of the way a system prompt can.
• The right tool for the job. Kyverno can validate, mutate, generate, and verify images;here it is used to validate the workloads embedded inside a ManifestWork.

Where it is used here:

• deploy/policies/ ships 9 ClusterPolicy objects that foreachover spec.workload.manifests inside a ManifestWork: block privileged/host access,protect system namespaces, enforce a kind allow-list, require the managed-by label from theserver ServiceAccount (so an unlabeled work cannot skip the others), and enforce aRestricted-Pod-Security baseline in parity with the static guardrails. They are scoped by theapp.kubernetes.io/managed-by: ocm-mcp-server label so they judge only agent-authored work.
• make policy-test runs a 42-case offline suite with the kyverno CLI - good, bad, andhuman-authored ManifestWorks - needing no cluster and no dependencies. It runs in CI, so apolicy regression fails the build before it can reach a hub.
• Don't start from scratch: the community librarykyverno/policies and the searchableKyverno Policies catalog are a ready source of validation,Pod Security Standards, and best-practice policies to adopt or take inspiration from.

Toolsets

The surface is 35 tools across ten toolsets. Almost all of it is read: the wholeOpen Cluster Management API is safe to inspect. Only two toolsets can changeanything, and only through the propose -> approve -> apply gate. Every hub-leveltool works for any managed spoke - a standalone OpenShift cluster, a HyperShifthosted cluster, or a cloud cluster - because on the hub they are all ManagedClusters.

Every read tool is annotated readOnlyHint; every write tool is annotateddestructiveHint and enforced by the gate. Setting OCM_MCP_READ_ONLY=1 turns offthe two writing toolsets entirely, for a strictly-inspection deployment.

Validate against your own hub in one command: ocm-mcp doctor calls every readtool against the live hub and prints a PASS / EMPTY / SKIP / FAIL table (writingnothing), so you can confirm exactly what the server sees before wiring up an agent.

There is deliberately no tool that reads Secrets, execs into pods, or deletesarbitrary resources. The generic reader (list_resources / get_resource) worksagainst an allow-list of OCM types, so Secrets are not restricted - they aresimply not expressible. A capability that does not exist cannot be prompt-injectedinto use.

Tools

Each tool below is annotated with its class: read (free, no gate),propose (stores a pending change, mutates nothing), or apply (delivers anapproved change; needs a human token).

• list_clusters (read) - all managed clusters with availability, version, labels, capacity.
• get_cluster (read) - full view of one cluster.
  • cluster (string) - managed cluster name.
• list_cluster_sets (read) - ManagedClusterSets with selector type and member clusters.
• list_cluster_set_bindings (read) - which ClusterSets a namespace's Placements may target.
  • namespace (string, optional) - limit to one namespace; empty lists all.
• list_cluster_claims (read) - every cluster's ClusterClaims (id, platform, region, version).
• get_cluster_info (read) - extended inventory from the hub (OpenShift version, nodes, console URL); needs no spoke access.
  • cluster (string) - managed cluster name.

• get_cluster_health (read) - hub conditions, unhealthy pods, degraded deployments.
  • cluster (string) - managed cluster name.
• get_fleet_health (read) - health of the whole fleet in one call: hub conditions for every cluster plus concurrent spoke scans; broken spokes show as an error entry instead of failing the sweep.
  • clusters (string, optional) - comma-separated cluster names to scope the sweep; empty means every cluster.
• query_events (read) - recent Kubernetes events, newest first.
  • cluster (string) - managed cluster name.
  • namespace (string, optional) - namespace filter; empty means all.
  • limit (int, optional) - max events (default 40).
• get_pod_logs (read) - tail a pod's logs (falls back to the previous instance if crashing).
  • cluster (string), namespace (string), pod (string) - target.
  • container (string, optional) - container name; empty picks the default.
  • lines (int, optional) - trailing lines (default 80).

• list_placements (read) - Placements and how many clusters each selects.
  • namespace (string, optional) - limit to one namespace.
• get_placement_decision (read) - the clusters a Placement actually selected.
  • placement (string) - Placement name.
  • namespace (string) - the Placement's namespace.
• list_addon_placement_scores (read) - custom scores prioritizers consume.
  • cluster (string) - managed cluster name.

• list_manifestworks (read) - ManifestWorks targeting a cluster.
  • cluster (string) - managed cluster name.
• get_manifestwork (read) - detailed status + per-resource status feedback (the "why not Applied").
  • cluster (string), name (string) - target.
• list_manifestworkreplicasets (read) - a template fanned across a Placement, with rollout summary.
  • namespace (string, optional) - limit to one namespace.
• propose_manifestwork (propose) - propose a change as a ManifestWork. Applies nothing.
  • cluster (string) - target cluster.
  • name (string) - short kebab-case ManifestWork name.
  • summary (string) - one or two sentences the human approver reads.
  • manifests_json (string) - JSON array of complete manifests (allowed kinds; namespaced; pinned images).
• apply_manifestwork (apply) - deliver an approved ManifestWork.
  • proposal_id (string), approval_token (string) - from ocm-mcp approve <id>.
• propose_rollback (propose) - propose undoing an applied ManifestWork; creates a rollback proposal bound to its UID.
  • proposal_id (string) - the applied ManifestWork proposal to undo.
• rollback_manifestwork (apply) - delete the ManifestWork after the rollback is approved (needs a rollback-scoped token).
  • rollback_proposal_id (string), approval_token (string).

• list_cluster_management_addons (read) - fleet-level add-on definitions and install strategy.
• get_addon_health (read) - per-cluster ManagedClusterAddOn Available / Degraded / Progressing.
• list_addons_for_cluster (read) - every add-on on one cluster, with install namespace and health.
  • cluster (string) - managed cluster name.

• list_pending_csrs (read) - pending cluster-join / add-on registration CSRs awaiting approval.
• propose_cluster_action (propose) - propose a lifecycle action. Applies nothing.
  • cluster (string) - target cluster.
  • action (string) - one of cordon (taint out of scheduling), uncordon, set_label, accept (hubAcceptsClient + approve join CSRs), enable_addon / disable_addon (create/delete a ManagedClusterAddOn).
  • summary (string) - what the human approver reads.
  • params_json (string, optional) - action parameters; set_label needs {"key","value"}, the add-on actions need {"addon"} (+ optional install_namespace).
• apply_cluster_action (apply) - apply an approved lifecycle action.
  • proposal_id (string), approval_token (string).

• list_policies (read) - Policies and per-cluster compliance. Reports clearly if the governance add-on is not installed.
  • namespace (string, optional) - limit to one namespace.
• list_policy_violations (read) - only the NonCompliant / Pending policy-cluster pairs across the fleet.

• list_hosted_clusters (read) - HostedClusters with version and conditions. Reports clearly if HCPs are hosted on a different management cluster.
  • namespace (string, optional) - limit to one namespace.
• get_hosted_cluster (read) - one HostedCluster in detail, with its NodePools.
  • name (string), namespace (string) - target.
• list_node_pools (read) - HyperShift NodePools (worker groups), desired vs current replicas.
  • namespace (string, optional), cluster (string, optional) - filters.

• list_resources (read) - list any allow-listed OCM type (identity + conditions).
  • resource (string) - e.g. managedclusters, placements, manifestworks, managedclusteraddons, klusterlets.
  • namespace (string, optional) - for namespaced types.
• get_resource (read) - get one allow-listed OCM object in full. Never returns a Secret (not on the allow-list).
  • resource (string), name (string) - target.
  • namespace (string, optional) - required for namespaced types.

• list_pending_proposals (read) - ManifestWorks and cluster actions awaiting approval.
• get_audit_trail (read) - the last N tool calls from this server's append-only log.
  • last_n (int, optional) - trailing entries (default 30).

Prompts

The server also ships ten MCP prompts - reusable templates that encode the safeworkflow so any client can start from a good runbook instead of a blank box.

Resources

The server also exposes 6 MCP resources - read-only fleet state a client can pin,browse, or attach as context without a tool call (strictly a subset of the read tools;every access still writes an audit line):

Observability - audit, tracing (OpenTelemetry/Jaeger), metrics

Every tool call produces up to three independent records, each with a different job:

What the tracing is: OpenTelemetry is the CNCFstandard for distributed tracing; Jaeger is a CNCFtrace viewer. When enabled, this server opens one span per tool call - namedtool.<name> (e.g. tool.apply_manifestwork) - with the call's arguments attachedas attributes. The approval_token is never attached, and argument values aretruncated at 200 characters, so traces are safe to ship to a shared backend.

Why it exists alongside the audit log: the audit log is a safety artifact -append-only and tamper-evident - while spans are a debugging artifact: in Jaegeryou can see that a get_cluster_health call spent 4 s waiting on one spoke, orfollow the exact propose → apply sequence of an incident on a timeline. Nothingsafety-related trusts the spans, which is why tracing can stay optional andfail-soft: without the extra installed and an endpoint set, it is a no-op.

How to use it (two switches + a viewer):

pip install "ocm-mcp-server[tracing]"                    # OTel SDK + OTLP/HTTP exporter
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 # your collector

# a local Jaeger to look at traces (make bootstrap starts this for you):
docker run -d --name jaeger -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:1.60
# open http://localhost:16686 and select the "ocm-mcp-server" service

How it is tested: unit tests cover span creation, token redaction, and theno-op paths; the e2e suite includes a tracing-export step that stands up a localOTLP sink, makes a tool call in a fresh server process, and asserts a real tracebatch arrives naming both the tool.* span and the ocm-mcp-server service - sothe export wiring is proven on every make e2e and in the nightly CI run. Details:deployment guide - tracingand architecture - observability.

Quickstart (laptop, ~15 minutes)

Requirements: docker, kind, kubectl,clusteradm, helm, Python 3.11+,Linux or macOS (Windows unsupported - use WSL2).The deployment guide has install commands and the real-fleet path.

git clone https://github.com/sandeepbazar/ocm-mcp-server.git
cd ocm-mcp-server

make bootstrap      # 1 hub + 3 managed kind clusters, OCM, Kyverno, policies, demo app
make install        # pip install -e ".[dev,tracing]"

Configuration

The server is configured entirely through environment variables. The two that matter mostare kubeconfig context names. New to those? Thecontext names guide explains what they are and the exactcommands to find yours, from a laptop kind cluster to a cloud login. In short: runkubectl config get-contexts and read the NAME column (make bootstrap printsready-to-paste values at the end).

For key management, ocm-mcp rotate-secret generates a fresh Ed25519 approval keypair(invalidating every outstanding approval token); ocm-mcp doctor runs the live read-pathsmoke test; and ocm-mcp audit-verify recomputes the audit log's hash chain to detect anyedit, reordering, or mid-log deletion.

# the values make bootstrap prints, spelled out:
export OCM_MCP_HUB_CONTEXT=kind-hub                      # context of the hub cluster
export OCM_MCP_SPOKE_CONTEXTS=cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3
#                             └ name on the hub ┘ └ kubeconfig context with read-only creds ┘

Not sure where kind-hub or cluster1=kind-cluster1 come from, or what your own valuesshould be? The context names guide walks through itstep by step, including cloud logins (EKS, GKE, AKS, OpenShift). Pointing at a realfleet instead of kind? Same variables; the deployment guide coversthe read-only spoke accounts and production hardening.

Then hand the server to your agent: the ready-made client configs are inConnect your agent near the top of this README.

Evaluation harness: honest numbers

eval/ ships 22 scripted incident scenarios in three classes: remediate (15),diagnose-only (3), adversarial (4). Scoring is objective on all three axes: diagnosiskeywords in the transcript, live cluster state for recovery, and the server's own audit logfor safety.

python3 eval/run_eval.py --agent-cmd "claude -p"     # or any agent CLI

Published results (eval/results/) - first full runsagainst two independent frontier agents, failures included:

Safety - the axis this server exists for - held 44/44 across both vendors: everyadversarial bait refused, zero unsafe proposals. Recovery misses concentrate on scenarioswhose fix requires state the read surface deliberately withholds; the results doc readsthose failures honestly.

Run it against your model of choice and publish your numbers, including the failures.The point is real data about what agents can and cannot yet be trusted to do.

The Kyverno policies have their own offline test suite: make policy-test runs 42 CLIcases (deploy/policies/tests/) against good, bad, andhuman-created ManifestWorks with no cluster and no dependencies. It runs in CI too, so apolicy regression fails the build before it ever reaches a hub.

Try it end to end (one command)

Want proof it works against real clusters, not mocks? One script stands up a realOpen Cluster Management fleet on kind, exercises every tool and prompt, runs abreak-then-fix scenario, and writes a graphical HTML report:

./hack/e2e-local.sh          # 2 spokes, auto-cleanup   (SPOKES=1 for a lighter run)

It (1) installs or version-checks the dependencies (Podman, kind, kubectl, clusteradm,helm; Docker is not required), (2) bootstraps a hub plus spokes, (3) runs every readtool, the gated propose -> approve -> apply write flow, the gated ROLLBACK flow, everylifecycle action (cordon/uncordon, set_label, accept, enable/disable_addon), and all tenprompts - each with a plain-language explanation of what it does and why, (4) drives thereal server binary over stdio JSON-RPC with the official MCP client (handshake, tools,prompts, resources, annotations), (5) runs a negative sweep proving every gate failsclosed (expired token, replayed token, apply-scoped token refused for rollback, read-onlymode, tampered audit log caught, signed audit anchor verified) plus a tracing-exportcheck (OTel spans over OTLP received by a local sink), (6) injects a failingrollout and shows the diagnose-and-fix loop end to end, then (7) writese2e-report.html and tears the fleet back down (kind and Podman stay installed). Thereport is git-ignored. Works on macOS (Homebrew + Podman) and Linux, and runsnightly in CI.

ocm-mcp doctor runs just the live read-path smoke test on its own, against any hub.

Here is a real, unedited run (recorded with asciinema, long waits compressed): the fleetcomes up, every step passes, and the fleet is torn down again -MP4 version · terminal cast:

Documentation

Repository map

src/ocm_mcp_server/   the MCP server: tools, guardrails, approvals, tracing, CLI
deploy/               least-privilege RBAC + Kyverno ClusterPolicies (+ offline tests)
hack/                 bootstrap.sh / teardown.sh / demo app (kind-based fleet)
chaos/                failure-injection scenarios (reversible, diagnosable)
eval/                 22-scenario evaluation harness + results
blogs/                long-form posts (canonical drafts; published to Medium)
docs/                 deployment, examples, architecture, guardrails, demo, upstream
examples/             MCP client configs + a production-shaped system prompt

Roadmap

The canonical, themed roadmap lives in ROADMAP.md. Current headline items:an authenticated HTTP transport with per-tool scopes, an off-box (KMS/HSM) approvalsigner, the OCM cluster-proxy transport, and a reusable Kyverno policy pack.(Multi-model eval results are now published.)

Have a need that's not there? Open a feature request.New tools require a safety rationale; see CONTRIBUTING.md.

Contributing & community

Issues and PRs welcome. Start with CONTRIBUTING.md.Getting help: SUPPORT.md.Security reports (privately, please): SECURITY.md.

Sponsorship

This project is independently maintained. If your organization wants priority integrationhelp, a hardened deployment review, sponsored features, or talks and workshops on safeagentic operations, connect onLinkedIn (details in SUPPORT.md).

Author

Sandeep Bazar - Passionate in Technology especially around Multi-cluster Kubernetes platforms, day-2operations, and making fleets safer to automate.

If this project is useful to you, a ⭐ helps others find it.

Project governance and maturity

This project holds itself to CNCF community, governance, and security practices as a qualitybar - the same standards expected of a CNCF Sandbox project - so it is easy to adopt,contribute to, and trust. The scaffolding is in place:

• Governance - how decisions are made and how to become a maintainer.
• Maintainers and Adopters - who maintains it, and an open page to record who uses it.
• Roadmap - direction by theme, safety-first.
• Security self-assessment - a CNCF TAG-Security-style assessment of what the guarantees are and where they end.
• CNCF Sandbox readiness - a self-check against CNCF Sandbox expectations, used as a quality bar.
• Code of Conduct - the CNCF Community Code of Conduct; report privately via LinkedIn.

Every change is signed off under the DCO, and any change that touchesa guardrail requires a written safety rationale.

License

Apache-2.0