Skip to main content
Version: 1.0

Logging

The MCP server emits structured logs to help you operate it and to give Couchbase support the diagnostic information needed to triage issues. You can configure the log level and choose one or more output sinks (console and/or file). Logging applies to all transports — both stdio and Streamable HTTP.

Log Levels​

LevelDescription
errorAn operation failed, or the server can't reliably serve the next request.
warningA threshold was crossed, a fallback was taken, or a deprecated path was used. Nothing is broken yet.
infoLifecycle events, request envelopes (metadata only), config snapshots, and version info. Default.
debugInternal phase transitions and timing details. Verbose; intended for debugging.
offNo logs are emitted.

The configured level is a minimum threshold: the server records events at that level and every level above it. For example, warning records warning and error.

note

If CB_MCP_LOG_LEVEL is set to an unrecognized value, the server prints an error message and falls back to info.

warning

Setting CB_MCP_LOG_LEVEL=off disables all logging. No logs are produced, so the diagnostic files required for product support will not be available.

Configuration​

Environment VariableDescriptionDefault
CB_MCP_LOG_LEVELMinimum level to record. One of off, debug, info, warning, error.info
CB_MCP_LOG_SINKSWhere logs are written. One or more of stderr, file (comma-separated; the server writes to all listed sinks).stderr
CB_MCP_LOG_FILEFile path used as the template for the per-level log files — the level name is inserted before the extension (mcp_server.log → mcp_server.info.log, …). Used when the file sink is enabled; the directory must already exist.mcp_server.log
CB_MCP_LOG_MAX_BYTESMaximum size in bytes per log file before it rotates.1048576 (1 MB)

Log Sinks​

The server supports two sinks, and you can enable more than one at a time:

  • stderr (default) — logs are written to the console. MCP clients running the server over stdio typically capture this stream into their own log files.

  • file — logs are written to disk. CB_MCP_LOG_FILE is the file path you provide (it may include a directory, e.g. /var/log/couchbase-mcp/mcp_server.log; the directory must already exist). It is a template, not the literal name written to disk — a separate file is written per log level, with the level name inserted just before the file extension. So /var/log/couchbase-mcp/mcp_server.log produces mcp_server.debug.log, mcp_server.info.log, mcp_server.warning.log, and mcp_server.error.log in that directory (the error file also captures CRITICAL). Each file uses size-based rotation controlled by CB_MCP_LOG_MAX_BYTES (default ~1 MB), keeping a single rotated backup per level (e.g. mcp_server.info.log.1) — so each level occupies at most about twice the configured size on disk.

When CB_MCP_LOG_SINKS is not set, the server writes to stderr only.

Startup Summary​

On every start, the server emits one INFO line reporting the resolved logging configuration — the level in effect, the active sinks, and the exact per-level file paths — after defaults are applied and any invalid input is discarded. For example:

2026-06-29T18:08:49+0530 - couchbase - INFO - Logging configured: level=INFO, sinks=stderr,file, log_files={'INFO': 'mcp_server.info.log', 'WARNING': 'mcp_server.warning.log', 'ERROR': 'mcp_server.error.log'}, max_bytes=1048576

When logging doesn't behave as expected, check this line first to confirm the level, sinks, and file paths actually in use. See Troubleshooting → Logging Issues.

Errors & Warnings​

  • File logging disabled (default). When the file sink is not explicitly enabled, the server emits the warning "File logging is disabled. Log files required for product support are not being generated." This is the default state, since the default sink is stderr — a reminder that your logs are not being saved to disk for future support needs.

  • File sink errors. When the file sink is enabled, the server raises an error if:

    • the directory for the configured CB_MCP_LOG_FILE path does not exist — it does not create the directory structure for you; or
    • the path exists but the server lacks write permission for it.

Sensitive Data in Logs​

To keep logs safe to share with support, the server never writes the following to any sink, at any log level:

  • Credentials and passwords
  • Tokens (bearer, JWT, OAuth) and signing secrets
  • Certificates
  • Connection strings with embedded credentials
  • Document content
warning

Some data can appear in logs depending on the configured log level:

  • Query text — when CB_MCP_LOG_LEVEL=debug, the full SQL++ query is logged.
  • Document IDs — document keys (DocIDs) are logged in certain cases and at certain log levels.

Take this into account when choosing a log level and before sharing logs, especially if your query text or document keys may contain sensitive information.

Example​

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://your-connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_LOG_LEVEL": "info",
        "CB_MCP_LOG_SINKS": "stderr,file",
        "CB_MCP_LOG_FILE": "/var/log/couchbase-mcp/mcp_server.log",
        "CB_MCP_LOG_MAX_BYTES": "1048576"
      }
    }
  }
}

See Also​