Couchbase MCP Server

Overview Schema Source Related Servers Discussions Admin

get_bucket_config

Read-only

Retrieves a Couchbase bucket's configuration and live stats—or all buckets when no name is given—to diagnose capacity, durability, and storage issues before making changes.

Instructions

Get a bucket's configuration and live state — or every bucket's, if bucket_name is omitted.

Answers "what is this bucket configured as, and how full is it right now?" — RAM quota, replica count, eviction policy, durability level, storage backend, conflict- resolution type, auto-compaction settings, and basic stats (item count, memory used, ops/sec, disk used). Use this to explain a bucket-level symptom that get_cluster_metrics or get_index_stats pointed at, or as a pre-flight safety check before advising a compaction/quota/durability change — this tool only ever reads; create/edit/flush/delete stay CAO-owned. get_buckets_in_cluster lists bucket names via the SDK but exposes none of this; use this tool once a specific bucket needs explaining.

bucket_name must be omitted (not passed as "") to get every bucket — an empty string is rejected rather than silently treated the same as omitting it, since a caller that meant to name a bucket should not get back every bucket's configuration instead.

Calls GET /pools/default/buckets/<bucket_name> (one bucket) or GET /pools/default/buckets (every bucket, when bucket_name is omitted). Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs the Read-Only Admin (ro_admin) role.

Reading the result — returned exactly as the endpoint sends it, nothing stripped or renamed, so every field keeps its REST API name (camelCase):

"autoCompactionSettings" is the bare value false, not an object, when the bucket has no per-bucket override. Read false as "uses the cluster-wide compaction settings", not "compaction disabled" — they are not the same thing, and this field alone cannot tell you which.
"durabilityMinLevel" and "storageBackend" are absent on server versions that predate those fields; absence means "not reported", not "none"/"couchstore".
"vBucketServerMap" and "nodes" are the bulk of the payload (a full server list and a per-vBucket map that grows with vbucket/replica/node count) and carry no RCA-relevant signal, but are not stripped: this tool never reshapes what the endpoint returns.
A node that was never joined to a cluster (or whose cluster-init failed) answers this endpoint with 200 and [] rather than an error. This is unlikely to matter for a connection_string naming hosts an operator verified are cluster members, but is a real risk when it names a DNS/SRV record backed by a rotating node set (e.g. a Kubernetes headless service), where a connection can land on a freshly provisioned, not-yet-joined node: an empty list there is not proof the cluster itself has no buckets.

Returns the endpoint's response unchanged — a dict for one bucket, a list for all buckets. Raises on failure, including a 404 for an unknown bucket name.

Input Schema

Name	Required	Description	Default
`timeout`	No
`bucket_name`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.1.0Nov 5, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=true, and the description goes far beyond it: REST endpoints used, 7.6+ self-managed-only constraint (Capella rejected without a call), ro_admin role requirement, raises-on-failure including 404 for unknown buckets, and the trap where a not-yet-joined node answers 200 with [] — turning a misleading empty result into a documented hazard.

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

Conciseness3/5

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

Well front-loaded with a one-line summary followed by usage, parameter semantics, endpoint/auth notes, and a 'Reading the result' section. However, the 'returns the endpoint's response unchanged / nothing stripped or renamed / never reshapes what the endpoint returns' idea is restated three times, and the not-yet-joined-node paragraph is long for an edge case, so several sentences could be trimmed.

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?

Covers everything an agent needs to call this correctly and interpret it: auth and version prerequisites, endpoint shapes, the false-vs-cluster-inherited autoCompactionSettings ambiguity, absent-field semantics for older servers, and payload-skew caveats. An output schema exists, yet the field-level interpretation notes add genuine value rather than duplicating it.

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

Parameters4/5

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

Schema coverage is 0%, so the description must carry parameter meaning — and it does for bucket_name: omitting it returns all buckets, passing "" is explicitly rejected rather than silently coalesced, and the return type differs (dict vs list) by that choice. The second parameter, timeout, is never mentioned, which is the only remaining gap.

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?

States a specific verb+resource (get a bucket's configuration and live state, or all buckets when bucket_name is omitted) and enumerates the exact fields covered (RAM quota, replica count, eviction policy, durability, storage backend, stats). It explicitly contrasts with get_buckets_in_cluster ('lists bucket names via the SDK but exposes none of this'), so an agent can separate the two without opening a schema.

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

Usage Guidelines5/5

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

Gives concrete when-to-use triggers ('explain a bucket-level symptom that get_cluster_metrics or get_index_stats pointed at') and a pre-flight scenario before advising compaction/quota/durability changes. It also names the exclusion boundary ('create/edit/flush/delete stay CAO-owned'), leaving nothing to inference.

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

Deploy Server