Couchbase MCP Server

Overview Schema Source Related Servers Discussions Admin

get_cluster_health_and_services

Read-only

Check Couchbase cluster health by pinging services and reporting reachability, latency, and errors per service. Optionally scope to a bucket or filter service types for targeted diagnostics.

Instructions

Check whether the cluster is reachable right now, and where it's broken.

This actively pings (see caveat below) the cluster's services and reports, per service:

Whether it responded and how long it took (latency)
Which node/endpoint answered, and any error if it didn't

Scope: cluster-level vs bucket-level ping

If bucket_name is omitted, this pings at the cluster level. This covers more services in one call, but whether the key-value (KV) service is included depends on the Couchbase Server version — it may be silently skipped.
If bucket_name is provided, this pings from the perspective of that bucket instead. This guarantees the KV service is covered for that bucket, but the result is scoped to that one bucket only — ping again per bucket_name to cover a multi-bucket cluster.

service_types optionally restricts which services get pinged. Valid values: "key_value", "query", "search", "analytics", "view", "management", "eventing". Omit to ping every service. An unrecognized value returns an error response instead of raising.

Caution — this is somewhat invasive: unlike a passive connection-state check, ping performs a live network round-trip to every targeted service. Prefer a narrow service_types filter, and avoid calling this in tight loops or high-frequency polling.

Returns:

Cluster health status with service-level connection details and latency measurements

Input Schema

TableJSON Schema

Name	Required	Description	Default
`bucket_name`	No
`service_types`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.1Aug 28, 2026

addedInput schema / properties / service_types

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

Changed4 schema fields changedv0.8.0May 27, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
- removedInput schema / properties / bucket_name / title
```
Removed value: -"Bucket Name"
```
- removedInput schema / title
```
Removed value: -"get_cluster_health_and_servicesArguments"
```
- removedOutput schema / title
```
Removed value: -"get_cluster_health_and_servicesDictOutput"
```
Addedv1.0.0Jan 3, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the readOnlyHint annotation by disclosing that the tool performs live network round-trips, may silently skip KV services depending on Couchbase Server version, returns an error response for unrecognized service_types rather than raising, and is somewhat invasive. These are critical behavioral traits the agent could not infer from the schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Although lengthy, every section earns its place: scope selection, service_types values, version-dependent caveats, and invasiveness warnings all change caller behavior. The use of bolded headings and bulleted list keeps dense information scannable, and the most important purpose statement is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two optional parameters, no schema descriptions, and an output schema present, the description covers all needed decision points: reachability check mechanics, per-service returned details, cluster versus bucket scoping, version caveats, valid service_types, invalid-input behavior, and safety advice. Nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully compensates. It explains that bucket_name changes scope from cluster-level to bucket-level and guarantees KV coverage, and it enumerates the exact valid service_types values plus behavior when omitted or invalid. This is far more informative than the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Check whether the cluster is reachable right now, and where it's broken.' It then distinguishes itself from a passive connection-state check and from sibling tools by emphasizing live ping behavior and service-level reporting. This makes it instantly clear what the tool does and how it differs from related cluster-status tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on when to use cluster-level versus bucket-level pinging, explains the KV-service coverage tradeoff, and advises callers to prefer narrow service_types filters and avoid high-frequency polling. It contrasts with 'a passive connection-state check' but does not explicitly name the sibling tool to use instead, so the routing guidance is strong but not fully explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.