Troubleshooting

Common issues that you might run into while using the Couchbase MCP Server and their solutions.

uv / uvx Issues

If you see errors related to uv or uvx, check the following:

uvx not found: Ensure 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.

If you see errors related to connecting to the Couchbase cluster, check the following:

Check credentials - Ensure your connection string, username, password, or certificate paths are correct.
Cluster accessibility - Ensure the cluster is accessible from the machine running the MCP server. If using Couchbase Capella, ensure the machine's IP is allowed in the cluster settings.
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 are connecting with TLS enabled on non-Capella clusters, ensure that the certificate is configured correctly via CB_CA_CERT_PATH.

If the MCP client is unable to communicate with the server, check the following based on your configured transport mode:

stdio - Ensure the MCP client is configured 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 matches the transport mode (/mcp for HTTP, /sse for SSE). 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.

If you are trying to perform write operations but they are not working as expected, check the following:

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 — regardless of CB_MCP_READ_ONLY_QUERY_MODE.
See Read-Only Mode for the full behavior truth table.

If a tool you expect to be disabled is still executing, check the following:

Verify tool names are spelled exactly as listed in the Tools reference.
If using a file path for CB_MCP_DISABLED_TOOLS, ensure the file exists and is readable by the server process. If using Docker, ensure 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.

If the tool you expect to require confirmation is executing without it, check the following:

Ensure that the MCP client supports Elicitation. If the client does not support it, the tools will be executed without requiring confirmation.
Verify tool names are spelled exactly as listed in the Tools reference.
If using a file path for CB_MCP_CONFIRMATION_REQUIRED, ensure the file exists and is readable by the server process. If using Docker, ensure the file is included in the container and the path is correct.

If you are setting environment variables but they do not seem to be taking effect, check the following:

Variables not taking effect - Ensure variables are set 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 is being overridden by a CLI argument.
Deprecated variables - CB_MCP_READ_ONLY_QUERY_MODE is deprecated. Use CB_MCP_READ_ONLY_MODE instead.
See Environment Variables for the full reference.

Check the MCP client logs for errors or warnings:

Client	Log Location
Claude Desktop	`~/Library/Logs/Claude` (macOS), `%APPDATA%\Claude\Logs` (Windows)
Cursor	Bottom panel > Output > "Cursor MCP"
Windsurf	Check Windsurf output panel
VS Code	Command Palette > "MCP: List Servers" > Show Output
JetBrains	Help > Show Log in Finder/Explorer > mcp > couchbase
Factory	`~/.factory/logs/` (macOS)