Write tools

Require --allow-mutations. These tools create or modify RayCluster / RayJob / RayService resources through the server-side-apply pipeline.

ray_cluster_create

Create a RayCluster from curated params (rayVersion, image, head/worker resources, worker groups, autoscaling) with an optional rawSpec escape hatch merged over them. Always server-side validated first; pass dryRun=true to validate without creating. Returns the field-level diff of your intent vs the server's view (server defaults surface here). Requires --allow-mutations.

Tier: write

Input parameters

Name	Type	Required	Description
annotations	object		annotations to set on the RayCluster
dryRun	boolean		validate against the live CRD schema (server-side dry-run) without creating anything
enableAutoscaling	boolean		enable the Ray in-tree autoscaler (honors per-group min/max)
headResources	object		resource quantities for the head node
image	string		the Ray container image for head and workers
labels	object		labels to set on the RayCluster
name	string	yes	the RayCluster name (required)
namespace	string		target namespace; defaults to the server default namespace
rawSpec	object		power-user escape hatch: a partial RayCluster object merged OVER the curated params (rawSpec wins, arrays replace wholesale). Removed from this schema when --allow-raw-spec=false
rayVersion	string		the Ray version, e.g. "2.9.0"
workerGroups	array		the worker groups to create

Output fields

Name	Type	Required	Description
diff	array	yes	the field-level diff of the submitted intent vs the server's view (server defaults surface here)
dryRun	boolean	yes	true if nothing was persisted (a server-side validation only)
fieldCount	integer	yes	the number of fields the server set or changed relative to the submitted intent
name	string	yes
namespace	string	yes

Example

Request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "ray-demo",
      "namespace": "ray-system"
    },
    "name": "ray_cluster_create"
  }
}

Response (synthesized from the schema; values are illustrative):

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "diff": [
        {
          "fieldCount": 1,
          "kind": "example",
          "path": "example"
        }
      ],
      "dryRun": false,
      "fieldCount": 1,
      "name": "ray-demo",
      "namespace": "ray-system"
    }
  }
}

---

ray_cluster_scale

Scale a RayCluster worker group: set minReplicas/maxReplicas (autoscaler bounds) and/or replicas (desired count). On an autoscaling cluster, replicas is refused (set min/max instead). Scaling replicas to 0 tears down the group's workers and requires --allow-destructive. Server-side validated first; pass dryRun=true to preview. Returns the field-level diff. Requires --allow-mutations.

Tier: write (destructive, idempotent)

Input parameters

Name	Type	Required	Description
dryRun	boolean		validate against the live CRD schema (server-side dry-run) without changing anything
maxReplicas	integer		autoscaler ceiling for this group (must be >= minReplicas)
minReplicas	integer		autoscaler floor for this group
name	string	yes	the RayCluster name (required)
namespace	string		namespace of the RayCluster; defaults to the server default namespace
replicas	integer		desired worker count. Refused on an autoscaling cluster (set min/max instead). Setting 0 tears down the group's workers and requires --allow-destructive
workerGroup	string	yes	the worker group to scale (required; must already exist)

Output fields

Name	Type	Required	Description
diff	array	yes	the field-level diff of the submitted intent vs the server's view
dryRun	boolean	yes	true if nothing was persisted (a server-side validation only)
fieldCount	integer	yes	the number of fields the server set or changed relative to the submitted intent
name	string	yes
namespace	string	yes

Example

Request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "ray-demo",
      "namespace": "ray-system",
      "workerGroup": "small-workers"
    },
    "name": "ray_cluster_scale"
  }
}

Response (synthesized from the schema; values are illustrative):

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "diff": [
        {
          "fieldCount": 1,
          "kind": "example",
          "path": "example"
        }
      ],
      "dryRun": false,
      "fieldCount": 1,
      "name": "ray-demo",
      "namespace": "ray-system"
    }
  }
}

---

ray_cluster_update

Update an existing RayCluster's image, rayVersion, autoscaling toggle, or labels/annotations via Server-Side Apply (read-modify-apply of the live object, so unrelated fields are preserved). Optional rawSpec is merged over the live object. Always server-side validated first; pass dryRun=true to validate without changing anything. Returns the field-level diff. Requires --allow-mutations.

Tier: write (idempotent)

Input parameters

Name	Type	Required	Description
annotations	object		annotations to set/merge on the RayCluster
dryRun	boolean		validate against the live CRD schema (server-side dry-run) without changing anything
enableAutoscaling	boolean		toggle the Ray in-tree autoscaler; omit to leave unchanged. Enabling it makes ray-mcp stop managing worker replicas (the autoscaler owns them)
image	string		new container image for the head and all worker groups (Ray container only); omit to leave unchanged
labels	object		labels to set/merge on the RayCluster
name	string	yes	the RayCluster name (required)
namespace	string		namespace of the RayCluster; defaults to the server default namespace
rawSpec	object		power-user escape hatch: a partial RayCluster object merged OVER the live object (rawSpec wins, arrays replace wholesale). Removed from this schema when --allow-raw-spec=false
rayVersion	string		new spec.rayVersion; omit to leave unchanged

