Read tools

Always available. These tools only read cluster state and the Ray dashboard; they never mutate anything.

ray_capabilities

Report ray-mcp server version, bound kubeconfig context, default namespace, enabled tool tiers, and the CI-tested KubeRay version range. Read-only; makes no live Kubernetes call.

Tier: read

Input parameters

None.

Output fields

Name	Type	Required	Description
allNamespaces	boolean	yes	true when the server serves all namespaces (verified cluster-wide access); false in namespaced mode
defaultNamespace	string	yes	the namespace used when a tool omits one
enabledTiers	array	yes	the enabled tool tiers (read, write, destructive)
fieldValidation	object	yes	how create/update inputs are validated, and the curated field set per CRD
kubeContext	string	yes	the bound kubeconfig context name
kubeRayTested	string	yes	the CI-tested KubeRay version range
servedNamespaces	array		the namespaces served in namespaced mode; empty in cluster mode (all namespaces)
serverVersion	string	yes	the ray-mcp server version

Example

Request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "ray_capabilities"
  }
}

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "allNamespaces": false,
      "defaultNamespace": "example",
      "enabledTiers": [
        "example"
      ],
      "fieldValidation": {
        "curatedFields": {},
        "mode": "example",
        "pruningDetection": false
      },
      "kubeContext": "example",
      "kubeRayTested": "example",
      "servedNamespaces": [
        "example"
      ],
      "serverVersion": "example"
    }
  }
}

---

ray_cluster_events

Recent, bounded Kubernetes events for a RayCluster — operator/reconcile events on the cluster object merged with scheduler/kubelet events on its pods (FailedScheduling, ErrImagePull, OOMKilled, ...), Warnings first then most recent. A relevant slice, never the raw event firehose. Read-only.

Tier: read (read-only)

Input parameters

Name	Type	Required	Description
limit	integer		max events to return; 0 uses the server default (~25). Warnings are prioritized over Normal events when trimming
name	string	yes	the RayCluster name (required)
namespace	string		namespace of the RayCluster; defaults to the server default namespace

Output fields

Name	Type	Required	Description
count	integer	yes	the number of events returned (after bounding)
events	array	yes	recent, bounded events for the cluster + its pods, Warnings first then most recent
warnings	integer	yes	how many of the returned events are Warnings

Example

Request:

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

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "count": 1,
      "events": [
        {
          "ageSeconds": 1,
          "count": 1,
          "message": "example",
          "reason": "example",
          "type": "example"
        }
      ],
      "warnings": 1
    }
  }
}

---

ray_cluster_get

Get one RayCluster's distilled status (phase, ready/desired workers, age, health, head service, dashboard URL). Pass verbose=true for the full unstructured object. Read-only.

Tier: read (read-only)

Input parameters

Name	Type	Required	Description
name	string	yes	the RayCluster name (required)
namespace	string		namespace of the RayCluster; defaults to the server default namespace
verbose	boolean		include the full unstructured object under raw; default is the distilled view

Output fields

Name	Type	Required	Description
ageSeconds	integer	yes
dashboardURL	string
desired	integer	yes
headServiceName	string
health	string	yes
name	string	yes
namespace	string	yes
phase	string	yes
raw	object		the full unstructured object; present only when verbose=true
ready	integer	yes

Example

Request:

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

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "ageSeconds": 1,
      "dashboardURL": "example",
      "desired": 1,
      "headServiceName": "example",
      "health": "example",
      "name": "ray-demo",
      "namespace": "ray-system",
      "phase": "example",
      "raw": {},
      "ready": 1
    }
  }
}

---

ray_cluster_list

List RayClusters as compact rows (name, namespace, phase, ready/desired workers, age, 1-line health), capped and paginated via an opaque continue token. Read-only.

Tier: read (read-only)

Input parameters

Name	Type	Required	Description
allNamespaces	boolean		list across all namespaces instead of one
continue	string		opaque continue token from a prior page; omit for the first page
limit	integer		max rows per page; 0 uses the server default (~50)
namespace	string		namespace to list RayClusters in; defaults to the server default namespace

Output fields

Name	Type	Required	Description
clusters	array	yes	the compact cluster rows for this page
continue	string		the continue token for the next page; empty when exhausted
count	integer	yes	the number of rows shown on this page
moreAvailable	boolean	yes	true if more pages exist; pass continue for the next page

Example

Request:

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

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "clusters": [
        {
          "ageSeconds": 1,
          "desired": 1,
          "health": "example",
          "name": "ray-demo",
          "namespace": "ray-system",
          "phase": "example",
          "ready": 1
        }
      ],
      "continue": "example",
      "count": 1,
      "moreAvailable": false
    }
  }
}

