Read-Only Mode

The MCP server provides configuration options for controlling write operations, ensuring safe interaction between LLMs and your database. Use this mode to start in a safe default that prevents data mutations by not loading write-capable tools; see the Security page for best practices. This mode is enabled by default.

Affected Tools

When read-only mode is enabled, the following tools are affected:

Tool	Description
upsert_document_by_id	Insert or update a document by ID
insert_document_by_id	Insert a new document by ID
replace_document_by_id	Replace an existing document by ID
delete_document_by_id	Delete a document by ID
run_sql_plus_plus_query	Run SQL++ queries that modify data

Read-Only Mode (Recommended)

This is the primary server-side safety switch (CB_MCP_READ_ONLY_MODE) — defense-in-depth on top of database RBAC, which remains the authoritative boundary:

• When true (default): All write operations are disabled. KV write tools (upsert, insert, replace, delete) are not loaded and will not be available to the LLM. SQL++ queries that modify data are also blocked.

• When false: KV write tools are loaded and available. SQL++ write queries are allowed.

Mode Behavior

READ_ONLY_MODE	Result
true (default)	Read-only KV and Query operations. All writes disabled.
false	All KV and Query operations allowed.

important

CB_MCP_READ_ONLY_MODE=true is the recommended safe default to prevent inadvertent data modifications by LLMs.

Configuration Example

To enable write operations:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://your-connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_READ_ONLY_MODE": "false"
      }
    }
  }
}

Security Guidelines

• Read-only mode is a defense-in-depth feature, not the primary security boundary.

• The authoritative control is Couchbase RBAC: You should configure database user permissions so that the credentials used by the MCP server simply do not have data modification privileges if you want strong guarantees. See RBAC for Couchbase Server or RBAC for Capella.