Environment Variables & Command Line Arguments

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_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	Maximum size (bytes) per log file before rotation. See Logging.	1048576 (1 MB)

Checking the MCP Server Version

uvx couchbase-mcp-server --version

Configuring Authentication

For authentication, you need either:

• Username and Password (basic authentication)

  or

• Client Certificate and Key paths (mTLS authentication)

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

note

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