Tools

reference

Reference of the tools the Couchbase MCP Server for Operational Insights exposes, grouped by category, with how the server handles large query results.

The Couchbase MCP Server for Operational Insights exposes several tools across multiple categories. The list of supported tools is constantly evolving, so see the README for the latest set of tools. Each tool is available to LLMs through the MCP protocol.

The Operational Insights server supports only self-managed deployments. For the Couchbase Server tools, see Couchbase Server Tools.

Server Status

Tool for checking server status. It’s shared with the Couchbase Server server, so it keeps its name without an operational_insights_ prefix.

Source

Tool Description

Tool	Description
`get_server_configuration_status`	Get the server status and configuration without connecting to the cluster. The tool reports read-only mode, the tools that are turned off or need confirmation, OAuth settings, the resolved logging configuration, and the audit logging counters. It shows the connection string and username in clear text. For the password and certificates, it shows only whether they’re set.

get_server_configuration_status

Get the server status and configuration without connecting to the cluster. The tool reports read-only mode, the tools that are turned off or need confirmation, OAuth settings, the resolved logging configuration, and the audit logging counters. It shows the connection string and username in clear text. For the password and certificates, it shows only whether they’re set.

Data Model & Schema Discovery

Tools for exploring databases, scopes, collections, and document schemas.

Source

Tool Description

Tool	Description
`operational_insights_get_databases_in_cluster`	Get a list of all the databases in the cluster.
`operational_insights_get_scopes_in_database`	Get a list of all the scopes in the specified database.
`operational_insights_get_collections_in_scope`	Get a list of all the collections in the specified scope, including the type of each collection: `INTERNAL`, `EXTERNAL`, or `VIEW`. To list only stored or linked collections, filter out the `VIEW` rows.
`operational_insights_get_schema_for_collection`	Infer the JSON schema of a collection with the `ARRAY_INFER_SCHEMA` function, by sampling up to `sample_size` documents. The maximum is 10,000. By default, the tool returns the structure only. Use `num_sample_values` to add example values.

operational_insights_get_databases_in_cluster

Get a list of all the databases in the cluster.

operational_insights_get_scopes_in_database

Get a list of all the scopes in the specified database.

operational_insights_get_collections_in_scope

Get a list of all the collections in the specified scope, including the type of each collection: INTERNAL, EXTERNAL, or VIEW. To list only stored or linked collections, filter out the VIEW rows.

operational_insights_get_schema_for_collection

Infer the JSON schema of a collection with the ARRAY_INFER_SCHEMA function, by sampling up to sample_size documents. The maximum is 10,000. By default, the tool returns the structure only. Use num_sample_values to add example values.

Query and Index

Tools for running SQL++ queries, managing async queries, and working with indexes. For how to limit or export large query results, see Large Result Handling. Read-only mode turns off operational_insights_create_index by default. All the other tools stay available in read-only mode, including operational_insights_cancel_async_query.

The async query tools are stateful. The server keeps each query handle in the memory of one process, so a restart loses all handles. If you run more than one Operational Insights server behind a load balancer, route all requests for a handle to the same server. For symptoms and fixes, see Async Query Issues.

Source (query) | Source (index)

Tool Description

Tool	Description
`operational_insights_list_indexes`	List the secondary indexes that users created, optionally filtered by database, scope, and collection. The tool does not list primary indexes, optimizer samples, or internal System indexes.
`operational_insights_explain_query`	Get the query plan for a SQL++ statement with EXPLAIN, without running it. Pass the statement without the `EXPLAIN` keyword.
`operational_insights_run_query_sync`	Run a SQL++ statement and return its result rows, up to the size limit that you configure. The statement can be SELECT, DML, or DDL. To send a large result to object storage instead, use the `copy_to_*` arguments. See Large Result Handling.
`operational_insights_run_query_async`	Start a SQL++ query without waiting for it to finish. The tool returns a `query_handle` and no rows. The query holds server resources until you discard its results or cancel it. It also supports the `copy_to_*` arguments.
`operational_insights_get_async_query_results`	Check the status of an async query and get its results once it finishes. While the query runs, the tool returns `ready: false` and no rows. When the query finishes, the tool returns `ready: true` with the rows. Calling the tool again does not consume the results.
`operational_insights_discard_async_query_results`	Free the results of a finished async query on the server. Fetching results does not free them. If the query is still running, the tool returns `discarded: false`, and you can cancel the query instead.
`operational_insights_cancel_async_query`	Stop an async query that’s still running. The query handle stops working. If the query already finished, the tool returns `cancelled: false` and keeps the handle, so you can discard the results. Available in read-only mode.
`operational_insights_create_index`	Create a secondary index with `CREATE INDEX`. The tool supports composite indexes and array indexes.

operational_insights_list_indexes

List the secondary indexes that users created, optionally filtered by database, scope, and collection. The tool does not list primary indexes, optimizer samples, or internal System indexes.

operational_insights_explain_query

Get the query plan for a SQL++ statement with EXPLAIN, without running it. Pass the statement without the EXPLAIN keyword.

operational_insights_run_query_sync

Run a SQL++ statement and return its result rows, up to the size limit that you configure. The statement can be SELECT, DML, or DDL. To send a large result to object storage instead, use the copy_to_* arguments. See Large Result Handling.

operational_insights_run_query_async

Start a SQL++ query without waiting for it to finish. The tool returns a query_handle and no rows. The query holds server resources until you discard its results or cancel it. It also supports the copy_to_* arguments.

operational_insights_get_async_query_results

Check the status of an async query and get its results once it finishes. While the query runs, the tool returns ready: false and no rows. When the query finishes, the tool returns ready: true with the rows. Calling the tool again does not consume the results.

operational_insights_discard_async_query_results

Free the results of a finished async query on the server. Fetching results does not free them. If the query is still running, the tool returns discarded: false, and you can cancel the query instead.

operational_insights_cancel_async_query

Stop an async query that’s still running. The query handle stops working. If the query already finished, the tool returns cancelled: false and keeps the handle, so you can discard the results. Available in read-only mode.

operational_insights_create_index

Create a secondary index with CREATE INDEX. The tool supports composite indexes and array indexes.

For AI agents:

Tools

Server Status

Data Model & Schema Discovery

Query and Index

See Also