Couchbase MCP Server
A read-only Couchbase MCP server that lets an AI agent explore cluster structure, read documents, run SQL++ queries, and diagnose health and query performance.
Inspect cluster topology — list buckets, scopes, and collections (
get_buckets_in_cluster,get_scopes_in_bucket,get_collections_in_scope,get_scopes_and_collections_in_bucket).Check connectivity and health — verify credentials against the cluster (
test_cluster_connection), actively ping services with latency per service viaget_cluster_health_and_services, and read cached SDK connection diagnostics offline viaget_cluster_diagnostics_report.Review server configuration —
get_server_configuration_statusreports the resolved settings (read-only mode, disabled tools, etc.) without connecting.Read data — fetch whole documents by ID (
get_document_by_id) or just specific fields, existence checks, and array/object counts withlookup_subdocumentto avoid transferring full documents.Understand schemas — infer a collection's structure with
get_schema_for_collection.Query — run SQL++ scoped to a bucket/scope, with named parameters to avoid injection (
run_sql_plus_plus_query), and inspect plans viaexplain_sql_plus_plus_query.Tune indexes — list indexes with filterable definitions and status (
list_indexes) and get Index Advisor recommendations including covering indexes (get_index_advisor_recommendations).Analyze query performance — surface problem queries from
system:completed_requests: slowest, most frequent, largest response sizes/result counts, primary-index users, non-covering-index users, and poorly selective scans.Safe by default — every tool in this schema is read-only; no write, index-creation, or data-modifying tools are exposed.
Allows LLMs to interact with Couchbase clusters to query collections, retrieve document structures, perform CRUD operations on documents, and run SQL++ queries on specified scopes.
Enables running the MCP server as a containerized application with configurable environment variables for Couchbase settings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Couchbase MCP Server show me the top 5 users by activity from the users collection"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Couchbase MCP Server
Couchbase MCP Server is a self-hosted MCP Server that allows AI agents to connect to and interact with data in Couchbase Servers (whether hosted on Capella or self-managed) or Operational Insights Enterprise. It provides tools across categories including Cluster Health, Data Schema, Query, and more — with safety controls via read-only mode and fine-grained tool disabling. It supports both STDIO and Streamable HTTP transports with OAuth capabilities.
Couchbase MCP Server is distributed as a Python Package Index (PyPI) package and via Docker. Enterprise support for Couchbase MCP Server is available by licensing Couchbase AI Data Plane, which also entitles use and enterprise support of Couchbase Agent Memory and Couchbase Agent Catalog.
Full documentation: docs.couchbase.com/mcp-server
Table of Contents
Related MCP server: Couchbase MCP Server
Why Couchbase MCP Server
Safe by default — write tools are not loaded and data-modifying queries are blocked unless you set
CB_MCP_READ_ONLY_MODE=false; individual tools can also be disabled or gated behind user confirmation.Couchbase Server and Operational Insights — the operational server connects to Couchbase Capella or a self-managed Couchbase Server cluster with the same configuration; the Operational Insights server connects to self-managed Operational Insights clusters.
RBAC-aware — tool controls guide the LLM; the Couchbase user's role-based access control remains the authoritative security boundary.
Production transports — STDIO for local desktop clients, or Streamable HTTP with optional OAuth 2.1 (any JWKS-publishing IdP: Auth0, Okta, Keycloak, Entra, Cognito, …), health checks and audit logging for shared deployments. The operational server can also run multiple workers to use more CPU cores.
Any MCP client — tested with Claude Desktop, Cursor, Windsurf, VS Code and JetBrains AI Assistant/Junie.
Once connected, you can ask things like:
"What buckets, scopes and collections do I have, and what's the schema of the
orderscollection?""Find the 10 most recent documents in
userswherestatus = 'active'.""What are the 5 slowest queries in the last hour, and are any of them missing a covering index?"
"Is this cluster healthy, and which services are running?"
"Insert a new document into
productswith these fields: …" (requiresCB_MCP_READ_ONLY_MODE=false)
Choosing a Server
This package ships two MCP servers. Each one is started by its own subcommand, connects to a different kind of cluster, and has its own tools. Pick the one that matches your cluster, follow its section for setup and tools, then use Common Configuration for the settings both share. To use both, register each as a separate server in your MCP client.
Use it with | A Couchbase cluster (Capella or self-managed) | A self-managed Operational Insights cluster (not available on Capella) |
Subcommand |
|
|
Connection string |
| HTTP(S) URL, e.g. |
Credential variables |
|
|
Tools | 52 — cluster health, schema, KV, SQL++, indexes, full-text and vector search, query performance | 13 — schema, SQL++ (sync and async), indexes, exports |
Default HTTP port |
|
|
Default log file |
|
|
The subcommand is optional for the operational server today — a bare
couchbase-mcp-serverstarts it — but naming it keeps your configuration unambiguous. Options go after the subcommand:couchbase-mcp-server operational --transport=http. Check the installed version withuvx couchbase-mcp-server --version.
Operational Server
The operational server connects to a Couchbase cluster on Capella or self-managed Couchbase Server, using the couchbase Python SDK.
Operational Quick Start
You need a running Couchbase cluster — the Capella free tier is the quickest way to get one (you can import a sample dataset) — and an MCP client. Add one of these configurations to your client (see Client Setup for where each client keeps it). If the client already has other servers, add couchbase to the existing mcpServers object.
From PyPI with uvx (requires uv and Python 3.11+):
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}With Docker (requires only Docker):
{
"mcpServers": {
"couchbase": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_CONNECTION_STRING=couchbases://connection-string",
"-e", "CB_USERNAME=username",
"-e", "CB_PASSWORD=password",
"couchbase/mcp-server:latest", "operational"
]
}
}
}git clone https://github.com/couchbase/mcp-server-couchbase.git{
"mcpServers": {
"couchbase": {
"command": "uv",
"args": [
"--directory", "path/to/cloned/repo/mcp-server-couchbase/",
"run", "src/mcp_server.py", "operational"
],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}path/to/cloned/repo/mcp-server-couchbase/ is the path to your clone — keep the trailing slash. After pulling updates, run uv sync to update dependencies.
Operational Connection and Authentication
Use either a username and password or a client certificate (mTLS). If both are set, the certificate is used.
Environment Variable | CLI Argument | Description |
|
| Connection string to the cluster. Required |
|
| Basic authentication |
|
| mTLS authentication |
|
| Root certificate for a self-signed/untrusted server certificate (not needed for Capella) |
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
"CB_CLIENT_KEY_PATH": "/path/to/client.key"
}
}
}
}Operational Tools
Write tools (marked ✏️) are not loaded while read-only mode is on, the default. Tools marked 🖥️ are self-managed only — they use admin REST endpoints that Capella does not expose, or (discover_tool_input_values) only serve reference data for a tool that does — so they need self-managed Couchbase Server 7.6+ and are not registered on Capella connections.
Cluster setup and health
Tool | Description |
| Server status and configuration without connecting to the cluster: read-only mode, disabled/confirmation-required tools, OAuth, logging and audit counters |
| Check the cluster credentials by connecting to the cluster |
| Cluster health and running services, optionally filtered via |
| The SDK's cached connection diagnostics, without active network probing |
| Cluster statistics over a historic time window (stats-range endpoint) |
| Tasks running right now — rebalance, compaction, XDCR, index build. Needs |
| Per-node health: service topology, membership, orchestrator and a health rollup. Needs |
| A bucket's (or every bucket's) configuration and live state — quotas, eviction, replicas, durability, storage, compaction. Needs |
| The system event log (config changes, failovers, rebalances, restarts), windowed with |
| Look up exact input values other tools need (e.g. every metric name for |
Data model and schema discovery
Tool | Description |
| List all buckets in the cluster |
| List all scopes in a bucket |
| List all collections in a scope (requires the Query service) |
| List all scopes and collections in a bucket |
| Infer the structure of a collection |
| Create a scope in a bucket (Server 7.6+ and Capella) |
| Create a collection in an existing scope (Server 7.6+ and Capella) |
| Delete a scope and all its collections — permanent |
| Delete a collection and all its documents — permanent |
Document (KV) operations
Tool | Description |
| Get a document by ID |
| Read specific paths, existence checks or counts without fetching the whole document |
| Upsert a document by ID |
| Insert a new document (fails if it exists) |
| Replace an existing document (fails if it doesn't exist) |
| Delete a document by ID |
| Modify paths in an existing document (upsert, insert, replace, remove, array ops, counters) |
Query and indexing
Tool | Description |
| Run a SQL++ query scoped to a bucket and scope — use collection names directly ( |
| Generate and evaluate an EXPLAIN plan: metadata, extracted plan and findings |
| Index Advisor recommendations for a SQL++ query |
| List indexes with definitions, filterable by bucket/scope/collection/name; flags vector indexes ( |
| Per-index size, fragmentation, scan traffic and lag, per node — finds pressure and unused indexes |
| Create a scalar, Hyperscale vector or Composite vector GSI index ( |
| Deprecated — use |
| Build all deferred indexes on a collection |
| Drop a GSI index (scalar or vector) |
Full-text search (FTS)
Requires Couchbase Server 7.6+ and the Search service. Scope-level and cluster-level (legacy) indexes are both supported: pass bucket_name and scope_name together for scope-level, or omit both.
Tool | Description |
| List Search indexes — cluster-level, per bucket, or per scope |
| Full definition of one Search index (mappings, analyzers, plan params) |
| Run any non-vector FTS query from its raw JSON body; |
| Create or update a Search index, including vector field mappings. Updates trigger a full rebuild — pass the current |
| Drop a Search index — permanent |
Vector search
Both tools embed plain query text with the model configured under Embedding Providers. Available on self-managed Couchbase Server and Capella.
Tool | Description |
| Similarity search against a GSI vector index (Server 8.0+) via |
| Search-service vector search (Server 7.6+) against a named index. |
Query performance analysis
Tool | Description |
| Longest-running queries by average service time |
| Most frequently executed queries |
| Queries with the largest response sizes |
| Queries with the largest result counts |
| Queries using a primary index |
| Queries not using a covering index |
| Queries whose scans — secondary index, primary index or sequential — return far more documents than the final result |
Query service health 🖥️
These call the Query service's own admin REST API on every query node.
Tool | Description |
| Query-engine health: request rate, active/queued requests, memory, GC, uptime. Needs |
| Queries executing right now across all query nodes. Needs |
| Cancel an in-flight query by request ID. Needs Full Admin or Cluster Admin |
Tools disabled automatically on Capella
The 🖥️ tools reach Couchbase through admin REST endpoints that Capella does not expose (the one exception, discover_tool_input_values, is withheld because it only serves a tool that needs them). When every host in CB_CONNECTION_STRING ends in .cloud.couchbase.com, the server does not register them and reports them alongside your own disabled tools in get_server_configuration_status and the startup log. SDK-based tools such as get_cluster_health_and_services and get_client_connectivity_report stay available.
Tool | Endpoint it needs |
| Management REST ( |
| Management REST ( |
| Management REST ( |
| Management REST, plus per-node endpoints |
| Management REST ( |
| Index Service REST (each indexer's |
| Query service REST ( |
| Query service REST ( |
| Query service REST ( |
| None (works offline), but it only serves |
Embedding Providers
run_vector_query and run_vector_search embed query text with the provider set in CB_MCP_EMBEDDING_MODEL_PROVIDER. This is optional: without it the server starts normally and both tools stay registered, but calling them returns an error explaining what to set.
| Required | Optional | Notes |
|
| — | Capella Model Service. |
|
|
| Set the endpoint to use an OpenAI-compatible local server (Ollama, vLLM, LM Studio) |
|
|
| |
|
|
| |
|
|
| Amazon Titan embedding models (e.g. |
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password",
"CB_MCP_EMBEDDING_MODEL_PROVIDER": "openai",
"CB_MCP_EMBEDDING_MODEL": "text-embedding-3-small",
"CB_MCP_EMBEDDING_MODEL_API_KEY": "sk-..."
}All Options
The Operational Insights server accepts the same options, except that it has its own connection settings and no CB_MCP_EMBEDDING_MODEL_* options.
Environment Variable | CLI Argument | Description | Default |
|
| Connection string to the Couchbase cluster | Required |
|
| Username with access to required buckets for basic authentication | Required (or Client Certificate and Key needed for mTLS) |
|
| Password for basic authentication | Required (or Client Certificate and Key needed for mTLS) |
|
| Path to the client certificate file for mTLS authentication | Required if using mTLS (or Username and Password required) |
|
| Path to the client key file for mTLS authentication | Required if using mTLS (or Username and Password required) |
|
| Path to server root certificate for TLS if server is configured with a self-signed/untrusted certificate. This will not be required if you are connecting to Capella | |
|
| Prevent all data modifications (KV, Query, scope/collection management, index management, and FTS index management). When enabled, write tools are not loaded. |
|
|
| Transport mode: |
|
|
| Host for the HTTP transport mode |
|
|
| Port for the HTTP transport mode |
|
|
| Number of server worker processes for the |
|
|
| Handle each HTTP request without per-session state. Only honored with |
|
|
| Tools to disable (see Disabling Tools) | None |
|
| Tools that require explicit user confirmation before execution via MCP elicitation (see Requiring confirmation) | None |
|
| Logging level for the MCP server: |
|
|
| Comma-separated log destinations: |
|
|
| Base path for per-level log files (only used when the |
|
|
| Global maximum size in MB per log file before it rotates, inherited by every level unless overridden. |
|
|
| Deprecated — use | Unset |
|
| Rotation size in MB for the ERROR log file; overrides | Inherits |
|
| Rotation size in MB for the WARNING log file; overrides | Inherits |
|
| Rotation size in MB for the INFO log file; overrides | Inherits |
|
| Rotation size in MB for the DEBUG log file; overrides | Inherits |
|
| Rotated backup files kept per-level log file (excluding the live file), applied to every level unless overridden. |
|
|
| Rotated backups kept for the ERROR log file; overrides the global count for ERROR | Inherits |
|
| Rotated backups kept for the WARNING log file; overrides the global count for WARNING | Inherits |
|
| Rotated backups kept for the INFO log file; overrides the global count for INFO | Inherits |
|
| Rotated backups kept for the DEBUG log file; overrides the global count for DEBUG | Inherits |
|
| JWKS endpoint of the identity provider used to verify bearer JWTs. Enables OAuth when set with the issuer and audience (see OAuth 2.1 Authorization) | None |
|
| Expected JWT | None |
|
| Expected JWT | None |
|
| JWT signing algorithm: one of |
|
|
| Public base URL of this server. When set, publishes RFC 9728 Protected Resource Metadata so PRM-aware clients can discover the IdP | None |
|
| Override the OAuth scope label treated as 'read' access (advertised in PRM and matched against the token's |
|
|
| Override the OAuth scope label treated as 'write' access; same semantics as the read label |
|
|
| Enable audit logging — a separate sink from the |
|
|
| Comma-separated audit destinations: |
|
|
| Path to the audit log file. Required when | None |
|
| Maximum size in MB the live audit file may reach before it rotates. |
|
|
| Age the live audit file may reach before it rotates, as |
|
|
| Rotated backups retained per audit file, excluding the live file. Backups are gzipped. |
|
|
| Record tool argument values in the audit log. Off by default — there is no redaction in this release, so enabling it writes arguments verbatim, including full document bodies |
|
|
| Audit events to suppress: comma-separated numeric event ids (e.g. | None |
|
| Embedding provider for | None |
|
| Model name/ID for the configured embedding provider | None |
|
| API key for the configured provider. Not used by | None |
|
| Base URL override (an OpenAI-compatible local server, or a Capella Model Service deployment's own URL — required when | None |
|
| AWS access key ID, | None |
|
| AWS secret access key, | None |
|
| AWS region, | None |
Operational Insights Server
The operational-insights server connects to self-managed Operational Insights clusters. Operational Insights is a real-time analytical database (RT-OLAP) for real-time apps and operational intelligence. The server is not available for Capella. It uses the couchbase-operational-insights SDK. It runs as its own process, separate from the operational server.
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING is an HTTP(S) URL, not a couchbase:// connection string — e.g. http://localhost:8095, or https://<host>:18095 over TLS. This is the most common misconfiguration.
Operational Insights Quick Start
From PyPI with uvx:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational-insights"],
"env": {
"CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "http://localhost:8095",
"CB_OPERATIONAL_INSIGHTS_USERNAME": "Administrator",
"CB_OPERATIONAL_INSIGHTS_PASSWORD": "password"
}
}
}
}With Docker:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=http://host.docker.internal:8095",
"-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=Administrator",
"-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=password",
"couchbase/mcp-server:latest", "operational-insights"
]
}
}
}From source, use the operational source configuration with operational-insights as the last argument and the variables above.
Operational Insights Connection and Authentication
Environment Variable | CLI Argument | Description |
|
| Endpoint URL (HTTP/HTTPS). Required |
|
| Username |
|
| Password |
|
| Root certificate (PEM) for a self-signed/untrusted server certificate |
|
| Client certificate for mTLS — PEM (with a key) or a PKCS#12 bundle ( |
|
| Private key (PEM) for the client certificate. Leave unset for PKCS#12 |
|
| Password for an encrypted key or PKCS#12 bundle |
|
| Maximum query result size in bytes. Unset means no limit. When set, reading stops at the budget and the response reports |
|
| Timeout in seconds for each async query request: starting the query, checking its status, fetching results, discarding and cancelling. For a fetch it covers the whole download, so a result that takes longer than this to read fails. Raise it for large results or slow links. Positive integer, default |
All common configuration applies, with these differences from the operational server:
The default port is
8001and the default log file ismcp_server_operational_insights.log, so both servers can run side by side.Only one worker is supported (
CB_MCP_WORKERS=1), because async query handles live in process memory.It has no
CB_MCP_EMBEDDING_MODEL_*options.
Operational Insights Tools
All names except get_server_configuration_status are prefixed operational_insights_, so both servers can be registered in one client without collisions. The write tool (marked ✏️) is not loaded while read-only mode is on, the default.
Server Status
Tool | Description |
| Same tool as on the operational server |
Data Model & Schema Discovery
Tool | Description |
| List databases |
| List scopes in a database |
| List collections (datasets) in a scope |
| Infer a collection's JSON schema by sampling |
Query and Index
Tool | Description |
| List secondary indexes from |
| EXPLAIN a SQL++ statement without running it |
| Run SQL++ and return rows, up to the result size limit; can export instead. Read-only mode is enforced server-side |
| Start a long-running query and return a |
| Poll an async query; returns rows (or the export destination) when ready |
| Free a finished async query's results |
| Stop a still-running async query (allowed in read-only mode) |
| Create a secondary index via |
Async queries follow a start → poll → discard-or-cancel flow: operational_insights_run_query_async returns a query_handle, operational_insights_get_async_query_results is polled until ready, then operational_insights_discard_async_query_results frees the results, or operational_insights_cancel_async_query stops a query still running.
Exporting large results
Instead of returning rows, operational_insights_run_query_sync and operational_insights_run_query_async can wrap the statement in COPY ... TO and write the rows to external object storage. Pass all three of copy_to_link (an existing link created with CREATE LINK ... TYPE S3), copy_to_bucket and copy_to_path, plus optionally copy_to_format (json, the default, or parquet). The tool then returns a confirmation with no rows:
{
"success": true,
"exported": true,
"destination": {"link": "s3Link", "bucket": "my-exports", "path": "exports/run1", "format": "json"},
"message": "Results were written to my-exports/exports/run1 as json. ..."
}A partial destination is rejected rather than silently returning rows.
The sync tool waits for the whole upload; prefer the async tool for large exports.
Exports are blocked in read-only mode (they write to external storage), so they need
CB_MCP_READ_ONLY_MODE=falseor a token withcouchbase-mcp:write.csvis not offered, because it needs an explicit output schema that can't be inferred from an arbitrarySELECT.
Common Configuration
These settings work the same way for both servers. Every option can be set as an environment variable or as a CLI flag after the subcommand.
Safety Controls
Follow these security principles:
Give the database user least privilege — RBAC is the authoritative boundary (see below).
Provide only the tools the agent needs, and disable the rest — every loaded tool is something the LLM can call. Use read-only mode and
CB_MCP_DISABLED_TOOLSto keep the tool list to the minimum.Require confirmation for sensitive tools that you keep — see Requiring confirmation.
The controls below form three layers, from broadest to narrowest. Use them together — but remember that none of them replaces RBAC.
The database user's RBAC permissions are the authoritative security control. For example, disablingupsert_document_by_id and delete_document_by_id does not stop run_sql_plus_plus_query from running INSERT/UPDATE/DELETE/MERGE — only read-only mode or missing RBAC permissions do. Give the server's database user only the permissions it needs.
Read-only mode
CB_MCP_READ_ONLY_MODE (default true) is the single switch for writes:
true— the write tools marked ✏️ in each server's tool list are not loaded, and queries that modify data or structure are blocked.false— write tools are loaded and modifying queries are allowed.
Disabling tools
CB_MCP_DISABLED_TOOLS removes tools from discovery entirely. It accepts a comma-separated list or a path to a file with one tool name per line (# starts a comment):
CB_MCP_DISABLED_TOOLS="upsert_document_by_id,delete_document_by_id"
# or
CB_MCP_DISABLED_TOOLS=/path/to/disabled_tools.txt# disabled_tools.txt
# Write operations
upsert_document_by_id
delete_document_by_id
# Index advisor
get_index_advisor_recommendationsOn Capella, the operational server also disables some admin tools automatically.
Requiring confirmation (elicitation)
CB_MCP_CONFIRMATION_REQUIRED_TOOLS asks the user to confirm before a listed tool runs, using MCP elicitation. It takes the same comma-separated or file formats as disabled tools:
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"If the client supports elicitation, the user is prompted before the tool runs.
If it doesn't, the tool runs without confirmation, for backward compatibility.
Confirmation needs an MCP session, so it cannot be combined with stateless HTTP (
CB_MCP_STATELESS_HTTP=trueorCB_MCP_WORKERSabove 1). The server refuses to start with that combination. Behind a load balancer, confirmation needs sticky sessions — see Load balancers.
Transports
Transport | Use for | Endpoint |
| One local client that launches the server as a subprocess | — |
| Several clients sharing one server; supports OAuth and health checks, and workers on the operational server |
|
Set the transport with CB_MCP_TRANSPORT, the bind address with CB_MCP_HOST (default 127.0.0.1) and the port with CB_MCP_PORT (each server's default port when unset). Without OAuth, the HTTP endpoint is unauthenticated.
uvx couchbase-mcp-server operational \
--connection-string='<couchbase_connection_string>' \
--username='<database_username>' \
--password='<database_password>' \
--transport=httpThen point your client at the URL:
{
"mcpServers": {
"couchbase-http": {
"url": "http://localhost:8000/mcp"
}
}
}Multiple workers
One process uses at most about one CPU core. --workers N (CB_MCP_WORKERS) runs N processes behind the same host and port; the number of available cores is a good starting point. Workers are supported by the operational server only. With more than one worker:
The
httptransport is required, and the server runs in stateless HTTP mode, because a client's requests can reach different workers. You can also set--stateless-http=trueon a single worker, for example behind a load balancer without sticky sessions.Confirmation-required tools cannot be used.
Each process writes its own log files, named with host and process id (
mcp_server.<host>.<pid>.info.log) — one set for the supervisor and one per worker.
Load balancers
You can run several server instances behind a load balancer. Each instance keeps its MCP sessions in its own memory, so the load balancer setting decides what works:
Load balancer | Server setting | Confirmation-required tools |
Sticky sessions, routed on the | One worker, stateful (the default) | Supported |
No sticky sessions |
| Not supported — the server refuses to start if they are configured |
Without sticky sessions, a stateful instance rejects every request whose session was created on a different instance. Use stateless mode in that case.
Route on the
Mcp-Session-Idheader, not on cookies. Many MCP clients do not keep cookies.If an instance restarts or fails over, its sessions and any pending confirmation prompts are lost. The client must start a new session.
Operational Insights async queries keep their
query_handlein the memory of the instance that started the query, also in stateless mode. Polling, discarding or cancelling the query on a different instance returnsUnknown query_handle. Use these tools with a single instance, or with sticky sessions so that all calls reach the instance that started the query. Stateless mode sends noMcp-Session-Id, so it needs another affinity key, such as the client IP address.
Health check
In HTTP mode, GET /health returns {"status": "ok", "server": "<server>"} on the MCP port. It is a liveness check: it does not connect to the cluster (so a cluster outage doesn't restart healthy containers), needs no authentication even with OAuth enabled, and is served by every worker. See Docker for probe examples.
OAuth 2.1 Authorization
With --transport=http, either server can act as an OAuth 2.1 resource server, validating bearer JWTs against your identity provider's JWKS. It works with any OAuth 2.1/OIDC provider that publishes a JWKS, and does not issue tokens or manage users. OAuth settings are ignored on stdio.
OAuth turns on only when all three of
CB_MCP_OAUTH_JWT_JWKS_URI,CB_MCP_OAUTH_JWT_ISSUERandCB_MCP_OAUTH_JWT_AUDIENCEare set; setting only some fails at startup.CB_MCP_OAUTH_MCP_BASE_URLadditionally publishes RFC 9728 Protected Resource Metadata so clients can discover the authorization server.Access is gated by two scopes in the token's
scope/scpclaim:couchbase-mcp:read(read tools) andcouchbase-mcp:write(write tools). Full access needs both. Rename them withCB_MCP_OAUTH_SCOPE_READ_LABEL/CB_MCP_OAUTH_SCOPE_WRITE_LABELif your IdP can't emit these labels. Both servers use the same labels, so one IdP configuration covers both.
uvx couchbase-mcp-server operational \
--connection-string='<couchbase_connection_string>' \
--username='<database_username>' \
--password='<database_password>' \
--transport=http \
--oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
--oauth-issuer='https://auth.example.com/' \
--oauth-audience='couchbase-mcp-server' \
--oauth-mcp-base-url='<public_base_url_of_this_server>'See the OAuth documentation for the operational server and the Operational Insights server for IdP setup.
Logging
Each server logs to stderr at info level by default.
CB_MCP_LOG_LEVEL—off,error,warning,info(lifecycle events and tool calls) ordebug.CB_MCP_LOG_SINKS—stderr,file, or both. Withfile, one rotating file per level is written next toCB_MCP_LOG_FILE(mcp_server.info.log,mcp_server.error.log, …).Rotation and retention —
CB_MCP_LOG_ROTATION_MAX_SIZE_MB(default 1 MB) andCB_MCP_LOG_RETENTION_BACKUP_COUNT(default 1) apply to every level; override per level withCB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB/CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT. Invalid sizes fall back to the default with a startup warning.CB_MCP_LOG_MAX_BYTESis deprecated.Config snapshot — with the
filesink, a JSON record of the environment and redacted server config is written tomcp_server_config.log.jsonon every start, for support.
# Debug logging to stderr and rotating per-level files
uvx couchbase-mcp-server operational --log-level=debug --log-sinks=stderr,fileYour MCP client usually also captures the server's stderr — see Client Setup for where. Details: logging documentation for the operational server and the Operational Insights server.
Auditing
Audit logging records who did what, and whether it was allowed — separate from the operational logs, which record what went wrong. The MCP server is the only layer that can answer this for an agent: every request reaches the cluster as a single database user, and decisions such as a scope denial, a read-only block or a declined confirmation never reach the cluster at all.
Auditing is off by default. Turn it on with CB_MCP_AUDIT_LOG_ENABLED=true; it writes to stderr unless you set CB_MCP_AUDIT_LOG_SINKS=file and CB_MCP_AUDIT_LOG_FILE_PATH.
# 90 days of daily, gzipped audit files
uvx couchbase-mcp-server operational --audit-log-enabled=true \
--audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
--audit-log-rotation-interval=1d --audit-log-rotation-max-size-mb=0 \
--audit-log-retention-max-backups=90Records are JSON Lines using the same field vocabulary as Couchbase Server and Sync Gateway:
{"id":61522,"name":"document write","description":"A document write operation was requested through a tool","timestamp":"2026-09-29T09:14:22.418Z","real_userid":{"domain":"oauth","user":"agent-svc-7"},"server":{"version":"1.0.2","host":"mcp-01"},"cid":"9f2c...","outcome":"success","tool_name":"upsert_document_by_id","required_scope":"write","ks":"travel-sample.inventory.airline","cb_userid":"mcp_service"}Identity —
real_useridis the caller:oauth(the token subject),local(the OS user, on stdio) oranonymous(HTTP without OAuth, which warns at startup).Correlation —
cidgroups every record from one request, and is sent as the SQL++client_context_id, so it joins exactly with Couchbase Server'sclientContextId. There is deliberately no session identifier.Events — a fixed, numbered catalogue (lifecycle, initialize, token rejected, scope denied, read-only block, confirmation declined/skipped, and a read/write pair per tool category).
queryandsearchare the exceptions: each is recorded as a single event rather than a read/write pair, because the distinction could not be made reliably for statement-driven and search surfaces. Vector operations sit inside those two categories. The full catalogue ships asdescriptor.jsonin the package. The operational server uses block0xF000(61440), Operational Insights0x10000(65536), and both share0xE000(57344) for core events.Filtering —
CB_MCP_AUDIT_LOG_DISABLED_EVENTSsuppresses read events by numeric id (e.g.61490,61492). Write and security events cannot be disabled, and neither can the single-event categoriesquery(61507, or 65603 on Operational Insights) andsearch(61510): one event covers each category's writes as well as its reads, so switching it off would lose a mutation record.Rotation — by size (
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB, default 10) and age (CB_MCP_AUDIT_LOG_ROTATION_INTERVAL, default1d), whichever comes first;0switches either off. Rotated files are timestamped and gzipped; the live file stays plain text fortail -f.Per-process files — host and pid are inserted into the name (
audit.log→audit.<host>.<pid>.log), so concurrent processes never share a file.Retention is per file —
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS(default 10) bounds one file's backups. Each new process writes a new file and nothing prunes old ones, so size the volume or sweep oldaudit.*.log*files.Fail-open — if the file can't be written, the server keeps serving and counts dropped records;
get_server_configuration_statusreportswritten/dropped/write_errors.Tool arguments — recorded only with
CB_MCP_AUDIT_LOG_TOOL_ARGS=true, which warns at startup. There is no redaction in this release, so arguments, including full document bodies, are written verbatim.
Client Setup
Each client needs a server configuration from the operational or Operational Insights quick start in its own configuration location. The examples below use the operational server.
Open the configuration file (see the MCP quickstart guide):
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the server under
mcpServersand restart Claude Desktop.
Logs: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. See the MCP troubleshooting guide.
Go to Cursor Settings > Tools & Integrations > MCP Tools (see Cursor's MCP docs), or use the one-click Install in Cursor link — then replace the placeholder connection string and credentials.
Add the configuration under
mcpServersand save.Refresh the MCP servers list to check that
couchbaseis enabled.
Logs: in the bottom panel, open Output and select Cursor MCP.
Open Command Palette > Windsurf MCP Configuration Panel, or Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (see Windsurf's MCP docs).
Click Add Server > Add custom server, paste the configuration and save.
Refresh the server list to check that
couchbaseis enabled.
VS Code uses servers as the top-level key instead of mcpServers. Put the configuration in .vscode/mcp.json for a workspace, or run MCP: Open User Configuration for all workspaces (see VS Code's MCP docs):
{
"servers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}Saving the file starts the server; use the Running | Stop | n Tools actions above it to manage it.
Logs: run MCP: List Servers, pick couchbase, then Show Output.
Install the AI Assistant or Junie plugin.
Go to Settings > Tools > AI Assistant (or Junie) > MCP Server, click +, add the configuration and click Apply.
Hover over the server's status to see its tools.
Logs: Help > Show Log in Finder (Explorer) > mcp > couchbase.
Docker
Prebuilt images are published to Docker Hub as couchbase/mcp-server, and the server is listed in the Docker MCP Catalog. Configure the container with the same environment variables as above. See the Docker Hub page (DOCKER.md) for tags, volumes and health-check examples.
Running over HTTP — note that the server must bind to 0.0.0.0 to be reachable from outside the container:
docker run --rm \
-e CB_CONNECTION_STRING='<couchbase_connection_string>' \
-e CB_USERNAME='<database_user>' \
-e CB_PASSWORD='<database_password>' \
-e CB_MCP_TRANSPORT=http \
-e CB_MCP_HOST=0.0.0.0 \
-p 8000:8000 \
couchbase/mcp-server:latest operationalIf Couchbase runs on your host machine, use
couchbase://host.docker.internalas the connection string (see Docker networking). Use--network=<your_network>to join another container's network.Append
operational-insightsinstead ofoperationalto run the Operational Insights server (port8001).
docker build -t mcp/couchbase-src ../build.sh [image-name] builds with the same arguments as CI — it sets the GIT_COMMIT_HASH and BUILD_DATE build args and tags the image latest and <short-commit> (default name mcp/couchbase-src). To build with the labels by hand:
docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
--build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
-t mcp/couchbase-src .
# Check the labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latestTroubleshooting
For full guides, see the troubleshooting documentation for the operational server and the Operational Insights server, and the security guidelines for the operational server and the Operational Insights server. Quick checks:
Check the connection string, username/password or certificate paths.
For Capella, make sure the cluster allows connections from the machine running the server.
Make sure the database user can access at least one bucket.
If the client can't find
uv/uvx, put the absolute path incommand.When running from source, check the repository path in the configuration, and run
uv syncafter pulling updates.Call
get_server_configuration_statusto see the configuration the server actually resolved, and check your client's logs (see Client Setup).
FAQ
How do I connect Claude Desktop to Couchbase? Add the quick start configuration to claude_desktop_config.json and restart Claude Desktop — see Client Setup.
Can I use this with Couchbase Capella? Yes, with the operational server: the same configuration works for Capella and self-managed clusters, though a few admin tools are only available on self-managed clusters (see Tools). The Operational Insights server is for self-managed Operational Insights clusters only.
Is it safe to let an AI agent write to my database? By default, no write tools are loaded and modifying SQL++ is blocked. If you enable writes, you can still disable individual tools or require confirmation — but your Couchbase user's RBAC permissions remain the real security boundary. See Safety Controls.
Do I need to know SQL++? No. Ask in plain English and the assistant writes the SQL++ for run_sql_plus_plus_query. It can also explain a query plan or ask the Index Advisor for recommendations.
STDIO or Streamable HTTP? STDIO for a single local client. Streamable HTTP to share one server between clients, with OAuth. See Transports.
Is this officially supported by Couchbase? Yes, with a Couchbase AI Data Plane license. Without one, Couchbase engineers help on a best-effort basis through GitHub issues. See Support Policy.
Contributing
Contributions are welcome — bug fixes, features and documentation. To report a bug or ask for help, open a GitHub issue.
See CONTRIBUTING.md for development setup, linting, testing, project structure and workflow. To get started:
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase
uv sync --extra dev
uv run pre-commit install
./scripts/lint.shIntegration tests run against a live cluster. Export CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD and optionally CB_MCP_TEST_BUCKET; the Operational Insights tests also use CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / _USERNAME / _PASSWORD and are skipped when those are unset. Then run:
uv run --extra dev pytest tests/integration -vUsage Data, LLM Risks and Support Policy
Usage Data Collection
This product automatically collects usage and performance data (such as product name and version) and browser information (such as IP address) (collectively, "Usage Data"). Couchbase uses Usage Data, along with other data you may provide to Couchbase (such as your user name or email address), to develop and improve our products as well as inform our sales and marketing programs. We do not access or collect any data you store in Couchbase products. We use Usage Data to understand aggregate usage patterns and make our products more useful to you. For more information on how Couchbase collects, protects, and processes information, please refer to the Couchbase Privacy Policy viewable at https://www.couchbase.com/privacy-policy.
Risks Associated with LLMs
The use of large language models and similar technology involves risks, including the potential for inaccurate or harmful outputs.
Couchbase does not review or evaluate the quality or accuracy of such outputs, and such outputs may not reflect Couchbase's views.
You are solely responsible for determining whether to use large language models and related technology, and for complying with any license terms, terms of use, and your organization's policies governing your use of the same.
Support Policy
Couchbase MCP Server is open source and maintained by Couchbase engineers. How you get help depends on how you use it:
Community use — report bugs, ask questions and request features by opening a GitHub issue. Couchbase engineers monitor the repository and respond on a best-effort basis, with no response-time commitment. The Couchbase support portal cannot help with community use.
Enterprise support — available by licensing Couchbase AI Data Plane, which also covers Couchbase Agent Memory and Couchbase Agent Catalog. Licensed customers get help through their usual Couchbase Support channels.
Thank you for using and contributing to the project!
Available Tools
36 toolsdiscover_tool_input_valuesARead-only
Find the exact input values a specific tool requires, from reference data bundled with this server.
Call this BEFORE calling a tool that needs an exact identifier you do not already know. Do not guess the identifier and do not browse the Couchbase documentation website for it -- a guessed value comes back from the target tool as an error with no data. The reference data ships inside this server, so this works offline and while the cluster is unreachable, which is exactly when you are most likely to be looking up a metric name.
Registered today:
tool_name="get_cluster_metrics" -> every Couchbase Server metric name, with its type (counter/gauge/histogram), unit, the server version it first appeared in, and a one-line description. Feed a result's "name" straight into get_cluster_metrics.
tool_name is the only required argument; everything else is optional.
Two ways to call it:
Browse -- pass tool_name alone. Every registered dataset is currently treated as too large to list in full, so this returns "record_count", a small "sample_records" preview, the "chapters" block (the small set of fields you can filter on, with every legal value and a record count each), and a "next_step" pointing you at search instead of a partial list.
Search -- pass tool_name and search_keywords. Returns records ranked by fuzzy relevance, best first. Matching is fuzzy over identifiers and descriptions, so partial words and near-misses still hit.
Every response includes the chapters block, so you never need a separate browse call before narrowing.
Inputs: tool_name (required), min_score, max_results, chapter_filters, +1 more. Returns: object
explain_sql_plus_plus_queryARead-only
Generate and evaluate an EXPLAIN plan for a SQL++ query. It provides information about the execution plan for the query.
The EXPLAIN statement is run in the specified scope in the specified bucket. It returns query metadata along with an extracted plan and plan evaluation.
Inputs: query (required), scope_name (required), bucket_name (required). Returns: object
get_active_queriesARead-only
Get all queries executing right now, across every query-service node.
Use this to find a runaway or stuck statement: elapsed time, the statement text, the client, and current state. Pair with get_cluster_query_vitals to confirm the engine is actually under load from what this returns, and pass a result's "requestId" to delete_active_query to cancel it.
Calls GET /admin/active_requests. Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs at minimum the Read-Only Admin (ro_admin) role — verify against your cluster's RBAC before relying on this in production.
/admin/active_requests answers per node — a request only shows up when the node running it is asked — so every query-service node is queried and the lists are merged into one. Each entry already carries its own "node" field, so there is no need to tag entries by which endpoint answered.
Returns {"status": "success", "active_requests": [...merged...], "unreachable_nodes": [{"node", "error"}]} (the last key omitted when every node answered), or {"status": "error", "error": ...} if no query node could be reached at all, or the cluster is Capella.
Inputs: timeout. Returns: object
get_bucket_configARead-only
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.
Inputs: timeout, bucket_name. Returns: result
get_buckets_in_clusterARead-only
Get the names of all the accessible buckets in the cluster.
Inputs: no named parameters. Returns: result
get_client_connectivity_reportARead-only
Check whether the client's connections were already broken, and for how long.
Unlike get_cluster_health_and_services (which actively pings each service right now), this reports the SDK's own cached connection state without performing any network I/O. It's cheap enough to call frequently, but it's only as fresh as the last time the SDK actually talked to each node — it won't proactively detect a service that just went down if nothing has touched it since. Use get_cluster_health_and_services instead when you need a live, right-now reachability check; there's also no way to filter this report to specific services the way that tool's ping can, since no I/O means nothing to filter.
For each known endpoint, reports which service it belongs to, its remote/local addresses, connection state, and last_activity — how long it's been since that connection last saw traffic. Also reports an overall online/degraded/offline cluster state.
This call makes no request to the server at all, so it needs no specific RBAC role beyond whatever the initial cluster connection already required — unlike an active ping, it isn't gated on KV/Query/Search or Cluster Admin privileges.
Returns:
Diagnostics report with per-endpoint connection state and overall cluster state
Inputs: no named parameters. Returns: object
get_cluster_health_and_servicesARead-only
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
Inputs: bucket_name, service_types. Returns: object
get_cluster_health_snapshotARead-only
Get per-node service topology, membership, orchestrator and health in one call.
Use this to turn a symptom into a specific node and service: which node is in "warning", what it runs, whether it is still in the cluster, and whether it is the orchestrator — i.e. whether acting on it is disruptive. Also answers "did a topology change leave us in a good state?" after a node replacement or failover.
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:
cluster.unhealthy_nodes / inactive_nodes are the fast path: a node is in unhealthy_nodes when status is not "healthy", and in inactive_nodes when it is no longer an "active" member (e.g. "inactiveFailed" — already failed over, which is a different situation from an active node merely reporting "warning").
safe_to_act_on is false only for the orchestrator, where a restart or failover is disruptive in a way it is not elsewhere. When cluster.orchestrator_known is false no node could be flagged, so read safe_to_act_on as "unknown", not "yes" — the cluster reports no orchestrator while one is being elected.
reachable_address is the address to probe next, chosen between the node's internal and externally advertised addresses based on which one this server reached the cluster on. Probing the other form may fail for network reasons that look like a node outage; alternateAddresses keeps it as a fallback.
cluster.counters holds lifetime rebalance tallies: rebalance_start above rebalance_success means a rebalance began and did not finish — the signature of an interrupted topology change. Pair with get_cluster_tasks for what is running now.
recoveryType other than "none" means a recovery is in progress: not healthy yet, rather than broken.
Returns {"cluster": {...}, "nodes": [...]}; raises on failure.
Inputs: timeout. Returns: object
get_cluster_metricsARead-only
Get one or more cluster statistics over a historic time window in a single call.
Use this to quantify a suspected problem (e.g. after get_cluster_health_and_services or get_client_connectivity_report) — is a metric spiking, climbing, or stable over time?
Self-managed Couchbase Server 7.6+ only — rejects Capella connections without a REST call. Calls POST /pools/default/stats/range.
metrics is passed through as the request body: a list of specs, each with a required
"metric" (list of {"label", "value"} pairs, e.g. [{"label": "name", "value":
"kv_ep_diskqueue_fill"}]), an optional "nodes" ("host:port" targets; omit it to cover every
node, which is usually what you want), and optional "applyFunctions",
"nodesAggregation", "start"/"end" (negative seconds relative to now; default -60/now),
"step" (seconds, default 10), "alignTimestamps".
To find metric names, call discover_tool_input_values(tool_name="get_cluster_metrics") — it lists or searches the full Couchbase metrics reference bundled with this server, offline. Don't guess a metric name: an unknown name comes back as a per-spec error with no data.
Not bounded: any number of specs, window, step, or node count is passed straight through to the REST call, so a broad request (long window, fine step, many nodes/specs) can return a large response.
Returns {"status": "success", "data": [...]} (one entry per spec, each with "data" and any per-spec "errors") or {"status": "error", "error": "..."}.
Inputs: metrics (required), timeout. Returns: object
get_cluster_query_vitalsARead-only
Get query-engine health (vitals) from every query-service node.
Distinguishes "the workload is heavy" from "the query engine itself is stressed" — get_cluster_metrics covers node hardware; this covers the N1QL service layer specifically: request rate, active/queued request counts, memory, GC, service uptime. Use it after get_cluster_metrics/ get_cluster_health_snapshot show healthy infra but queries are still slow.
Calls GET /admin/vitals. Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs at minimum the Read-Only Admin (ro_admin) role — verify against your cluster's RBAC before relying on this in production, since the N1QL Admin API's exact privilege requirements are not fully documented.
/admin/vitals answers per node, not cluster-wide — each query node only describes itself — so every query-service node is queried and the results are keyed by node ("host:port").
Returns {"status": "success", "vitals": {"host:port": {...}, ...}, "unreachable_nodes": [{"node", "error"}]} (the last key omitted when every node answered), or {"status": "error", "error": ...} if no query node could be reached at all, or the cluster is Capella.
Inputs: timeout. Returns: object
get_cluster_system_eventsARead-only
Get the cluster's system event log — what changed on the cluster, and when.
This is the RCA timeline: once a symptom is confirmed, it finds the config change, failover, rebalance or service restart that preceded it. Window it to the symptom's onset with since_time, then cross-check that timestamp against get_cluster_metrics.
Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs the Full Admin or Cluster Admin role. Calls GET /events.
Ordering — easy to misread:
Events are ALWAYS oldest-first, but which ones the server picks depends on since_time. Without it, the server takes the
limitMOST RECENT events, so the last element is the newest thing on the cluster. With it, it takes thelimitEARLIEST events at or after that time, so the last element is NOT the newest — more may follow it.Do not re-sort or re-slice to get "the latest N": slicing keeps the oldest. Lower
limitand let the server choose.To page forward, pass summary.next_since_time as the next since_time. It is inclusive, so the boundary event repeats — dedupe on uuid. When it is null on a truncated result, check summary.paging_blocked: every event in the batch shares one timestamp, so sinceTime cannot move past them and a higher limit is the only way to see the rest.
A cluster's log is overwhelmingly "info", so expect routine entries in the window; move
the window rather than raising limit.
Reading the result:
summary.by_severity / by_component say what the window holds at a glance, so a lone "error" among routine entries is visible without reading every event.
summary.possibly_truncated means the server filled the limit, so more events probably exist outside the window. Absence of a later event is not evidence.
The log is a ring buffer (10,000 entries by default), so an empty result for an old since_time can mean the events aged out, not that nothing happened.
Returns {"summary": {...}, "events": [...]}; raises on failure.
Inputs: limit, timeout, since_time. Returns: object
get_cluster_tasksARead-only
Get the cluster tasks running right now — rebalance, compaction, XDCR, index build.
Answers "what is this cluster doing?" — where stuck rebalances, hung index builds and lagging XDCR surface. One call is a single sample, so pair it with get_cluster_metrics to tell "slow but progressing" from "flatlined".
Calls GET /pools/default/tasks. Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs the Read-Only Admin (ro_admin) role.
Returns the endpoint's array unchanged, or [] if no tasks are reported. Only "type" and "status" are common to every entry; the rest are per type — rebalance: progress, perNode, detailedProgress, stageInfo, subtype; bucket_compaction: bucket, progress, changesDone, totalChanges; xdcr: changesLeft, docsChecked, docsWritten, source, target; global_indexes/indexer: bucket, index, progress, id; loadingSampleBucket: task_id, bucket, bucket_uuid.
Reading the result:
An idle cluster still reports a rebalance entry with status "notRunning", so check each task's "status" rather than counting entries.
"statusIsStale": true means the cluster cannot vouch for that status — read it as "unknown", not "stuck". Flatlined progress and a status that stopped updating look identical here but mean different things.
"progress" means different things per type, so do not compare it across tasks.
Poll no faster than "recommendedRefreshPeriod" (seconds), the server's own hint.
"cancelURI"/"lastReportURI" are informational UI links; this tool only ever GETs and never invokes them.
Inputs: timeout. Returns: result
get_collections_in_scopeARead-only
Get the names of all collections in the given scope and bucket.
Inputs: scope_name (required), bucket_name (required). Returns: result
get_document_by_idARead-only
Get a document by its ID from the specified scope and collection. If the document is not found, it will raise an exception.
Inputs: scope_name (required), bucket_name (required), document_id (required), collection_name (required). Returns: object
get_index_advisor_recommendationsBRead-only
Get index recommendations from Couchbase Index Advisor for a given SQL++ query.
The Index Advisor analyzes the query and provides recommendations for optimal indexes. This tool works with SELECT, UPDATE, DELETE, or MERGE queries. The queries will be run on the specified scope in the specified bucket.
Returns a dictionary with:
current_used_indexes: Array of currently used indexes (if any)
recommended_indexes: Array of recommended secondary indexes (if any)
recommended_covering_indexes: Array of recommended covering indexes (if any)
Each index object contains:
index: The CREATE INDEX SQL++ command
statements: Array of statement objects with the query and run count
Raises an error carrying the advisor's message if the advisor cannot analyse the statement (for example, a SQL++ syntax error).
Inputs: query (required), scope_name (required), bucket_name (required). Returns: object
get_index_statsARead-only
Get per-index statistics (size, fragmentation, scan traffic) from the Index Service.
Names which index is responsible for disk or memory pressure — use it after get_cluster_metrics shows a node's index disk climbing.
Filters are hierarchical: scope requires bucket, collection requires both, index requires all three. No filters returns every index in the cluster.
Returns nodes (keyed by node, each with an indexer block and an
indexes list of bucket/scope/collection/name + stats),
nodes_without_index (nodes that answered but do not hold the requested
index — expected, since an index lives only where it was placed) and
nodes_failed (nodes that could not be reached, so a partial answer is
visible as one). indexer is None for filtered calls.
Numbers are per node. A partitioned index appears under several nodes, each
reporting only its own share: sum items_count/data_size/disk_size
across nodes, but not num_requests, which every hosting node counts in
full.
Reading the stats: disk_size far above data_size (see
frag_percent) means space reclaimable by compaction; num_requests
with last_known_scan_time (Unix ns, 0 = never) identifies unused
indexes; num_docs_pending is indexing lag. Counters reset when the
indexer restarts, so a low count alone does not prove an index is unused.
skip_empty=True drops zero-valued fields (~two thirds on an idle
cluster) — leave it False when hunting unused indexes, since it also removes
num_requests: 0.
Inputs: index_name, scope_name, skip_empty, bucket_name, +1 more. Returns: object
get_longest_running_queriesARead-only
Get the N longest running queries from the system:completed_requests catalog.
Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.
Inputs: limit. Returns: result
get_most_frequent_queriesARead-only
Get the N most frequent queries from the system:completed_requests catalog.
Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.
Inputs: limit. Returns: result
get_queries_not_selectiveARead-only
Get queries that are not very selective from the system:completed_requests catalog.
Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.
Inputs: limit. Returns: result
get_queries_not_using_covering_indexARead-only
Get queries that don't use a covering index from the system:completed_requests catalog.
Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.
Inputs: limit. Returns: result
get_queries_using_primary_indexARead-only
Get queries that use a primary index from the system:completed_requests catalog.
Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.
Inputs: limit. Returns: result
get_queries_with_large_result_countARead-only
Get queries with the largest result counts from the system:completed_requests catalog.
Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.
Inputs: limit. Returns: result
get_queries_with_largest_response_sizesARead-only
Get queries with the largest response sizes from the system:completed_requests catalog.
Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.
Inputs: limit. Returns: result
get_schema_for_collectionARead-only
Get the schema for a collection in the specified scope. Returns a dictionary with the collection name and the schema returned by running INFER query on the Couchbase collection.
num_sample_values sets how many example values INFER reports per field. Leave it unset to use the server's own default (5). Pass 0 to omit sample values entirely, keeping only the structure and type information.
Inputs: scope_name (required), bucket_name (required), collection_name (required), num_sample_values. Returns: object
get_scopes_and_collections_in_bucketARead-only
Get the names of all scopes and collections in the bucket. Returns a dictionary with scope names as keys and lists of collection names as values.
Inputs: bucket_name (required). Returns: object
get_scopes_in_bucketARead-only
Get the names of all scopes in the given bucket.
Inputs: bucket_name (required). Returns: result
get_search_index_definitionARead-only
Get the full definition of a single Search (FTS) index.
Pass both bucket_name and scope_name together to look up a scope-level (scoped) index in that scope, or omit both to look up a cluster-level ("legacy") index. Passing only one of the two is invalid — Couchbase allows the same index name to exist in different scopes, so the location must be stated explicitly rather than guessed.
Returns {"success": True, "name", "source_type", "idx_type", "source_name", "uuid", "params" (mapping/analyzer configuration), "source_uuid", "source_params", "plan_params" (num replicas/partitions), "bucket", "scope"}. If no index with this name exists at the given location, returns {"success": False, "error": ...} — confirm the exact name and location first with list_search_indexes.
Inputs: index_name (required), scope_name, bucket_name. Returns: object
get_server_configuration_statusARead-only
Get the server status and configuration without establishing connection. This tool can be used to verify if the server is running and check the configuration.
Inputs: no named parameters. Returns: object
list_indexesARead-only
List indexes in the cluster with optional filtering by bucket, scope, collection, and index name.
Filters must be provided hierarchically: scope requires bucket, collection requires both, index requires all three.
Set return_raw_index_stats=True to get the unprocessed source row for each index.
Each result contains: name, definition (CREATE INDEX statement), status, isPrimary, bucket, scope, collection, lastScanTime, is_vector (True for a Hyperscale or Composite Vector Index), and, only when is_vector is True, vector_type ("hyperscale" or "composite"). If a required field is missing, the entry contains warning and raw_index_stats instead.
Source depends on cluster version: v8+ queries system:indexes via the
query service (RBAC-scoped — the connected user sees only indexes on
keyspaces they can access); older clusters fall back to the admin-level
Index Service REST API /getIndexStatus.
Inputs: index_name, scope_name, bucket_name, collection_name, +1 more. Returns: result
list_search_indexesARead-only
List Search (FTS) indexes, optionally filtered by bucket and scope.
Filtering behavior:
No filters: lists cluster-level ("legacy") Search indexes only — the original, pre-scoped FTS index model, defined at the cluster level.
bucket_name only: lists scope-level (scoped) Search indexes across every scope in that bucket.
bucket_name and scope_name: lists scope-level Search indexes in that one scope only.
scope_name without bucket_name is invalid — returns an error entry explaining that bucket_name is required.
Each entry contains: name, uuid, source_name, source_type, idx_type, bucket, scope. bucket/scope are None for cluster-level (legacy) entries. This is a summary view — to get one index's full definition (mappings, analyzers, plan params), call get_search_index_definition with that entry's name and its own bucket/scope values (both, for a scoped entry; neither, when they're None). Don't reuse this call's filters: listing by bucket_name alone spans several scopes, and get_search_index_definition rejects a bucket without a scope.
Inputs: scope_name, bucket_name. Returns: result
lookup_subdocumentARead-only
Look up parts of a document without fetching the whole thing, using Couchbase sub-document operations. Use this instead of get_document_by_id when you only need a few fields, a presence check, or the size of an array/object inside a document — AND you already know the exact field path(s) to look up (e.g. from a prior get_document_by_id call on this same document, from the user explicitly naming the field, or from a known/confirmed schema for this collection).
IMPORTANT: Do NOT guess field paths. If you don't already know the document's exact field names/structure, call get_document_by_id first (or instead) — a guessed path that doesn't exist returns a per-path error here rather than the real data, and reporting "not found" for a wrong guess is worse than just fetching the whole document and reading the right field.
Provide one or more of the following. Each is a list of sub-document paths using Couchbase's dot/bracket path syntax (e.g. "address.city", "tags[0]", "tags[-1]" for the last array element):
get_paths: fetch the VALUE at each path.
exists_paths: check whether each path exists, without fetching its value (cheaper than get_paths — no payload transfer — when you only need a yes/no answer).
count_paths: get the number of elements in the array or object at each path (fails per-path if the path isn't an array/object).
At least one of get_paths, exists_paths, or count_paths must be provided. As a rule of thumb, keep the combined number of paths across all three to 16 or fewer — Couchbase limits subdocument operations per call, though the exact limit is server-side and may change. If the server rejects the call (too many paths, or another constraint like path length or nesting depth), the whole call fails with {"error": "..."}.
A path that doesn't exist (or otherwise fails, e.g. count on a non-array/object) does NOT fail the whole call — it is reported individually as {"error": ...} in the returned dict so the other requested paths can still be resolved.
Returns a dict with a key for each category that was requested (only requested categories are included): { "get": {"": {"value": } | {"error": "..."}}, "exists": {"": {"value": true | false} | {"error": "..."}}, "count": {"": {"value": } | {"error": "..."}}, } On a connection/lookup failure, or an invalid request (no paths / too many paths), returns {"error": ""} instead.
Inputs: scope_name (required), bucket_name (required), document_id (required), collection_name (required), +3 more. Returns: object
run_searchARead-only
Run an FTS (Search) query against a Search index, or fetch its execution plan.
Use this instead of run_sql_plus_plus_query's SEARCH() function when you need relevance-scored, fuzzy, or linguistic full-text matching (scoring, highlighting, faceting, fuzzy/phrase/wildcard matching) — SQL++ can invoke FTS predicates too, but this tool gives clearer tracing of what data was searched and keeps FTS-specific result shape (score, fragments, facets) out of general query results.
query is the raw FTS query JSON body, passed through unvalidated to the Search service — this supports every non-vector FTS query type, e.g.:
{"match": "ale", "field": "type"}
{"conjuncts": [{"match": "ale"}, {"term": "beer", "field": "type"}]}
{"query": "type:beer +name:ale"} (query_string) Vector search is NOT supported by this tool (separate feature).
Pass both bucket_name and scope_name together to query a scope-level (scoped) index, or omit both to query a cluster-level ("legacy") index. Passing only one is invalid. Confirm the index's exact name/location first with list_search_indexes. Don't guess which fields a query body can target — if you don't already know what the index maps and how those fields are analyzed, call get_search_index_definition first; a field-scoped query against an unmapped field matches nothing rather than erroring. Note this only works for indexes with explicit static field mappings — a dynamically mapped index (dynamic: true) has no fixed field list to inspect, since it indexes whatever fields appear in each document; for those, look at actual document contents instead to know what's queryable.
explain: if True, fetches the execution plan instead of normal results. The Search service exposes the query plan per matched document, not as a separate plan-only/ dry-run call — so explain=True still executes the query (with explain enabled) and returns the explanation for each returned hit. limit defaults to 1 in this mode to keep it cheap (pass a larger limit to see the plan for more matched documents), and skip/fields/sort/facets/highlight_fields/disable_scoring/raw are ignored — they only apply when explain=False.
limit/skip/fields/sort/facets/highlight_fields/disable_scoring map to the equivalent Search options. limit defaults to 10 when explain=False (matching the other query tools in this server) and to 1 when explain=True. raw is a passthrough dict for any other SearchOptions field not exposed directly (e.g. highlight_style, consistent_with).
Returns {"success": True, "index_name", "explain", "limit" (the limit actually applied, since it defaults differently depending on explain), "total_hits", "hits", "facets", "metadata": {"errors","metrics"}} on success, or {"success": False, "error": ...} if the input is invalid or the query fails (e.g. bad query syntax, index not found). total_hits counts the hits actually returned, so it is capped by limit — for how many documents matched overall, read metadata.metrics.total_rows instead, and don't report total_hits as the size of the match set. hits entries are {"id","score","fields","fragments"} when explain=False, or {"id","score","explanation"} when explain=True (facets is empty in that case).
Inputs: query (required), index_name (required), raw, skip, +9 more. Returns: object
run_sql_plus_plus_queryA
Run a SQL++ query on a scope and return the results as a list of JSON values.
The query will be run on the specified scope in the specified bucket. The query should use collection names directly without bucket/scope prefixes, as the scope context is automatically set.
Use named_parameters to bind values to $name placeholders in the
query instead of concatenating user input into the statement. This prevents
SQL++ injection
Example: query = "SELECT * FROM users WHERE age > 18" # Incorrect: "SELECT * FROM bucket.scope.users WHERE age > 18"
For creating a new index (scalar or vector), prefer the create_query_index tool over a raw CREATE INDEX statement here — it defers the build by default and tells you the recommended next step. Use list_indexes to check whether an index is online before relying on it in a query plan.
For relevance-scored, fuzzy, or linguistic full-text search (scoring, highlighting, faceting, fuzzy/phrase/wildcard matching), prefer run_search over SQL++'s SEARCH() function — it keeps FTS-specific result shape (score, fragments, facets) out of general query results and gives clearer tracing of what was searched.
Inputs: query (required), scope_name (required), bucket_name (required), named_parameters. Returns: result
run_vector_queryARead-only
Embed a query and run a vector similarity search against a GSI vector index.
Embedding: query_text is embedded using the model configured via CB_MCP_EMBEDDING_MODEL_PROVIDER/CB_MCP_EMBEDDING_MODEL/CB_MCP_EMBEDDING_MODEL_API_KEY/CB_MCP_EMBEDDING_MODEL_ENDPOINT (plus CB_MCP_EMBEDDING_MODEL_AWS_* for provider=bedrock). If no provider is configured, this tool returns {"success": False, "error": ...} explaining what to set -- it is not hidden from tool discovery when unconfigured.
Index selection: this tool queries a Couchbase 8.0+ GSI vector index (Composite Vector Index or Hyperscale Vector Index) via SQL++'s APPROX_VECTOR_DISTANCE(). Unlike Search-service vector search, GSI selects the index automatically from the vector field referenced in the query -- there is no index_name parameter, and none is needed.
distance_metric is required, deliberately with no default: it must match
the similarity the index was created with (CREATE INDEX ... WITH
{"similarity": ...}), or Couchbase silently falls back to not using the
Composite/Hyperscale Vector Index at all (no error -- the query still
returns correct results, just unindexed). There is no one value that's
usually right, since it depends entirely on how the specific index was
created, and this tool has no index_name to look that up automatically
(see above) -- call list_indexes first and read the similarity value
out of the matching index's definition field (valid values: cosine,
dot, l2/euclidean, l2_squared/euclidean_squared).
num_probes/rerank/top_n_scan are Hyperscale Vector Index tuning
parameters. num_probes (integer) is the number of centroids to probe --
raise it to improve poor recall. rerank (true/false) re-checks the top
candidates against the full vectors; it needs num_probes. top_n_scan
(integer) is how many candidates to rerank; it needs num_probes and
rerank. num_probes alone, or num_probes + rerank, are both valid. A
Composite Vector Index doesn't use any of them. This tool
itself has no index_name to check, but list_indexes now reports each
index's vector_type ("hyperscale" or "composite") -- check that first
if you need to know which shape will actually serve the query.
where is an optional raw SQL++ boolean expression (e.g. "doc.status = 'active'") appended to prefilter candidates before the vector ordering -- this tool only ever emits a SELECT, so, unlike run_sql_plus_plus_query, there is no write-guard for it to bypass. If the index was created with a partial-index condition (create_query_index's condition), where must match or imply it for the planner to actually use that index -- otherwise it falls back to a full scan silently (confirmed via EXPLAIN), the same footgun documented above for a mismatched distance_metric.
select_fields limits the projected document fields; omit it to return the full document. limit defaults to 10, matching the other query/search tools in this server.
Returns {"success": True, "hits": [{"id", "distance", "document": {... selected fields, or the full document}}], "total_hits", "cluster_major_version", and a "warning" key only when the detected cluster major version is below 8 (informational -- a pre-8.0 cluster fails the query naturally with its own "unknown function" error rather than being blocked here)} or {"success": False, "error": ...}. The document is nested under "document" rather than merged into the hit directly -- a document field literally named "id" or "distance" would otherwise silently collide with (and could overwrite) this tool's own id/distance metadata.
Inputs: query_text (required), scope_name (required), bucket_name (required), vector_field (required), +8 more. Returns: object
run_vector_searchARead-only
Run the Search service's vector search, including hybrid and prefiltered search.
Embedding: vector_query_text is embedded using the model configured via CB_MCP_EMBEDDING_MODEL_PROVIDER/CB_MCP_EMBEDDING_MODEL/CB_MCP_EMBEDDING_MODEL_API_KEY/CB_MCP_EMBEDDING_MODEL_ENDPOINT (plus CB_MCP_EMBEDDING_MODEL_AWS_* for provider=bedrock). If no provider is configured, this tool returns {"success": False, "error": ...} explaining what to set
Unlike run_vector_query's GSI-backed search, this tool always targets a named Search (FTS) index -- index_name is required. Pass both bucket_name and scope_name together to query a scope-level (scoped) index, or omit both to query a cluster-level ("legacy") index. Confirm the index's exact name/location first with list_search_indexes if unsure -- this tool does not pre-validate index_name; a wrong or non-vector index name fails naturally at the Search service with its own error.
scalar_query and prefilter are both optional and both take the same raw FTS query JSON body run_search accepts (e.g. {"match": "jacket", "field": "description"}), but they do different things -- do not confuse them:
scalar_query makes this a genuinely hybrid search: both the vector query and this scalar query are sent to the Search service together, and it ranks/combines their hits server-side (a document can match via either signal). is_hybrid in the response reflects whether this was set.
prefilter narrows which documents the vector search is even allowed to consider as nearest-neighbor candidates, evaluated before the k-nearest-neighbor search runs -- the Search-service equivalent of run_vector_query's
whereprefilter on a GSI Composite Vector Index. A document that doesn't match prefilter is never returned, regardless of vector similarity.
Both can be set together (prefilter narrows the candidate pool, then scalar_query's relevance signal still contributes to ranking within it). Omit both for a plain vector-only search through this tool (equivalent in intent to run_vector_query, but against a named Search index instead of a GSI vector index).
num_candidates bounds how many nearest-neighbor candidates the vector query considers; limit bounds how many hits the search as a whole returns, and both default to 10. For a vector-only search (no scalar_query), limit above num_candidates is a no-op -- there are never more than num_candidates vector hits to return. With scalar_query set, limit can meaningfully exceed num_candidates, since scalar_query's own matches aren't bounded by it. fields requests specific stored index fields per hit.
This tool does not fetch full document bodies -- a Search hit carries whatever fields the index stores (row.fields), the same as run_search, not a KV-fetched document (a hit has no reliable per-row collection name to fetch against). Follow up with get_document_by_id for any hit you need the full document for.
Returns {"success": True, "index_name", "vector_field", "num_candidates", "limit", "total_hits", "hits": [{"id", "score", "fields"}], "is_hybrid", "is_prefiltered"} or {"success": False, "error": ...}.
Inputs: index_name (required), vector_field (required), vector_query_text (required), limit, +6 more. Returns: object
test_cluster_connectionARead-only
Test the connection to Couchbase cluster and optionally to a bucket. This tool verifies the connection to the Couchbase cluster and bucket by establishing the connection if it is not already established. If bucket name is not provided, it will not try to connect to the bucket specified in the MCP server settings. Returns connection status and basic cluster information.
Inputs: bucket_name. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 36 tools
Most tools target clearly distinct resources/actions, and the descriptions do heavy lifting to separate read-only KV, SQL++, FTS, vector, index, and cluster-ops surfaces. A few pairs are genuinely easy to confuse: run_vector_query (GSI) vs run_vector_search (FTS), get_scopes_and_collections_in_bucket vs get_scopes_in_bucket/get_collections_in_scope, and the three cluster-health tools (health_and_services, health_snapshot, client_connectivity_report). The six query-analysis tools are individually named but form a dense cluster an agent must read carefully.
Names are uniformly snake_case and almost all follow verb_noun (get_, list_, run_, explain_, discover_, test_). Minor deviations: near-duplicate verbs for similar concepts (get_document_by_id vs lookup_subdocument, run_vector_query vs run_vector_search) which read consistently but blur intent. No camelCase or style mixing.
36 tools exceeds the 25+ threshold and the surface spans many domains (KV, SQL++, FTS, vector, indexes, cluster diagnostics). Several query-analysis tools (not_selective, not_using_covering_index, using_primary_index, large_result_count, largest_response_sizes, longest_running, most_frequent) could be consolidated into a single parameterized tool. The count feels heavy relative to what an agent can reliably pick from.
The read/investigation surface is broad and strong, but there are no document write tools (no insert/upsert/replace/delete) despite the server being KV-capable. Several tools reference operations that aren't in the surface: run_sql_plus_plus_query points to create_query_index, and get_active_queries points to delete_active_query — neither exists, creating dead-end references. Read-only by design, but the stated domain (a Couchbase MCP server) implies write/lifecycle coverage that's missing.
Maintenance
Related MCP Connectors
An MCP server for search and retrieval over a local LanceDB database
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables large language models to interact directly with MongoDB databases, allowing them to query collections, inspect schemas, and manage data through natural language.23 npmMIT
- AlicenseNot gradedqualityDmaintenanceA server that enables natural language interactions with Couchbase databases through the Model Context Protocol, allowing users to perform SQL++ queries on Couchbase Capella clusters using conversational commands.1MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables large language models to interact directly with Couchbase databases through natural language, supporting operations like querying buckets, performing CRUD operations, and executing N1QL queries.33 npm7MIT

YugabyteDB MCP Serverofficial
AlicenseNot gradedqualityCmaintenanceAn MCP server implementation that allows Large Language Models to directly interact with YugabyteDB databases, supporting table listing and read-only SQL queries.11Apache 2.0