Read-Only Mode

reference

Control write access to your Couchbase cluster from the MCP server; enabled by default for safety.

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.

Tools Affected by Read-Only Mode

The following tools are disabled when CB_MCP_READ_ONLY_MODE is true (the default):

Tool Description

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
`mutate_subdocument`	Mutate one or more paths in a document
`run_sql_plus_plus_query`	Run SQL++ queries that modify data
`create_index`	Create a non-vector GSI index
`build_index`	Build a deferred index
`drop_index`	Drop an existing index
`create_scope`	Create a new scope
`create_collection`	Create a new collection
`delete_scope`	Delete an existing scope
`delete_collection`	Delete an existing collection

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

mutate_subdocument

Mutate one or more paths in a document

run_sql_plus_plus_query

Run SQL++ queries that modify data

create_index

Create a non-vector GSI index

build_index

Build a deferred index

drop_index

Drop an existing index

create_scope

Create a new scope

create_collection

Create a new collection

delete_scope

Delete an existing scope

delete_collection

Delete an existing collection

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. SQL++ queries that modify data are also blocked.
When false: All tools are loaded and available. SQL++ write queries are allowed.

Mode Behavior

READ_ONLY_MODE Result

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

true (default)

Read-only KV and Query operations. All writes disabled.

false

All KV and Query operations allowed.

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 do not have data modification privileges if you want strong guarantees. See RBAC for Couchbase Server or RBAC for Capella.