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.

Environment Variables & Command Line Arguments

  • reference
Reference for all environment variables and CLI arguments used to configure the Couchbase MCP Server, including authentication examples.

You can configure the MCP server using environment variables or command line arguments. If you specify both, command line arguments take priority over environment variables.

Configuration Reference

Environment Variable CLI Argument Description Default

CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING

--connection-string

HTTP(S) URL of the Operational Insights cluster, for example http://localhost:8095 or https://<host>:18095. This is not a couchbase:// connection string. See Configuring Connection String.

Required

CB_OPERATIONAL_INSIGHTS_USERNAME

--username

Username for basic authentication. See Configuring Authentication.

Required (or mTLS)

CB_OPERATIONAL_INSIGHTS_PASSWORD

--password

Password for basic authentication. See Configuring Authentication.

Required (or mTLS)

CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH

--client-cert-path

Path to the client certificate for mTLS. Use either a PEM certificate (paired with the client key path) or a PKCS#12 bundle (.p12 or .pfx, with the client key path left unset). Requires an https:// connection string. When set, the server ignores the username and password. See Configuring Authentication.

Required if using mTLS

CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH

--client-key-path

Path to the client certificate’s private key file (PEM). Leave unset when the client certificate path is a PKCS#12 bundle that already contains the key. See Configuring Authentication.

Required for a PEM client certificate

CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD

--client-cert-password

Decryption password for the client key or PKCS#12 bundle, if it’s encrypted. Omit if the file is unencrypted.

None

CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH

--ca-cert-path

Path to the server trust store (CA certificate) file. The server uses it to verify the server certificate during authentication, for example with self-signed or untrusted certificates.

CB_MCP_READ_ONLY_MODE

--read-only-mode

Prevent all data modifications. See Read-Only Mode for details.

true

CB_MCP_TRANSPORT

--transport

Transport mode selection: stdio (client launches server as subprocess), http (Streamable HTTP - multiple clients, serves at /mcp)

stdio

CB_MCP_HOST

--host

Host for HTTP transport mode

127.0.0.1

CB_MCP_PORT

--port

Port for HTTP transport mode. Overrides the server default of 8001.

None

CB_MCP_WORKERS

--workers

Number of worker processes. The Operational Insights server supports only 1 and refuses larger values.

1

CB_MCP_STATELESS_HTTP

--stateless-http

Run HTTP transport mode without session state, for replicas behind a load balancer without sticky sessions. See Stateless Mode and Workers.

false

CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE

--operational-insights-query-result-max-size

Maximum size, in bytes, of a query tool result. Unset means no limit, and the full result comes back. When set, reading stops once the limit is reached, and the response reports truncated: true. Values greater than 4194304 (4 MB) are reduced to 4 MB with a warning. See Large Result Handling.

Unset

CB_MCP_OPERATIONAL_INSIGHTS_ASYNC_QUERY_RESULT_TIMEOUT

--operational-insights-async-query-result-timeout

Timeout, in seconds, for the requests that the async query tools make to the cluster. It must be a positive integer, and the maximum is 600. The server replaces any other value with the default, and reduces a larger value to 600. It logs a warning in both cases. See Timeout for Async Query Tools.

30

CB_MCP_DISABLED_TOOLS

--disabled-tools

Tools to disable. See Disabling Tools

None

CB_MCP_CONFIRMATION_REQUIRED_TOOLS

--confirmation-required-tools

Tools requiring user confirmation before execution. See Elicitation/Confirmation for Tool Calls

None

CB_MCP_OAUTH_JWT_JWKS_URI

--oauth-jwks-uri

JWKS endpoint for verifying JWT signatures (Streamable HTTP only). See OAuth.

None

CB_MCP_OAUTH_JWT_ISSUER

--oauth-issuer

Expected JWT iss (issuer) claim. See OAuth.

None

CB_MCP_OAUTH_JWT_AUDIENCE

--oauth-audience

Expected JWT aud (audience) claim. See OAuth.

None

CB_MCP_OAUTH_JWT_ALGORITHM

--oauth-algorithm

JWT signing algorithm. See OAuth.

RS256

CB_MCP_OAUTH_MCP_BASE_URL

--oauth-mcp-base-url

Public base URL of this server. Enables Protected Resource Metadata / DCR discovery. See OAuth.

None

CB_MCP_OAUTH_SCOPE_READ_LABEL

--oauth-scope-read-label

Custom label for the read scope, for IdPs using a different naming convention. See OAuth.

couchbase-mcp:read

CB_MCP_OAUTH_SCOPE_WRITE_LABEL

--oauth-scope-write-label

Custom label for the write scope, for IdPs using a different naming convention. See OAuth.

couchbase-mcp:write

CB_MCP_LOG_LEVEL

--log-level

Minimum log level: off, debug, info, warning, error. See Logging.

info

CB_MCP_LOG_SINKS

--log-sinks

Log output sinks: stderr, file (writes to all listed). See Logging.

stderr

CB_MCP_LOG_FILE

--log-file

Base path for the per-level log files. Used when the file sink is enabled. See Logging.

mcp_server_operational_insights.log

CB_MCP_LOG_MAX_BYTES

