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.

The MCP server can be configured using environment variables or command line arguments. If both are specified, command line arguments take priority over environment variables.

Configuration Reference

Environment Variable CLI Argument Description Default

CB_CONNECTION_STRING

--connection-string

Connection string to the Couchbase cluster. See Configuring Connection String.

Required

CB_USERNAME

--username

Username for basic authentication. See Configuring Authentication.

Required (or mTLS)

CB_PASSWORD

--password

Password for basic authentication. See Configuring Authentication.

Required (or mTLS)

CB_CLIENT_CERT_PATH

--client-cert-path

Path to client certificate for mTLS. See Configuring Authentication.

Required if using mTLS

CB_CLIENT_KEY_PATH

--client-key-path

Path to client key for mTLS. See Configuring Authentication.

Required if using mTLS

CB_CA_CERT_PATH

--ca-cert-path

Path to server root certificate for TLS (self-signed / untrusted certs). Not required for Capella.

CB_MCP_READ_ONLY_MODE

--read-only-mode

Prevent all data modifications (KV and Query). 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

8000

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.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
Both the rotation size and backup count can also be set 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 both are specified, mTLS takes priority.

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

Example Configurations

All examples below use uvx to run the server. These can be replaced with the corresponding docker run commands - see Streamable HTTP for the Docker HTTP configuration.

How to: Basic Auth

Provide a Couchbase database username and password. For Basic Authentication setup, see Manage Database Credentials (Capella) or Manage Users and Roles (self-managed).

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

How to: Connect to Capella

  • Connection string: Use couchbases:// (with s) — TLS is always enabled. Find your connection string in the Capella UI under Cluster > Connect.

  • TLS certificates: The bundled Capella root CA is used automatically. You do not need to set CB_CA_CERT_PATH.

  • IP allowlisting: Ensure the machine running the MCP server has its IP allowed in the Capella cluster settings. Required only when the server reaches Capella over the public Internet — not if it’s on a VPC or a private network connected to Capella.

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://cb.your-capella-endpoint.cloud.couchbase.com",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

How to: Connect to Self-Managed Server with Certificates

  • Connection string: Use couchbase:// for unencrypted connections or couchbases:// for TLS.

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

  • mTLS: For certificate-based authentication, use CB_CLIENT_CERT_PATH and CB_CLIENT_KEY_PATH instead of username/password.

Basic auth with custom CA:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://your-server-hostname",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_CA_CERT_PATH": "/path/to/ca-certificate.pem"
      }
    }
  }
}

mTLS (no username/password):

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://your-server-hostname",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key",
        "CB_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": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://your-connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}