ray-mcp¶
An MCP server for Ray on Kubernetes. Point Claude — or any MCP client — at your cluster and ask about your Ray workloads in plain language.
ray-mcp is built specifically for Ray, with the LLM as the consumer: it returns
distilled status (a one-line health read, not a wall of raw .status YAML),
keeps output token-bounded, and is read-only by default with a guarded,
opt-in write path.
Start here¶
- Install — get the binary and connect your agent.
- Try it with Claude Code — zero to a live cluster in ~20 min.
- Tool reference — all 19 tools, parameters, and examples.
- Safety tiers — how read / write / destructive are gated.
The tools at a glance¶
ray-mcp exposes 19 tools across three permission tiers:
- Read (always on) —
ray_capabilities, and the read tools for RayClusters, RayJobs (the cross-plane "wedge" — CRD status fused with the live Ray dashboard), and RayServices. - Write (
--allow-mutations) — create / update / scale clusters, submit / delete jobs, deploy / update services — all through a Server-Side Apply pipeline with dry-run and before/after diffs. - Destructive (
--allow-destructive) — delete a cluster or service, behind a two-step confirm-fingerprint flow and theray-mcp/protectedannotation guard.
See the Tool reference for the full, always-in-sync list.
Transports¶
- stdio (default) — your agent launches ray-mcp as a subprocess. See Install.
- HTTP — a streamable HTTP listener with bearer-token or Kubernetes TokenReview auth. See HTTP transport & auth.
Learn more¶
- Configuration reference — every flag and environment variable.
- Architecture — layers, ports, and data flows.
- Design specs — the authoritative design and decision log.
- Contributing — the test pyramid and the "adding a tool" checklist.