--log-max-bytes

Deprecated — use CB_MCP_LOG_ROTATION_MAX_SIZE_MB instead. Still honored for backward compatibility. If both are set, the MB variable takes priority (with a startup warning). See Logging.

1048576 (1 MB)

CB_MCP_LOG_ROTATION_MAX_SIZE_MB

--log-rotation-max-size-mb

Maximum size (MB) per log file before rotation, for all levels unless overridden per level. See Logging.

1

CB_MCP_LOG_RETENTION_BACKUP_COUNT

--log-retention-backup-count

Number of rotated backup files kept per level, in addition to the live file, for all levels unless overridden per level. See Logging.

1

CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB

--log-error-rotation-max-size-mb

Rotation size in MB for the error log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for error.

Inherits CB_MCP_LOG_ROTATION_MAX_SIZE_MB

CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB

--log-warning-rotation-max-size-mb

Rotation size in MB for the warning log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for warning.

Inherits CB_MCP_LOG_ROTATION_MAX_SIZE_MB

CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB

--log-info-rotation-max-size-mb

Rotation size in MB for the info log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for info.

Inherits CB_MCP_LOG_ROTATION_MAX_SIZE_MB

CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB

--log-debug-rotation-max-size-mb

Rotation size in MB for the debug log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for debug.

Inherits CB_MCP_LOG_ROTATION_MAX_SIZE_MB

CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT

--log-error-retention-backup-count

Rotated backups kept for the error log file. Overrides the global count for error.

Inherits CB_MCP_LOG_RETENTION_BACKUP_COUNT

CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT

--log-warning-retention-backup-count

Rotated backups kept for the warning log file. Overrides the global count for warning.

Inherits CB_MCP_LOG_RETENTION_BACKUP_COUNT

CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT

--log-info-retention-backup-count

Rotated backups kept for the info log file. Overrides the global count for info.

Inherits CB_MCP_LOG_RETENTION_BACKUP_COUNT

CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT

--log-debug-retention-backup-count

Rotated backups kept for the debug log file. Overrides the global count for debug.

Inherits CB_MCP_LOG_RETENTION_BACKUP_COUNT

CB_MCP_AUDIT_LOG_ENABLED

--audit-log-enabled

Turns audit logging on. See Audit Logging.

false

CB_MCP_AUDIT_LOG_SINKS

--audit-log-sinks

Comma-separated list of audit sinks. Allowed values are console and file.

console

CB_MCP_AUDIT_LOG_FILE_PATH

--audit-log-file-path

Path of the audit log file. Needed when file is one of the sinks.

None

CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB

--audit-log-rotation-max-size-mb

Size (MB) that the live audit file can reach before rotation. 0 turns size-based rotation off.

10

CB_MCP_AUDIT_LOG_ROTATION_INTERVAL

--audit-log-rotation-interval

Age that the live audit file can reach before rotation, as <value>d or <value>w. 0 turns time-based rotation off.

1d

CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS

--audit-log-retention-max-backups

Number of rotated backups kept for each audit file, not counting the live file.

10

CB_MCP_AUDIT_LOG_TOOL_ARGS

--audit-log-tool-args

Includes tool arguments in audit records, verbatim and without redaction.

false

CB_MCP_AUDIT_LOG_DISABLED_EVENTS

--audit-log-disabled-events

Numeric event IDs to turn off, as a comma-separated list or a path to a file. The server refuses to turn off write or security events.

None
You can also set both the rotation size and backup count per log level (error, warning, info, debug) — see Per-Level Overrides.

Checking the MCP Server Version

uvx couchbase-mcp-server --version

Configuring Authentication

For authentication, you need either:

or

If you specify both, mTLS takes priority.

Optionally, you can specify a CA root certificate path to validate server certificates (useful for self-signed certificates).

Example Configurations

The following examples use uvx to run the server. You can replace these with the corresponding docker run commands - see Streamable HTTP for the Docker HTTP configuration.

How to: Basic Auth

Provide an Operational Insights username and password. For Basic Authentication setup, see Manage Users and Roles (self-managed).

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "username",
        "CB_OPERATIONAL_INSIGHTS_PASSWORD": "password"
      }
    }
  }
}

How to: Connect with Certificates

  • Connection string: Use http:// for unencrypted connections or https:// for TLS.

  • TLS certificates: If using TLS with self-signed or untrusted certificates, set CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH to your CA root certificate.

  • mTLS: For certificate-based authentication, use CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH and CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH instead of username/password. For a PKCS#12 bundle (.p12 or .pfx), set only CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH. If the client key or bundle is encrypted, also set CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD. mTLS requires an https:// connection string.

Basic auth with custom CA:

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "username",
        "CB_OPERATIONAL_INSIGHTS_PASSWORD": "password",
        "CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH": "/path/to/ca-certificate.pem"
      }
    }
  }
}

mTLS (no username/password):

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH": "/path/to/client.key",
        "CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH": "/path/to/ca-certificate.pem"
      }
    }
  }
}

How to: mTLS Based Auth

For environments requiring certificate-based authentication. For mTLS setup, see Configure Client Certificate Authentication.

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}