uvx not found: Verify that uv is on your system PATH. Install uv following the official instructions. If installed via a package manager, verify it’s on your PATH.

Run which uv (macOS/Linux) or where uv (Windows) to find the path. You may need to provide the absolute path to uv/uvx in the command field of your MCP client configuration.

After updating source code, run uv sync to update dependencies. This is only required when running from source after pulling new changes.

Check credentials: Verify that your connection string, username, password, or certificate paths are correct.

Cluster accessibility: Verify that the cluster is accessible from the machine running the MCP server. If using Couchbase Capella, verify that the machine’s IP is allowed in the cluster settings — required only when connecting over the public Internet, not on a VPC or a private network to Capella.

Bucket permissions: Check that the database user has proper permissions to access at least one bucket.

Connection string format: Use couchbases:// for Capella and TLS-enabled clusters, couchbase:// for unencrypted local connections.

Use couchbase:// for unencrypted connections

Certificates for TLS: If you’re connecting with TLS enabled on non-Capella clusters, verify that you’ve configured the certificate correctly via CB_CA_CERT_PATH.

stdio: Verify that you’ve configured the MCP client to launch the server as a subprocess. Check the client’s server configuration for the correct command and arguments to start the server.

HTTP: Check that the configured port is not in use. Verify that the URL ends with /mcp. Also check if the client configuration is set correctly.

Port conflicts: If the default port 8000 is in use, set a different port with CB_MCP_PORT or --port.

Host binding: By default, the server binds to 127.0.0.1 (localhost only). To allow external connections, set CB_MCP_HOST=0.0.0.0 or --host.

Permission denied for get_cluster_health_snapshot, get_cluster_tasks, get_cluster_query_vitals, get_active_queries, or get_bucket_config: These tools need the ro_admin role or a role with more privileges.

Permission denied for get_cluster_system_events or delete_active_query: These tools need the Full Admin or Cluster Admin role.

Permission denied for get_cluster_health_and_services: The active ping needs KV, Query, or Search privileges, or the Cluster Admin role. get_client_connectivity_report makes no request to the cluster, so it needs no role beyond the one the connection already uses.

Tool missing from tool discovery: The server does not load ten tools when the connection string points at Capella: get_cluster_health_snapshot, get_cluster_metrics, get_cluster_tasks, get_cluster_system_events, get_cluster_query_vitals, get_index_stats, get_bucket_config, get_active_queries, delete_active_query, and discover_tool_input_values. They also need Couchbase Server 7.6 or later. get_server_configuration_status reports the withheld tools, and the server lists them in the startup log.

REST-based tools fail with mTLS: Tools that call REST APIs directly use basic authentication. They need CB_USERNAME and CB_PASSWORD, and they do not work with an mTLS-only configuration.

Earlier system events are missing: get_cluster_system_events returns 50 records at first, and up to 500 per request. Use since_time to page through earlier events.

A bucket shows no configuration: get_bucket_config returns an empty list when the connection lands on a node that never joined a cluster. This can happen when the connection string names a DNS or SRV record that points to a changing set of nodes. An empty list does not prove that the cluster has no buckets.

Embedding provider not configured: Vector search needs an embedding provider. The vector search tools stay registered, and they return an error when you call them without one. Set CB_MCP_EMBEDDING_MODEL_PROVIDER and CB_MCP_EMBEDDING_MODEL, or the matching --embedding-model-provider and --embedding-model flags. See Environment Variables.

Provider authentication fails: Set CB_MCP_EMBEDDING_MODEL_API_KEY for capella, openai, cohere, and voyage. For bedrock, set the AWS key variables or rely on the default AWS credential chain. Bedrock also needs the optional extra, couchbase-mcp-server[bedrock-embeddings].

Provider endpoint unreachable: The capella provider requires CB_MCP_EMBEDDING_MODEL_ENDPOINT. For a local OpenAI-compatible server such as Ollama or vLLM, use the openai provider with CB_MCP_EMBEDDING_MODEL_ENDPOINT. Requests to the provider time out after 30 seconds.

Wrong model: Use the same embedding model that produced the vectors in your index.

Server version: run_vector_query needs Couchbase Server 8.0 or later and a GSI Composite or Hyperscale vector index. run_vector_search needs Couchbase Server 7.6 or later and the Search Service.

Data residency: The server sends the search text of every vector search to the embedding provider. With a hosted provider, the provider is a third party.

Check whether CB_MCP_READ_ONLY_MODE=true (the default).

When CB_MCP_READ_ONLY_MODE=true, KV write tools are not loaded and SQL++ write queries are blocked. Set CB_MCP_READ_ONLY_MODE=false to allow write operations.

See Read-Only Mode for the full behavior reference.

Verify that you’ve spelled tool names exactly as listed in the Tools reference.

If using a file path for CB_MCP_DISABLED_TOOLS, verify that the file exists and the server process can read it. If using Docker, verify that the file is included in the container and the path is correct.

Remember that disabling tools alone does not prevent operations - RBAC is the authoritative security control. See Security.

Verify that the MCP client supports Elicitation. If the client does not support it, the server executes the tools without requiring confirmation.

Verify that you’ve spelled tool names exactly as listed in the Tools reference.

The server fails to start with confirmation-required tools: Elicitation cannot work in stateless mode, which has no session for the prompt. The server refuses to start when you combine --confirmation-required-tools with --stateless-http, or with --workers set to more than 1. Turn off stateless mode and use one worker, or remove the confirmation requirement.

If using a file path for CB_MCP_CONFIRMATION_REQUIRED_TOOLS, verify that the file exists and the server process can read it. If using Docker, verify that the file is included in the container and the path is correct.

Variables not taking effect: Verify that you’ve set variables in the env block of your MCP client configuration, not as system environment variables (unless your client supports that).

CLI vs environment variable conflicts: Command line arguments take priority over environment variables. If a setting is not behaving as expected, check if it’s being overridden by a CLI argument.

See Environment Variables for the full reference.

Tools

Environment Variables & Command Line Arguments

Logging

Audit Logging

Security