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.

As of v1.1, the server can also be invoked with an explicit operational subcommand (couchbase-mcp-server operational) — see Architecture. Running with no subcommand is unchanged and still starts the operational server.

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. Overrides the server default of 8000.

None

CB_MCP_WORKERS

--workers

Number of worker processes for HTTP transport mode. Values greater than 1 require the http transport and stateless mode, and you cannot combine them with --confirmation-required-tools. See Scaling with Workers.

1

CB_MCP_STATELESS_HTTP

--stateless-http

Handle each HTTP request without session state. It turns on automatically when CB_MCP_WORKERS is greater than 1. Only the http transport honors it, and you cannot combine it with --confirmation-required-tools.

false

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

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

CB_MCP_EMBEDDING_MODEL_PROVIDER

--embedding-model-provider

Embedding provider for the vector search tools: capella (the Capella Model Service), openai, cohere, voyage, or bedrock. The server sends the search text of every vector search to this provider. See Embedding Providers.

None

CB_MCP_EMBEDDING_MODEL

--embedding-model

Name or ID of the embedding model.

None

CB_MCP_EMBEDDING_MODEL_API_KEY

--embedding-model-api-key

API key for the embedding provider. Providers other than bedrock need it. The server treats it as a secret.

None

CB_MCP_EMBEDDING_MODEL_ENDPOINT

--embedding-model-endpoint

Base URL of the provider. Required for capella. With openai, it also allows OpenAI-compatible local servers such as Ollama or vLLM.

None

CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID

--embedding-model-aws-access-key-id

AWS access key ID. Bedrock only. If unset, the server uses the default AWS credential chain. The server treats it as a secret.

None

CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY

--embedding-model-aws-secret-access-key

AWS secret access key. Bedrock only. If unset, the server uses the default AWS credential chain. The server treats it as a secret.

None

CB_MCP_EMBEDDING_MODEL_AWS_REGION

--embedding-model-aws-region

AWS region. Bedrock only. If unset, the server uses the region that the AWS SDK resolves.

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

Embedding Providers

The vector search tools, run_vector_query and run_vector_search, turn the search text into an embedding with the provider that you configure. Set the provider and the model when you start the server. If you do not set a provider, the tools stay registered, and they return an error when you call them.

Provider Required Settings Optional Settings Notes

capella

CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL, CB_MCP_EMBEDDING_MODEL_ENDPOINT

None

The Capella Model Service, provisioned or serverless. The endpoint is the base URL of your deployment, such as https://<id>.ai.couchbase.com. It has no default. Find it in the Capella UI under AI Data Plane > Models. The model is the deployed model name.

openai

CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL

CB_MCP_EMBEDDING_MODEL_ENDPOINT

An example model is text-embedding-3-small. Set the endpoint to use an OpenAI-compatible local server, such as Ollama, vLLM, or LM Studio.

cohere

CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL

CB_MCP_EMBEDDING_MODEL_ENDPOINT

An example model is embed-english-v3.0. Set the endpoint for a private Cohere deployment.

voyage

CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL

CB_MCP_EMBEDDING_MODEL_ENDPOINT

An example model is voyage-3.

bedrock

CB_MCP_EMBEDDING_MODEL

CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID, CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY, CB_MCP_EMBEDDING_MODEL_AWS_REGION

Only the Titan embedding family works, such as amazon.titan-embed-text-v2:0. If you omit the keys, the server uses the default AWS credential chain. The region falls back to the one the AWS SDK resolves. Bedrock needs the optional extra couchbase-mcp-server[bedrock-embeddings].

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

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 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"
      }
    }
  }
}