Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Architecture

  • concept
Component breakdown and request flow for the Couchbase MCP Server’s Operational Insights topology.

The Couchbase MCP Server for Operational Insights is a self-hosted bridge between AI agents and a Couchbase Operational Insights endpoint. It follows a three-tier topology — MCP Client → MCP Server → Operational Insights Cluster. The server exposes Operational Insights capabilities as MCP tools, enforces authentication and safety controls, and talks to the cluster through the couchbase-operational-insights Python SDK. Clients connect over one of two transports: stdio (local subprocess) or Streamable HTTP (networked, multi-client).

The Operational Insights MCP server supports only self-managed deployments. Capella-hosted Operational Insights is not supported.

This page covers the Operational Insights (operational-insights) server. For the components that both servers share, see Architecture.

How It Works — A Quick Example

The following example illustrates a typical request. An analyst asks: "Which databases do we have, and how many orders came in last month in the sales database?"

  1. On receiving the prompt, the agent first discovers what’s available by calling operational_insights_get_databases_in_cluster, then operational_insights_get_scopes_in_database and operational_insights_get_collections_in_scope for the sales database.

  2. It calls operational_insights_get_schema_for_collection to infer the real structure of the orders collection, rather than guessing field names.

  3. With the real schema known, it generates a SQL++ analytics query grounded in that schema.

  4. It submits the query with operational_insights_run_query_sync (or, for a long-running query, operational_insights_run_query_async followed by operational_insights_get_async_query_results), and the server returns the results over the MCP protocol.

Finally, the agent’s LLM shapes the result into a natural-language answer for the analyst. Notably, the model never touches the Operational Insights cluster directly — every data access goes through the MCP server.

Components & Responsibilities

Component Responsibility Learn more

MCP Client

The AI agent or IDE (VS Code, Claude Desktop, Cursor, …) that discovers and invokes tools.

Quick Start

Transport

How the client reaches the server: stdio (local subprocess) or Streamable HTTP (networked, serves /mcp).

Streamable HTTP

MCP Server

The server process (distributed via PyPI and Docker, built on the FastMCP SDK), running the operational-insights subcommand. Hosts the tools and enforces auth and safety controls.

Overview

Tool layer

The tools the server exposes — database, scope, and collection discovery, schema inference, and query execution/management — split into read and write tools.

Tools

Safety controls

Server-side gating of which tools load and run: read-only mode, disabled tools, and confirmation/elicitation.

Read-Only Mode · Security

OAuth resource server

On Streamable HTTP, verifies client JWTs (signature via JWKS, plus iss/aud/scopes) and optionally publishes PRM for discovery/DCR.

OAuth

couchbase-operational-insights SDK

The client library the server uses to perform SQL++ query operations against the Operational Insights cluster.

—

Operational Insights Cluster

A self-managed Couchbase Operational Insights deployment. RBAC on the server’s credentials is the authoritative data-access control.

Security

Identity Provider / Authorization Server

External service that authenticates users/agents and issues signed JWTs (exposes JWKS and issuer).

OAuth

Reverse proxy / TLS

For networked deployments, terminates TLS in front of the server so the connection encrypts traffic and tokens in transit.

Securing the Endpoint with TLS

Logging / observability

Structured logs with configurable level and sinks (stderr / file).

Logging

Network Path

The MCP server connects to the Operational Insights cluster over HTTP(S) via the couchbase-operational-insights SDK, typically port 8095 (HTTP) or 18095 (HTTPS).

Authentication Planes

The server has two independent authentication planes:

  • Client → Server: secured with OAuth (Streamable HTTP only). Decides which client may connect and which tools it may call.

  • Server → Operational Insights Cluster: uses your Operational Insights cluster credentials (Basic Auth or mTLS, set via CB_OPERATIONAL_INSIGHTS_* environment variables). Decides what data the server can actually touch.

They’re enforced separately, and RBAC on the Operational Insights cluster is the ultimate authority over data access. For details, see OAuth and Security.

SQL++ Read/Write Enforcement

In read-only mode, the server runs SQL++ statements with the server-side readonly query option, rather than client-side AST parsing. COPY …​ TO (export) statements are also blocked client-side.

See Also