Output fields

Name	Type	Required	Description
diff	array	yes	the field-level diff of the submitted intent vs the server's view
dryRun	boolean	yes	true if nothing was persisted (a server-side validation only)
fieldCount	integer	yes	the number of fields the server set or changed relative to the submitted intent
name	string	yes
namespace	string	yes

Example

Request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "ray-demo",
      "namespace": "ray-system"
    },
    "name": "ray_cluster_update"
  }
}

Response (synthesized from the schema; values are illustrative):

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "diff": [
        {
          "fieldCount": 1,
          "kind": "example",
          "path": "example"
        }
      ],
      "dryRun": false,
      "fieldCount": 1,
      "name": "ray-demo",
      "namespace": "ray-system"
    }
  }
}

---

ray_job_delete

Delete a RayJob. An existing-cluster job (clusterSelector) deletes immediately as a plain write (the targeted cluster is untouched). An ephemeral job (clusterSpec) owns its RayCluster, so deleting it cascades to that cluster and every actor/job on it: that is a two-step confirmed deletion (call WITHOUT confirm to preview and receive a fingerprint, then re-call with confirm=) and requires --allow-destructive. Honors the ray-mcp/protected annotation (refuses). Pass dryRun=true to validate without deleting. Requires --allow-mutations.

Tier: write (destructive, idempotent)

Input parameters

Name	Type	Required	Description
confirm	string		confirmation fingerprint from a prior preview (empty call); echo it back to commit an ephemeral-cluster deletion
dryRun	boolean		validate the deletion server-side without removing anything
name	string	yes	the RayJob name (required)
namespace	string		namespace of the RayJob; defaults to the server default namespace

Output fields

Name	Type	Required	Description
confirm	string		echo this fingerprint back to commit an ephemeral-cluster deletion (preview only)
dryRun	boolean		true if nothing was deleted (a server-side validation only)
message	string		human-readable explanation of the preview or result
name	string	yes
namespace	string	yes

Example

Request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "ray-demo",
      "namespace": "ray-system"
    },
    "name": "ray_job_delete"
  }
}

Response (synthesized from the schema; values are illustrative):

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "confirm": "example",
      "dryRun": false,
      "message": "example",
      "name": "ray-demo",
      "namespace": "ray-system"
    }
  }
}

---

ray_job_submit

Submit a RayJob (non-blocking) against EXACTLY ONE cluster target: existingCluster (run on a running RayCluster) XOR clusterSpec (create an ephemeral cluster for the job, torn down on finish by default — pass shutdownAfterJobFinishes=false to keep it). Supplying both or neither is an error. Always server-side validated first; pass dryRun=true to validate without submitting. Returns immediately with the field-level diff and the just-submitted status (jobId/deploymentStatus are usually empty until the controller reconciles — follow with ray_job_get/ray_job_wait). Requires --allow-mutations.

Tier: write

Input parameters

Name	Type	Required	Description
clusterSpec	object		create an ephemeral cluster for this job (mode B); mutually exclusive with existingCluster
dryRun	boolean		validate against the live CRD schema (server-side dry-run) without submitting anything
entrypoint	string	yes	the shell command the Ray job runs, e.g. "python main.py" (required)
existingCluster	string		run against an already-running RayCluster by name (mode A); mutually exclusive with clusterSpec
metadata	object		arbitrary job metadata passed to Ray
name	string	yes	the RayJob name (required)
namespace	string		target namespace; defaults to the server default namespace
rawSpec	object		power-user escape hatch: a partial RayJob object merged OVER the curated params (rawSpec wins, arrays replace wholesale). Removed from this schema when --allow-raw-spec=false
runtimeEnvYAML	string		the Ray runtime environment as a YAML document (pip, env_vars, working_dir, ...)
shutdownAfterJobFinishes	boolean		ephemeral mode only: tear down the cluster when the job finishes (default true; pass false to keep it for debugging). Rejected with existingCluster

Output fields

Name	Type	Required	Description
deploymentStatus	string	yes	the CRD lifecycle phase (status.jobDeploymentStatus); empty means New (not yet reconciled)
diff	array	yes	the field-level diff of the submitted intent vs the server's view (server defaults surface here)
dryRun	boolean	yes	true if nothing was persisted (a server-side validation only)
ephemeral	boolean	yes	true if this submitted an ephemeral-cluster job (clusterSpec mode)
fieldCount	integer	yes	the number of fields the server set or changed relative to the submitted intent
jobId	string		the Ray submission id (status.jobId); usually empty right after submit, before the controller reconciles
name	string	yes
namespace	string	yes