---

ray_job_get

Get a RayJob's distilled, cross-plane status: the KubeRay CRD lifecycle fused with the LIVE Ray job status dialed from the dashboard once the job is scheduled. Before scheduling it reports 'not yet scheduled' (never a connection error). Pass verbose=true for the full unstructured object. Read-only.

Tier: read (read-only)

Input parameters

Name	Type	Required	Description
name	string	yes	the RayJob name (required)
namespace	string		namespace of the RayJob; defaults to the server default namespace
verbose	boolean		include the full unstructured object under raw; default is the distilled view

Output fields

Name	Type	Required	Description
ageSeconds	integer	yes
dashboardURL	string
degradeReason	string		when degraded, the bounded reason the live Ray detail was unavailable
degraded	boolean	yes	true when the job is scheduled but the live Ray dashboard was unreachable, so this is the CRD-derived view only (live jobStatus/message/timestamps absent)
deploymentStatus	string	yes	the CRD lifecycle phase (status.jobDeploymentStatus): Initializing/Running/Complete/Failed/...
endedAtUnix	integer		job end time (epoch seconds) from the live dashboard status; omitted when not ended
health	string	yes	1-line distilled health summary
jobId	string		the Ray submission id (status.jobId); empty before scheduling
jobStatus	string		the Ray driver phase: live from the dashboard when scheduled, else the CRD's cached status.jobStatus
message	string		a bounded status/failure message when present
name	string	yes
namespace	string	yes
raw	object		the full unstructured object; present only when verbose=true
rayClusterName	string		the RayCluster backing this job (status.rayClusterName)
scheduled	boolean	yes	true once status.jobId+dashboardURL are set; false means not yet scheduled
startedAtUnix	integer		job start time (epoch seconds) from the live dashboard status; omitted when not started

Example

Request:

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

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "ageSeconds": 1,
      "dashboardURL": "example",
      "degradeReason": "example",
      "degraded": false,
      "deploymentStatus": "example",
      "endedAtUnix": 1,
      "health": "example",
      "jobId": "example",
      "jobStatus": "example",
      "message": "example",
      "name": "ray-demo",
      "namespace": "ray-system",
      "raw": {},
      "rayClusterName": "example",
      "scheduled": false,
      "startedAtUnix": 1
    }
  }
}

---

ray_job_list

List RayJobs as compact rows (name, namespace, deployment status, Ray job status, age, 1-line health), capped and paginated via an opaque continue token. Each row shows BOTH the CRD lifecycle (deploymentStatus) and the Ray driver phase (jobStatus). Read-only.

Tier: read (read-only)

Input parameters

Name	Type	Required	Description
allNamespaces	boolean		list across all namespaces instead of one
continue	string		opaque continue token from a prior page; omit for the first page
limit	integer		max rows per page; 0 uses the server default (~50)
namespace	string		namespace to list RayJobs in; defaults to the server default namespace

Output fields

Name	Type	Required	Description
continue	string		the continue token for the next page; empty when exhausted
count	integer	yes	the number of rows shown on this page
jobs	array	yes	the compact RayJob rows for this page
moreAvailable	boolean	yes	true if more pages exist; pass continue for the next page

Example

Request:

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

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "continue": "example",
      "count": 1,
      "jobs": [
        {
          "ageSeconds": 1,
          "deploymentStatus": "example",
          "health": "example",
          "jobStatus": "example",
          "name": "ray-demo",
          "namespace": "ray-system"
        }
      ],
      "moreAvailable": false
    }
  }
}

---

ray_job_logs

Fetch a bounded tail of a RayJob's driver logs from the Ray dashboard (most recent output, line- and byte-capped — never the full buffer). Returns scheduled=false with no logs when the job has not been scheduled yet. Read-only.

Tier: read (read-only)

Input parameters

Name	Type	Required	Description
maxBytes	integer		hard byte ceiling on the returned tail; 0 uses the server default (~16KB)
name	string	yes	the RayJob name (required)
namespace	string		namespace of the RayJob; defaults to the server default namespace
tailLines	integer		keep only the last N lines; 0 uses the server default (~200)

Output fields

Name	Type	Required	Description
bytesOmitted	integer		a floor on how many bytes of the full buffer were dropped
degradeReason	string		when degraded, the bounded reason the logs were unavailable
degraded	boolean	yes	true when the job is scheduled but the Ray dashboard was unreachable, so no logs could be fetched (not an error)
logs	string	yes	the bounded log tail (most recent output)
name	string	yes
namespace	string	yes
scheduled	boolean	yes	false means the job is not yet scheduled, so no logs exist yet
truncated	boolean	yes	true if the line/byte ceiling clipped earlier output

