Skip to content

Configuration reference

ray-mcp is configured entirely by command-line flags and environment variables — there is no config file. Precedence is flags > environment > defaults.

The authoritative specification is design spec §9 Configuration; this page mirrors it for quick reference.

Flag Env Default Purpose
--transport RAY_MCP_TRANSPORT stdio stdio or http — see HTTP transport & auth
--context RAY_MCP_CONTEXT current context kubeconfig context to bind
--kubeconfig KUBECONFIG discovery / in-cluster credentials source
--default-namespace RAY_MCP_NAMESPACE pod's namespace in-cluster, else default namespace used when a tool omits one
--allow-all-namespaces RAY_MCP_ALL_NS false serve every namespace (reconciled against RBAC at boot)
--ray-access RAY_MCP_RAY_ACCESS auto how the wedge reaches the Ray dashboard: auto / direct / port-forward
--allow-mutations RAY_MCP_ALLOW_MUTATIONS false register the write tools
--allow-destructive RAY_MCP_ALLOW_DESTRUCTIVE false register the destructive (delete) tools — also needs --allow-mutations
--allow-raw-spec RAY_MCP_ALLOW_RAW_SPEC true expose the rawSpec escape hatch on write tools
--log-level RAY_MCP_LOG_LEVEL info debug / info / warn / error (logs go to stderr)
--http-addr RAY_MCP_HTTP_ADDR 127.0.0.1:8765 listener address (http transport only)
--auth-mode RAY_MCP_AUTH_MODE static static or tokenreview (http transport only)
--auth-token RAY_MCP_AUTH_TOKEN (none) accepted bearer token in static mode
--ray-dashboard-auth RAY_MCP_RAY_DASH_AUTH (none) token/header passed to a dashboard auth proxy

Notable behaviors

  • Read-only by default. The write and destructive tiers are opt-in — see Safety tiers.
  • --allow-all-namespaces is reconciled against RBAC at boot. The server runs a SelfSubjectAccessReview for cluster-wide list on the three Ray CRDs. If the ServiceAccount is not authorized cluster-wide it refuses to start; if the cluster can't be reached it downgrades to namespaced scope. ray_capabilities reports the reconciled truth.
  • Non-loopback HTTP binds require auth. Binding a routable --http-addr without a token (or tokenreview mode) makes the process refuse to boot. There is no --insecure escape hatch — see HTTP transport & auth.
  • The server always boots without a reachable cluster. ray_capabilities is config-only; cluster-touching tools dial lazily on first use.