Example

Request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "entrypoint": "python -c \"import ray; ray.init()\"",
      "name": "ray-demo",
      "namespace": "ray-system"
    },
    "name": "ray_job_submit"
  }
}

Response (synthesized from the schema; values are illustrative):

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "deploymentStatus": "example",
      "diff": [
        {
          "fieldCount": 1,
          "kind": "example",
          "path": "example"
        }
      ],
      "dryRun": false,
      "ephemeral": false,
      "fieldCount": 1,
      "jobId": "example",
      "name": "ray-demo",
      "namespace": "ray-system"
    }
  }
}

---

ray_service_deploy

Deploy a RayService from curated params (serveConfigV2, rayVersion, image, head/worker resources, worker groups, autoscaling) with an optional rawSpec escape hatch merged over them. The embedded cluster config uses the rayClusterConfig key. Always server-side validated first; pass dryRun=true to validate without deploying. Returns the field-level diff. Requires --allow-mutations.

Tier: write

Input parameters

Name	Type	Required	Description
annotations	object		annotations to set on the RayService
dryRun	boolean		validate against the live CRD schema (server-side dry-run) without deploying anything
enableAutoscaling	boolean		enable the Ray in-tree autoscaler
headResources	object		resource quantities for the head node
image	string		the Ray container image for head and workers
labels	object		labels to set on the RayService
name	string	yes	the RayService name (required)
namespace	string		target namespace; defaults to the server default namespace
rawSpec	object		power-user escape hatch: a partial RayService object merged OVER the curated params (rawSpec wins, arrays replace wholesale). Removed from this schema when --allow-raw-spec=false
rayVersion	string		the Ray version for the embedded cluster, e.g. "2.9.0"
serveConfigV2	string		the Serve config (YAML/JSON string); optional — the RayService can start without it
workerGroups	array		the worker groups for the embedded cluster

Output fields

Name	Type	Required	Description
diff	array	yes	the field-level diff of the submitted intent vs the server's view
dryRun	boolean	yes	true if nothing was persisted (a server-side validation only)
fieldCount	integer	yes	the number of fields the server set or changed relative to the submitted intent
name	string	yes
namespace	string	yes

Example

Request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "ray-demo",
      "namespace": "ray-system"
    },
    "name": "ray_service_deploy"
  }
}

Response (synthesized from the schema; values are illustrative):

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "diff": [
        {
          "fieldCount": 1,
          "kind": "example",
          "path": "example"
        }
      ],
      "dryRun": false,
      "fieldCount": 1,
      "name": "ray-demo",
      "namespace": "ray-system"
    }
  }
}

---

ray_service_update

Update an existing RayService's serveConfigV2, image, rayVersion, autoscaling, or labels/annotations via Server-Side Apply (read-modify-apply of the live object). Reports the PREDICTED operator path: an in-place serve reconfig, a zero-downtime cluster swap, or a replicas-only scale. Optional rawSpec is merged over the live object. Always server-side validated first; pass dryRun=true to validate without changing anything. Returns the field-level diff and the predicted path. Requires --allow-mutations.

Tier: write (idempotent)

Input parameters

Name	Type	Required	Description
annotations	object		annotations to set/merge on the RayService
dryRun	boolean		validate against the live CRD schema (server-side dry-run) without changing anything
enableAutoscaling	boolean		toggle the Ray in-tree autoscaler in the embedded cluster; omit to leave unchanged
image	string		new container image for the head and all worker groups; omit to leave unchanged
labels	object		labels to set/merge on the RayService
name	string	yes	the RayService name (required)
namespace	string		namespace of the RayService; defaults to the server default namespace
rawSpec	object		power-user escape hatch: a partial RayService object merged OVER the live object (rawSpec wins, arrays replace wholesale). Removed from this schema when --allow-raw-spec=false
rayVersion	string		new rayClusterConfig.rayVersion; omit to leave unchanged
serveConfigV2	string		new Serve config (YAML/JSON string); omit to leave unchanged

Output fields

Name	Type	Required	Description
diff	array	yes	the field-level diff of the submitted intent vs the server's view
dryRun	boolean	yes	true if nothing was persisted (a server-side validation only)
fieldCount	integer	yes	the number of fields the server set or changed relative to the submitted intent
name	string	yes
namespace	string	yes
predictedPath	string	yes	the predicted operator behavior: in-place, zero-downtime-swap, or scale (no swap)

Example

Request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "ray-demo",
      "namespace": "ray-system"
    },
    "name": "ray_service_update"
  }
}

Response (synthesized from the schema; values are illustrative):

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "diff": [
        {
          "fieldCount": 1,
          "kind": "example",
          "path": "example"
        }
      ],
      "dryRun": false,
      "fieldCount": 1,
      "name": "ray-demo",
      "namespace": "ray-system",
      "predictedPath": "example"
    }
  }
}

---