Example

Request:

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

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "bytesOmitted": 1,
      "degradeReason": "example",
      "degraded": false,
      "logs": "example",
      "name": "ray-demo",
      "namespace": "ray-system",
      "scheduled": false,
      "truncated": false
    }
  }
}

---

ray_job_wait

Wait (bounded, ≤30s) for a RayJob to reach a condition: 'running' (default — started executing, or already finished) answers 'did it start or is it stuck Pending?'; 'terminal' waits for succeeded/failed/stopped. Returns the current distilled status plus a 'reached' flag — reached=false means not yet (re-poll), never an error. Read-only.

Tier: read (read-only)

Input parameters

Name	Type	Required	Description
name	string	yes	the RayJob name (required)
namespace	string		namespace of the RayJob; defaults to the server default namespace
until	string		the condition to wait for: 'running' (default — started or already finished) or 'terminal' (succeeded/failed/stopped)
waitSeconds	integer		max seconds to wait, clamped to 30; the call returns promptly with reached=false if the condition is not met in time

Output fields

Name	Type	Required	Description
degradeReason	string		when degraded, the bounded reason the live Ray detail was unavailable
degraded	boolean	yes	true when the job is scheduled but the live Ray dashboard was unreachable on the final poll, so this is the CRD-derived view only
deploymentStatus	string	yes	the CRD lifecycle phase (status.jobDeploymentStatus)
health	string	yes	1-line distilled health summary
jobId	string		the Ray submission id (status.jobId); empty before scheduling
jobStatus	string		the Ray driver phase: live from the dashboard when scheduled+reachable, else the CRD's cached status.jobStatus
message	string		a bounded status/failure message when present
name	string	yes
namespace	string	yes
rayClusterName	string		the RayCluster backing this job (status.rayClusterName)
reached	boolean	yes	true if the job reached the requested condition within waitSeconds; false means not yet (re-poll), not an error
scheduled	boolean	yes	true once status.jobId+dashboardURL are set; false means not yet scheduled
until	string	yes	the condition waited for: running or terminal

Example

Request:

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

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "degradeReason": "example",
      "degraded": false,
      "deploymentStatus": "example",
      "health": "example",
      "jobId": "example",
      "jobStatus": "example",
      "message": "example",
      "name": "ray-demo",
      "namespace": "ray-system",
      "rayClusterName": "example",
      "reached": false,
      "scheduled": false,
      "until": "example"
    }
  }
}

---

ray_service_get

Get one RayService's distilled status (serve status, healthy serve endpoints, rollout phase, age, health). Pass verbose=true for the full unstructured object. Read-only.

Tier: read (read-only)

Input parameters

Name	Type	Required	Description
name	string	yes	the RayService name (required)
namespace	string		namespace of the RayService; defaults to the server default namespace
verbose	boolean		include the full unstructured object under raw; default is the distilled view

Output fields

Name	Type	Required	Description
ageSeconds	integer	yes
health	string	yes
healthyReplicas	integer	yes
name	string	yes
namespace	string	yes
raw	object		the full unstructured object; present only when verbose=true
rolloutPhase	string	yes
serviceStatus	string	yes

Example

Request:

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

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "ageSeconds": 1,
      "health": "example",
      "healthyReplicas": 1,
      "name": "ray-demo",
      "namespace": "ray-system",
      "raw": {},
      "rolloutPhase": "example",
      "serviceStatus": "example"
    }
  }
}

---

ray_service_list

List RayServices as compact rows (name, namespace, serve status, healthy serve endpoints, age, 1-line health), capped and paginated via an opaque continue token. Read-only.

Tier: read (read-only)

Input parameters

Name	Type	Required	Description
allNamespaces	boolean		list across all namespaces instead of one
continue	string		opaque continue token from a prior page; omit for the first page
limit	integer		max rows per page; 0 uses the server default (~50)
namespace	string		namespace to list RayServices in; defaults to the server default namespace

Output fields

Name	Type	Required	Description
continue	string		the continue token for the next page; empty when exhausted
count	integer	yes	the number of rows shown on this page
moreAvailable	boolean	yes	true if more pages exist; pass continue for the next page
services	array	yes	the compact service rows for this page

Example

Request:

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

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "<human-readable summary>",
        "type": "text"
      }
    ],
    "structuredContent": {
      "continue": "example",
      "count": 1,
      "moreAvailable": false,
      "services": [
        {
          "ageSeconds": 1,
          "health": "example",
          "healthyReplicas": 1,
          "name": "ray-demo",
          "namespace": "ray-system",
          "serviceStatus": "example"
        }
      ]
    }
  }
}

---