Couchbase

oficial

Interactúa con los datos almacenados en clústeres de Couchbase usando lenguaje natural.

¿Qué puedes hacer con Couchbase MCP?

  • Explorar los datos del clúster — Enumerar buckets, scopes y colecciones, y luego inferir el esquema de una colección como orders.
  • Ejecutar consultas SQL++ — Ejecutar consultas SQL++ de solo lectura en un bucket y un scope, y explicar los planes de consulta.
  • Inspeccionar documentos — Obtener un documento por ID o leer rutas específicas de subdocumentos sin cargar el documento completo.
  • Comprobar el estado del clúster — Informar sobre el estado del clúster, los servicios en ejecución y los diagnósticos de conexión.
  • Analizar el rendimiento de las consultas — Encontrar las consultas de mayor duración, más frecuentes o que no usan índices de cobertura.
  • Búsquedas y consultas vectoriales — Ejecutar búsquedas de texto completo y consultas de similitud vectorial en índices configurados.

Documentación

Servidor MCP de Couchbase

Couchbase MCP Server es un servidor MCP autohospedado que permite a los agentes de IA conectarse e interactuar con los datos de Couchbase Servers (ya sea alojados en Capella o autogestionados) o de Operational Insights Enterprise. Proporciona herramientas en categorías como estado del clúster, esquema de datos, consultas y más, con controles de seguridad mediante el modo de solo lectura y la desactivación granular de herramientas. Admite los transportes STDIO y Streamable HTTP, con capacidades de OAuth.

Couchbase MCP Server se distribuye como un paquete de Python Package Index (PyPI) y mediante Docker. El soporte empresarial para Couchbase MCP Server está disponible mediante la licencia de Couchbase AI Data Plane, que también da derecho a usar Couchbase Agent Memory y Couchbase Agent Catalog y a recibir soporte empresarial para ambos.

Docs License Python 3.11+ PyPI version Install in Cursor Verified on MseeP Trust Score

Documentación completa: docs.couchbase.com/mcp-server

Couchbase Server MCP server

Tabla de contenido

Por qué Couchbase MCP Server

  • Seguro de forma predeterminada: las herramientas de escritura no se cargan y las consultas que modifican datos se bloquean, a menos que establezcas CB_MCP_READ_ONLY_MODE=false; también se pueden desactivar herramientas individuales o exigir la confirmación del usuario para usarlas.
  • Couchbase Server y Operational Insights: el servidor operativo se conecta a Couchbase Capella o a un clúster de Couchbase Server autogestionado con la misma configuración; el servidor Operational Insights se conecta a clústeres autogestionados de Operational Insights.
  • Compatible con RBAC: los controles de las herramientas orientan al LLM; el control de acceso basado en roles del usuario de Couchbase sigue siendo el límite de seguridad autoritativo.
  • Transportes para producción: STDIO para clientes de escritorio locales o Streamable HTTP con OAuth 2.1 opcional (cualquier proveedor de identidad que publique JWKS: Auth0, Okta, Keycloak, Entra, Cognito, …), comprobaciones de estado y registro de auditoría para implementaciones compartidas. El servidor operativo también puede ejecutar varios trabajadores para aprovechar más núcleos de CPU.
  • Cualquier cliente MCP: probado con Claude Desktop, Cursor, Windsurf, VS Code y JetBrains AI Assistant/Junie.

Una vez conectado, puedes hacer preguntas como estas:

  • «¿Qué buckets, scopes y collections tengo, y cuál es el esquema de la collection orders?»
  • «Busca los 10 documentos más recientes de users donde status = 'active'.»
  • «¿Cuáles son las 5 consultas más lentas de la última hora y les falta algún índice de cobertura?»
  • «¿Está en buen estado este clúster y qué servicios están en ejecución?»
  • «Inserta un documento nuevo en products con estos campos: …» (requiere CB_MCP_READ_ONLY_MODE=false)

Cómo elegir un servidor

Este paquete incluye dos servidores MCP. Cada uno se inicia con su propio subcomando, se conecta a un tipo de clúster distinto y tiene sus propias herramientas. Elige el que corresponda a tu clúster, sigue la sección correspondiente para configurarlo y consultar sus herramientas, y luego usa Configuración común para los ajustes que comparten. Para usar ambos, registra cada uno como un servidor independiente en tu cliente MCP.

Servidor operativoServidor Operational Insights
Úsalo conUn clúster de Couchbase (Capella o autogestionado)Un clúster autogestionado de Operational Insights (no disponible en Capella)
Subcomandooperational (predeterminado)operational-insights
Cadena de conexióncouchbase:// / couchbases://URL HTTP(S), p. ej., http://localhost:8095
Variables de credencialesCB_CONNECTION_STRING, CB_USERNAME, …CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, …
Herramientas52: estado del clúster, esquema, KV, SQL++, índices, búsqueda de texto completo y vectorial, rendimiento de consultas13: esquema, SQL++ (síncrono y asíncrono), índices, exportaciones
Puerto HTTP predeterminado80008001
Archivo de registro predeterminadomcp_server.logmcp_server_operational_insights.log

Actualmente, el subcomando es opcional para el servidor operativo: basta con ejecutar couchbase-mcp-server; sin embargo, especificarlo hace que la configuración sea inequívoca. Las opciones van después del subcomando: couchbase-mcp-server operational --transport=http. Comprueba la versión instalada con uvx couchbase-mcp-server --version.

Servidor operativo

El servidor operational se conecta a un clúster de Couchbase en Capella o a un Couchbase Server autogestionado mediante el SDK de Python couchbase.

Inicio rápido del servidor operativo

Necesitas un clúster de Couchbase en ejecución —el nivel gratuito de Capella es la forma más rápida de obtener uno (puedes importar un conjunto de datos de ejemplo)— y un cliente MCP. Añade una de estas configuraciones a tu cliente (consulta Configuración del cliente para saber dónde guarda cada cliente su configuración). Si el cliente ya tiene otros servidores, añade couchbase al objeto mcpServers existente.

Desde PyPI con uvx (requiere uv y Python 3.11 o posterior):

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

Con Docker (solo requiere Docker):

{
  "mcpServers": {
    "couchbase": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_CONNECTION_STRING=couchbases://connection-string",
        "-e", "CB_USERNAME=username",
        "-e", "CB_PASSWORD=password",
        "couchbase/mcp-server:latest", "operational"
      ]
    }
  }
}
Desde el código fuente
git clone https://github.com/couchbase/mcp-server-couchbase.git
{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory", "path/to/cloned/repo/mcp-server-couchbase/",
        "run", "src/mcp_server.py", "operational"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

path/to/cloned/repo/mcp-server-couchbase/ es la ruta a tu clon; conserva la barra final. Después de descargar las actualizaciones, ejecuta uv sync para actualizar las dependencias.

Conexión y autenticación del servidor operativo

Usa un nombre de usuario y una contraseña o un certificado de cliente (mTLS). Si se configuran ambos, se usa el certificado.

Variable de entornoArgumento de CLIDescripción
CB_CONNECTION_STRING--connection-stringCadena de conexión al clúster. Obligatoria
CB_USERNAME / CB_PASSWORD--username / --passwordAutenticación básica
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH--client-cert-path / --client-key-pathAutenticación mTLS
CB_CA_CERT_PATH--ca-cert-pathCertificado raíz para un certificado de servidor autofirmado o no confiable (no se necesita para Capella)
Ejemplo de mTLS
{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

Herramientas del servidor operativo

Las herramientas de escritura (marcadas con ✏️) no se cargan mientras está activado el modo de solo lectura, que es el modo predeterminado. Las herramientas marcadas con 🖥️ son solo para instalaciones autogestionadas: usan endpoints REST de administración que Capella no expone o (discover_tool_input_values) solo proporcionan datos de referencia para una herramienta que sí los usa; por eso requieren Couchbase Server 7.6+ autogestionado y no se registran en conexiones de Capella.

Configuración y estado del clúster

HerramientaDescripción
get_server_configuration_statusEstado y configuración del servidor sin conectarse al clúster: modo de solo lectura, herramientas desactivadas o que requieren confirmación, OAuth, registro y contadores de auditoría
test_cluster_connectionComprueba las credenciales del clúster conectándote a él
get_cluster_health_and_servicesEstado del clúster y servicios en ejecución, con filtrado opcional mediante service_types
get_client_connectivity_reportDiagnósticos de conexión almacenados en caché por el SDK, sin sondeo activo de la red
get_cluster_metrics 🖥️Estadísticas del clúster durante un intervalo histórico (endpoint stats-range)
get_cluster_tasks 🖥️Tareas en ejecución en este momento: rebalanceo, compactación, XDCR y creación de índices. Requiere ro_admin
get_cluster_health_snapshot 🖥️Estado de cada nodo: topología de servicios, pertenencia, orquestador y resumen del estado. Requiere ro_admin
get_bucket_config 🖥️Configuración y estado actual de un bucket o de todos los buckets: cuotas, política de expulsión, réplicas, durabilidad, almacenamiento y compactación. Requiere ro_admin
get_cluster_system_events 🖥️Registro de eventos del sistema (cambios de configuración, conmutaciones por error, rebalanceos y reinicios), delimitado por since_time. Requiere Full Admin o Cluster Admin
discover_tool_input_values 🖥️Busca valores de entrada exactos que necesitan otras herramientas (p. ej., todos los nombres de métricas para get_cluster_metrics). Funciona sin conexión

Descubrimiento del modelo de datos y del esquema

HerramientaDescripción
get_buckets_in_clusterEnumera todos los buckets del clúster
get_scopes_in_bucketEnumera todos los scopes de un bucket
get_collections_in_scopeEnumera todas las collections de un scope (requiere el servicio Query)
get_scopes_and_collections_in_bucketEnumera todos los scopes y collections de un bucket
get_schema_for_collectionDeduce la estructura de una collection
create_scope ✏️Crea un scope en un bucket (Server 7.6+ y Capella)
create_collection ✏️Crea una collection en un scope existente (Server 7.6+ y Capella)
delete_scope ✏️Elimina un scope y todas sus collections; acción permanente
delete_collection ✏️Elimina una collection y todos sus documentos; acción permanente

Operaciones con documentos (KV)

HerramientaDescripción
get_document_by_idObtiene un documento por ID
lookup_subdocumentLee rutas específicas, comprueba la existencia o cuenta elementos sin obtener el documento completo
upsert_document_by_id ✏️Inserta o actualiza un documento por ID
insert_document_by_id ✏️Inserta un documento nuevo (falla si ya existe)
replace_document_by_id ✏️Reemplaza un documento existente (falla si no existe)
delete_document_by_id ✏️Elimina un documento por ID
mutate_subdocument ✏️Modifica rutas de un documento existente (inserción o actualización, inserción, reemplazo, eliminación, operaciones con arrays y contadores)

Consultas e indexación

HerramientaDescripción
run_sql_plus_plus_queryEjecuta una consulta SQL++ limitada a un bucket y un scope; usa directamente los nombres de las collections (SELECT * FROM users). Las instrucciones que modifican datos se bloquean en el modo de solo lectura
explain_sql_plus_plus_queryGenera y evalúa un plan EXPLAIN: metadatos, plan extraído y hallazgos
get_index_advisor_recommendationsRecomendaciones de Index Advisor para una consulta SQL++
list_indexesEnumera índices con sus definiciones, filtrables por bucket, scope, collection o nombre; identifica los índices vectoriales (is_vector, vector_type)
get_index_stats 🖥️Tamaño, fragmentación, tráfico de escaneo y retraso de cada índice por nodo; detecta presión y índices sin uso
create_query_index ✏️Crea un índice GSI escalar, vectorial Hyperscale o vectorial compuesto (index_type). Se difiere de forma predeterminada; continúa con build_index
create_index ✏️Obsoleto: usa create_query_index. Eliminado en la versión 2.0
build_index ✏️Crea todos los índices diferidos de una collection
drop_index ✏️Elimina un índice GSI (escalar o vectorial)

Búsqueda de texto completo (FTS)

Requiere Couchbase Server 7.6+ y el servicio Search. Se admiten tanto los índices de nivel de scope como los de nivel de clúster (heredados): pasa bucket_name y scope_name juntos para el nivel de scope, o bien omite ambos.

HerramientaDescripción
list_search_indexesLista los índices de Search: a nivel de clúster, por bucket o por scope
get_search_index_definitionDefinición completa de un índice de Search (asignaciones, analizadores, parámetros del plan)
run_searchEjecuta cualquier consulta FTS que no sea vectorial a partir de su cuerpo JSON sin procesar; explain=true devuelve el plan de ejecución
upsert_search_index ✏️Crea o actualiza un índice de Search, incluidas las asignaciones de campos vectoriales. Las actualizaciones activan una reconstrucción completa: pasa el valor actual de uuid para evitar sobrescribir cambios simultáneos
drop_search_index ✏️Elimina un índice de Search de forma permanente

Búsqueda vectorial

Ambas herramientas incrustan texto de consulta sin formato con el modelo configurado en Proveedores de incrustación. Disponible en Couchbase Server autogestionado y Capella.

HerramientaDescripción
run_vector_queryBúsqueda por similitud en un índice vectorial GSI (Server 8.0+) mediante APPROX_VECTOR_DISTANCE(). El índice se elige automáticamente; admite un prefiltro SQL++ where y ajustes de Hyperscale (num_probes, rerank, top_n_scan). Devuelve documentos completos
run_vector_searchBúsqueda vectorial del servicio Search (Server 7.6+) en un índice con nombre. scalar_query la convierte en híbrida; prefilter reduce primero los candidatos. Devuelve los campos almacenados en el índice por resultado

Análisis del rendimiento de consultas

HerramientaDescripción
get_longest_running_queriesConsultas de mayor duración según el tiempo medio de servicio
get_most_frequent_queriesConsultas ejecutadas con mayor frecuencia
get_queries_with_largest_response_sizesConsultas con los tamaños de respuesta más grandes
get_queries_with_large_result_countConsultas con la mayor cantidad de resultados
get_queries_using_primary_indexConsultas que usan un índice primario
get_queries_not_using_covering_indexConsultas que no usan un índice de cobertura
get_queries_not_selectiveConsultas cuyos escaneos —de índice secundario, índice primario o secuenciales— devuelven muchos más documentos que el resultado final

Estado del servicio Query 🖥️

Estas herramientas llaman a la API REST de administración del propio servicio Query en cada nodo de consulta.

HerramientaDescripción
get_cluster_query_vitalsEstado del motor de consultas: tasa de solicitudes, solicitudes activas/en cola, memoria, GC y tiempo de actividad. Requiere ro_admin
get_active_queriesConsultas que se están ejecutando en este momento en todos los nodos de consulta. Requiere ro_admin
delete_active_query ✏️Cancela una consulta en curso por ID de solicitud. Requiere Full Admin o Cluster Admin

Herramientas deshabilitadas automáticamente en Capella

Las herramientas 🖥️ acceden a Couchbase mediante endpoints REST de administración que Capella no expone (la única excepción, discover_tool_input_values, no está disponible porque solo sirve a una herramienta que las necesita). Cuando todos los hosts de CB_CONNECTION_STRING terminan en .cloud.couchbase.com, el servidor no las registra y las muestra junto con tus propias herramientas deshabilitadas en get_server_configuration_status y en el registro de inicio. Las herramientas basadas en SDK, como get_cluster_health_and_services y get_client_connectivity_report, siguen disponibles.

HerramientaEndpoint necesario
get_cluster_metricsREST de administración (/pools/default/stats/range)
get_cluster_tasksREST de administración (/pools/default/tasks)
get_bucket_configREST de administración (/pools/default/buckets[/<name>])
get_cluster_health_snapshotREST de administración, además de endpoints por nodo
get_cluster_system_eventsREST de administración (/events)
get_index_statsREST del servicio Index (el /api/v1/stats de cada indexador)
get_cluster_query_vitalsREST del servicio Query (/admin/vitals)
get_active_queriesREST del servicio Query (/admin/active_requests)
delete_active_queryREST del servicio Query (DELETE /admin/active_requests/{id})
discover_tool_input_valuesNinguno (funciona sin conexión), pero solo sirve a get_cluster_metrics, que Capella no tiene

Proveedores de incrustación

run_vector_query y run_vector_search incrustan el texto de consulta con el proveedor establecido en CB_MCP_EMBEDDING_MODEL_PROVIDER. Es opcional: sin esta configuración, el servidor se inicia normalmente y ambas herramientas siguen registradas, pero al llamarlas se devuelve un error que explica qué se debe configurar.

CB_MCP_EMBEDDING_MODEL_PROVIDERObligatorioOpcionalNotas
capellaCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL, CB_MCP_EMBEDDING_MODEL_ENDPOINT—Capella Model Service. CB_MCP_EMBEDDING_MODEL_ENDPOINT es la URL propia de tu implementación (p. ej., https://<id>.ai.couchbase.com) de AI Data Plane > Models de Capella
openaiCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINTEstablece el endpoint para usar un servidor local compatible con OpenAI (Ollama, vLLM, LM Studio)
cohereCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
voyageCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
bedrockCB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID, CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY, CB_MCP_EMBEDDING_MODEL_AWS_REGIONModelos de incrustación Amazon Titan (p. ej., amazon.titan-embed-text-v2:0): el proveedor envía el formato de solicitud inputText de Titan, por lo que todavía no se admiten otros modelos de incrustación de Bedrock, como Cohere Embed. Omite las credenciales para usar la cadena predeterminada de AWS. Requiere el extra: pip install couchbase-mcp-server[bedrock-embeddings]
"env": {
  "CB_CONNECTION_STRING": "couchbases://connection-string",
  "CB_USERNAME": "username",
  "CB_PASSWORD": "password",
  "CB_MCP_EMBEDDING_MODEL_PROVIDER": "openai",
  "CB_MCP_EMBEDDING_MODEL": "text-embedding-3-small",
  "CB_MCP_EMBEDDING_MODEL_API_KEY": "sk-..."
}

Todas las opciones

Todas las variables de entorno y opciones de CLI para el servidor operational server

El servidor Operational Insights acepta las mismas opciones, excepto que tiene sus propios ajustes de conexión y no tiene opciones CB_MCP_EMBEDDING_MODEL_*.

Variable de entornoArgumento de CLIDescripciónValor predeterminado
CB_CONNECTION_STRING--connection-stringCadena de conexión al clúster de CouchbaseObligatorio
CB_USERNAME--usernameNombre de usuario con acceso a los buckets necesarios para la autenticación básicaObligatorio (o se necesitan el certificado y la clave del cliente para mTLS)
CB_PASSWORD--passwordContraseña para la autenticación básicaObligatorio (o se necesitan el certificado y la clave del cliente para mTLS)
CB_CLIENT_CERT_PATH--client-cert-pathRuta al archivo de certificado del cliente para la autenticación mTLSObligatorio si se usa mTLS (o se necesitan el nombre de usuario y la contraseña)
CB_CLIENT_KEY_PATH--client-key-pathRuta al archivo de clave del cliente para la autenticación mTLSObligatorio si se usa mTLS (o se necesitan el nombre de usuario y la contraseña)
CB_CA_CERT_PATH--ca-cert-pathRuta al certificado raíz del servidor para TLS si el servidor está configurado con un certificado autofirmado o no confiable. No será necesario si se conecta a Capella
CB_MCP_READ_ONLY_MODE--read-only-modeImpide todas las modificaciones de datos (KV, Query, administración de ámbitos/colecciones, administración de índices y administración de índices FTS). Cuando está habilitado, no se cargan las herramientas de escritura.true
CB_MCP_TRANSPORT--transportModo de transporte: stdio, httpstdio
CB_MCP_HOST--hostHost para el modo de transporte HTTP127.0.0.1
CB_MCP_PORT--portPuerto para el modo de transporte HTTP8000
CB_MCP_WORKERS--workersNúmero de procesos de trabajo del servidor para el transporte http. Los valores superiores a 1 ejecutan el modo HTTP sin estado (consulta Varios procesos de trabajo)1
CB_MCP_STATELESS_HTTP--stateless-httpGestiona cada solicitud HTTP sin estado por sesión. Solo se aplica con http; no se puede combinar con herramientas que requieren confirmación (consulta Varios procesos de trabajo)true cuando workers > 1; de lo contrario, false
CB_MCP_DISABLED_TOOLS--disabled-toolsHerramientas que se deshabilitarán (consulta Deshabilitar herramientas)Ninguna
CB_MCP_CONFIRMATION_REQUIRED_TOOLS--confirmation-required-toolsHerramientas que requieren confirmación explícita del usuario antes de ejecutarse mediante la solicitud de información de MCP (consulta Requerir confirmación)Ninguna
CB_MCP_LOG_LEVEL--log-levelNivel de registro del servidor MCP: off, debug, info, warning, error (consulta Registro)info
CB_MCP_LOG_SINKS--log-sinksDestinos de registro separados por comas: stderr, file o ambos (consulta Registro)stderr
CB_MCP_LOG_FILE--log-fileRuta base para los archivos de registro por nivel (solo se usa cuando el destino file está habilitado)mcp_server.log
CB_MCP_LOG_ROTATION_MAX_SIZE_MB--log-rotation-max-size-mbTamaño máximo global en MB por archivo de registro antes de rotarlo, heredado por cada nivel salvo que se sobrescriba. 0 —o un valor no válido, como uno negativo, nan o inf— no es válido y se sustituye por el valor predeterminado, con una advertencia al iniciar1 (1 MB)
CB_MCP_LOG_MAX_BYTES--log-max-bytesObsoleto — usa CB_MCP_LOG_ROTATION_MAX_SIZE_MB (MB). Tamaño global de rotación en bytes, aún admitido por compatibilidad con versiones anteriores; se ignora si también se establece CB_MCP_LOG_ROTATION_MAX_SIZE_MBSin establecer
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB--log-error-rotation-max-size-mbTamaño de rotación en MB para el archivo de registro ERROR; sobrescribe CB_MCP_LOG_ROTATION_MAX_SIZE_MB para ERRORHereda CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB--log-warning-rotation-max-size-mbTamaño de rotación en MB para el archivo de registro WARNING; sobrescribe CB_MCP_LOG_ROTATION_MAX_SIZE_MB para WARNINGHereda CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB--log-info-rotation-max-size-mbTamaño de rotación en MB para el archivo de registro INFO; sobrescribe CB_MCP_LOG_ROTATION_MAX_SIZE_MB para INFOHereda CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB--log-debug-rotation-max-size-mbTamaño de rotación en MB para el archivo de registro DEBUG; sobrescribe CB_MCP_LOG_ROTATION_MAX_SIZE_MB para DEBUGHereda CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_RETENTION_BACKUP_COUNT--log-retention-backup-countArchivos de copia de seguridad rotados que se conservan por archivo de registro y nivel (sin incluir el archivo activo), aplicado a todos los niveles salvo que se sobrescriba. 0 conserva solo el archivo activo (consulta Registro)1
CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT--log-error-retention-backup-countCopias de seguridad rotadas que se conservan para el archivo de registro ERROR; sobrescribe el recuento global para ERRORHereda CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT--log-warning-retention-backup-countCopias de seguridad rotadas que se conservan para el archivo de registro WARNING; sobrescribe el recuento global para WARNINGHereda CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT--log-info-retention-backup-countCopias de seguridad rotadas que se conservan para el archivo de registro INFO; sobrescribe el recuento global para INFOHereda CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT--log-debug-retention-backup-countCopias de seguridad rotadas que se conservan para el archivo de registro DEBUG; sobrescribe el recuento global para DEBUGHereda CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_OAUTH_JWT_JWKS_URI--oauth-jwks-uriPunto de conexión JWKS del proveedor de identidad que se usa para verificar los JWT de portador. Habilita OAuth cuando se establece junto con el emisor y la audiencia (consulta Autorización OAuth 2.1)Ninguno
CB_MCP_OAUTH_JWT_ISSUER--oauth-issuerClaim iss esperado del JWT. Obligatorio para habilitar OAuthNinguno
CB_MCP_OAUTH_JWT_AUDIENCE--oauth-audienceClaim aud esperado del JWT. Obligatorio para habilitar OAuthNinguno
CB_MCP_OAUTH_JWT_ALGORITHM--oauth-algorithmAlgoritmo de firma JWT: uno de RS256/384/512, ES256/384/512, PS256/384/512RS256
CB_MCP_OAUTH_MCP_BASE_URL--oauth-mcp-base-urlURL base pública de este servidor. Cuando se establece, publica metadatos de recursos protegidos RFC 9728 para que los clientes compatibles con PRM puedan detectar el IdPNinguno
CB_MCP_OAUTH_SCOPE_READ_LABEL--oauth-scope-read-labelSobrescribe la etiqueta de ámbito OAuth que se trata como acceso de «lectura» (anunciada en PRM y comparada con el claim scope/scp del token). Úsala cuando tu IdP no pueda emitir la forma canónicacouchbase-mcp:read
CB_MCP_OAUTH_SCOPE_WRITE_LABEL--oauth-scope-write-labelSobrescribe la etiqueta de ámbito OAuth que se trata como acceso de «escritura»; tiene la misma semántica que la etiqueta de lecturacouchbase-mcp:write
CB_MCP_AUDIT_LOG_ENABLED--audit-log-enabledHabilita el registro de auditoría: un destino independiente de los registros operativos CB_MCP_LOG_*, con un esquema estable y su propia retención (consulta Auditoría)false
CB_MCP_AUDIT_LOG_SINKS--audit-log-sinksDestinos de auditoría separados por comas: console, file o ambos. console escribe en stderr —nunca en stdout, que transporta el protocolo JSON-RPC en stdio—console
CB_MCP_AUDIT_LOG_FILE_PATH--audit-log-file-pathRuta al archivo de registro de auditoría. Obligatoria cuando file está entre los destinos; el nombre de host y el id del proceso se insertan antes de la extensión (audit.log → audit.<host>.<pid>.log)Ninguno
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB--audit-log-rotation-max-size-mbTamaño máximo en MB que puede alcanzar el archivo de auditoría activo antes de rotarse. 0 desactiva la rotación por tamaño10 (10 MB)
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL--audit-log-rotation-intervalAntigüedad máxima del archivo de auditoría activo antes de rotarse, como <value><unit>, donde la unidad es d (24 horas) o w (7 días); por ejemplo, 1d, 30d, 8w. 0 desactiva la rotación por intervalo1d
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS--audit-log-retention-max-backupsCopias de seguridad rotadas que se conservan por archivo de auditoría, sin incluir el archivo activo. Las copias de seguridad se comprimen con gzip. 0 no conserva ninguna. Esto limita un archivo, no el directorio; consulta Auditoría10
CB_MCP_AUDIT_LOG_TOOL_ARGS--audit-log-tool-argsRegistra los valores de los argumentos de las herramientas en el registro de auditoría. Desactivado de forma predeterminada —esta versión no incluye redacción, por lo que al habilitarlo se escriben los argumentos literalmente, incluidos los cuerpos completos de los documentos—false
CB_MCP_AUDIT_LOG_DISABLED_EVENTS--audit-log-disabled-eventsEventos de auditoría que se omitirán: ids de evento numéricos separados por comas (p. ej., 61490,61492) o un archivo con un id por línea. Solo se pueden omitir los eventos filtrablesNinguno
CB_MCP_EMBEDDING_MODEL_PROVIDER--embedding-model-providerProveedor de embeddings para run_vector_query / run_vector_search: uno de capella, openai, cohere, voyage, bedrock. Si no se establece, se desactiva el paso de embeddings de ambas herramientas hasta que se configure; consulta Configuración del proveedor de embeddingsNinguno
CB_MCP_EMBEDDING_MODEL--embedding-modelNombre/ID del modelo para el proveedor de embeddings configuradoNinguno
CB_MCP_EMBEDDING_MODEL_API_KEY--embedding-model-api-keyClave de API del proveedor configurado. No la usa bedrock (usa la cadena de credenciales de AWS / CB_MCP_EMBEDDING_MODEL_AWS_*)Ninguno
CB_MCP_EMBEDDING_MODEL_ENDPOINT--embedding-model-endpointSobrescritura de la URL base (un servidor local compatible con OpenAI o la URL propia de una implementación de Capella Model Service; obligatoria cuando CB_MCP_EMBEDDING_MODEL_PROVIDER=capella)Ninguno
CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID--embedding-model-aws-access-key-idID de clave de acceso de AWS; solo para el proveedor bedrock. Omítelo para usar la cadena de credenciales predeterminada de AWSNinguno
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY--embedding-model-aws-secret-access-keyClave de acceso secreta de AWS; solo para el proveedor bedrockNinguno
CB_MCP_EMBEDDING_MODEL_AWS_REGION--embedding-model-aws-regionRegión de AWS; solo para el proveedor bedrock. Si no se establece, se recurre a la resolución de región propia del SDK de AWSNinguno

Servidor Operational Insights

El servidor operational-insights se conecta a clústeres autogestionados de Operational Insights. Operational Insights es una base de datos analítica en tiempo real (RT-OLAP) para aplicaciones en tiempo real e inteligencia operativa. El servidor no está disponible para Capella. Usa el SDK couchbase-operational-insights. Se ejecuta como un proceso propio, separado del servidor operativo.

[!IMPORTANT] CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING es una URL HTTP(S), no una cadena de conexión couchbase://; por ejemplo, http://localhost:8095 o https://<host>:18095 con TLS. Este es el error de configuración más común.

Inicio rápido de Operational Insights

Desde PyPI con uvx:

{
  "mcpServers": {
    "couchbase-operational-insights": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "http://localhost:8095",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "Administrator",
        "CB_OPERATIONAL_INSIGHTS_PASSWORD": "password"
      }
    }
  }
}

Con Docker:

{
  "mcpServers": {
    "couchbase-operational-insights": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=http://host.docker.internal:8095",
        "-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=Administrator",
        "-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=password",
        "couchbase/mcp-server:latest", "operational-insights"
      ]
    }
  }
}

Desde el código fuente, usa la configuración del código fuente operativo con operational-insights como último argumento y las variables anteriores.

Conexión y autenticación de Operational Insights

Variable de entornoArgumento de CLIDescripción
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING--connection-stringURL del endpoint (HTTP/HTTPS). Obligatorio
CB_OPERATIONAL_INSIGHTS_USERNAME--usernameNombre de usuario
CB_OPERATIONAL_INSIGHTS_PASSWORD--passwordContraseña
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH--ca-cert-pathCertificado raíz (PEM) para un certificado de servidor autofirmado o no confiable
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH--client-cert-pathCertificado de cliente para mTLS: PEM (con una clave) o un paquete PKCS#12 (.p12/.pfx, sin clave). Requiere una URL https://; reemplaza el nombre de usuario y la contraseña
CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH--client-key-pathClave privada (PEM) del certificado de cliente. Déjela sin configurar para PKCS#12
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD--client-cert-passwordContraseña de una clave cifrada o un paquete PKCS#12
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE--operational-insights-query-result-max-sizeTamaño máximo del resultado de la consulta en bytes. Si no se configura, no hay límite. Cuando se configura, la lectura se detiene al alcanzar el límite y la respuesta informa truncated: true; no se devuelve una fila que lo excedería. Los valores superiores a 4 MiB (4194304) se limitan a 4 MiB, con una advertencia en stderr al iniciar
CB_MCP_OPERATIONAL_INSIGHTS_ASYNC_QUERY_RESULT_TIMEOUT--operational-insights-async-query-result-timeoutTiempo de espera en segundos para cada solicitud de consulta asíncrona: iniciar la consulta, comprobar su estado, obtener resultados, descartar y cancelar. En una obtención, abarca toda la descarga, por lo que falla si se tarda más que este tiempo en leer un resultado. Auméntelo para resultados grandes o conexiones lentas. Entero positivo, valor predeterminado 30, máximo 600. Los valores mayores se limitan a 600 con una advertencia; cualquier otro valor no válido se registra como advertencia y se usa 30

Se aplica toda la configuración común, con estas diferencias respecto al servidor operativo:

  • El puerto predeterminado es 8001 y el archivo de registro predeterminado es mcp_server_operational_insights.log, para que ambos servidores puedan ejecutarse en paralelo.
  • Solo se admite un trabajador (CB_MCP_WORKERS=1), porque los identificadores de consulta asíncrona residen en la memoria del proceso.
  • No tiene opciones CB_MCP_EMBEDDING_MODEL_*.

Herramientas de Operational Insights

Todos los nombres, excepto get_server_configuration_status, llevan el prefijo operational_insights_, para que ambos servidores puedan registrarse en un mismo cliente sin colisiones. La herramienta de escritura (marcada con ✏️) no se carga mientras está activado el modo de solo lectura, que es el predeterminado.

Estado del servidor

HerramientaDescripción
get_server_configuration_statusLa misma herramienta que en el servidor operativo

Detección del modelo de datos y el esquema

HerramientaDescripción
operational_insights_get_databases_in_clusterEnumerar bases de datos
operational_insights_get_scopes_in_databaseEnumerar ámbitos de una base de datos
operational_insights_get_collections_in_scopeEnumerar colecciones (conjuntos de datos) de un ámbito
operational_insights_get_schema_for_collectionInferir el esquema JSON de una colección mediante muestreo

Consultas e índices

HerramientaDescripción
operational_insights_list_indexesEnumerar índices secundarios de System.Metadata.Index
operational_insights_explain_queryExplicar una instrucción SQL++ sin ejecutarla
operational_insights_run_query_syncEjecutar SQL++ y devolver filas, hasta el límite de tamaño del resultado; también puede exportar. El modo de solo lectura se aplica en el servidor
operational_insights_run_query_asyncIniciar una consulta de larga duración y devolver un query_handle sin esperar las filas; también es la opción preferida para exportaciones grandes. El modo de solo lectura se aplica en el servidor
operational_insights_get_async_query_resultsConsultar una consulta asíncrona; devuelve filas (o el destino de exportación) cuando está lista
operational_insights_discard_async_query_resultsLiberar los resultados de una consulta asíncrona finalizada
operational_insights_cancel_async_queryDetener una consulta asíncrona que aún se está ejecutando (permitido en modo de solo lectura)
operational_insights_create_index ✏️Crear un índice secundario mediante CREATE INDEX

Las consultas asíncronas siguen un flujo de inicio → consulta periódica → descarte o cancelación: operational_insights_run_query_async devuelve un query_handle, se consulta operational_insights_get_async_query_results hasta que esté lista y, luego, operational_insights_discard_async_query_results libera los resultados o operational_insights_cancel_async_query detiene una consulta que aún se está ejecutando.

Exportación de resultados grandes

En lugar de devolver filas, operational_insights_run_query_sync y operational_insights_run_query_async pueden envolver la instrucción en COPY ... TO y escribir las filas en un almacenamiento de objetos externo. Proporcione los tres elementos copy_to_link (un enlace existente creado con CREATE LINK ... TYPE S3), copy_to_bucket y copy_to_path, además de copy_to_format opcionalmente (json, el valor predeterminado, o parquet). La herramienta devuelve entonces una confirmación sin filas:

{
  "success": true,
  "exported": true,
  "destination": {"link": "s3Link", "bucket": "my-exports", "path": "exports/run1", "format": "json"},
  "message": "Results were written to my-exports/exports/run1 as json. ..."
}
  • Se rechaza un destino incompleto en lugar de devolver filas silenciosamente.
  • La herramienta síncrona espera a que finalice toda la carga; para exportaciones grandes, prefiera la herramienta asíncrona.
  • Las exportaciones están bloqueadas en modo de solo lectura (escriben en almacenamiento externo), por lo que requieren CB_MCP_READ_ONLY_MODE=false o un token con couchbase-mcp:write.
  • csv no está disponible, porque necesita un esquema de salida explícito que no se puede inferir de un SELECT arbitrario.

Configuración común

Estos ajustes funcionan de la misma manera en ambos servidores. Cada opción se puede establecer como variable de entorno o como indicador de CLI después del subcomando.

Controles de seguridad

Siga estos principios de seguridad:

  • Otorgue al usuario de la base de datos los privilegios mínimos: RBAC es el límite de seguridad autoritativo (véase más abajo).
  • Proporcione solo las herramientas que necesita el agente y desactive las demás: cada herramienta cargada es algo que el LLM puede invocar. Use el modo de solo lectura y CB_MCP_DISABLED_TOOLS para reducir al mínimo la lista de herramientas.
  • Exija confirmación para las herramientas sensibles que conserve; consulte Exigir confirmación.

Los controles siguientes forman tres capas, de la más amplia a la más específica. Úselos conjuntamente, pero recuerde que ninguno sustituye a RBAC.

[!IMPORTANT] Los permisos RBAC del usuario de la base de datos son el control de seguridad autoritativo. Por ejemplo, desactivar upsert_document_by_id y delete_document_by_id no impide que run_sql_plus_plus_query ejecute INSERT/UPDATE/DELETE/MERGE; solo lo impiden el modo de solo lectura o la falta de permisos RBAC. Otorgue al usuario de la base de datos del servidor únicamente los permisos que necesita.

Modo de solo lectura

CB_MCP_READ_ONLY_MODE (predeterminado true) es el único interruptor para las escrituras:

  • true: las herramientas de escritura marcadas con ✏️ en la lista de herramientas de cada servidor no se cargan, y se bloquean las consultas que modifican datos o estructuras.
  • false: se cargan las herramientas de escritura y se permiten las consultas que modifican datos o estructuras.

Desactivación de herramientas

CB_MCP_DISABLED_TOOLS elimina herramientas por completo de la detección. Acepta una lista separada por comas o la ruta a un archivo con un nombre de herramienta por línea (# inicia un comentario):

CB_MCP_DISABLED_TOOLS="upsert_document_by_id,delete_document_by_id"
# or
CB_MCP_DISABLED_TOOLS=/path/to/disabled_tools.txt
# disabled_tools.txt
# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

En Capella, el servidor operativo también desactiva automáticamente algunas herramientas de administración.

Exigir confirmación (elicitación)

CB_MCP_CONFIRMATION_REQUIRED_TOOLS solicita al usuario que confirme antes de ejecutar una herramienta de la lista, mediante la elicitación de MCP. Acepta los mismos formatos de lista separada por comas o archivo que las herramientas desactivadas:

CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"
  • Si el cliente admite la elicitación, se solicita confirmación al usuario antes de ejecutar la herramienta.
  • Si no la admite, la herramienta se ejecuta sin confirmación, por compatibilidad con versiones anteriores.
  • La confirmación requiere una sesión MCP, por lo que no se puede combinar con HTTP sin estado (CB_MCP_STATELESS_HTTP=true o CB_MCP_WORKERS superior a 1). El servidor se niega a iniciarse con esa combinación. Detrás de un balanceador de carga, la confirmación requiere sesiones persistentes; consulte Balanceadores de carga.

Transportes

TransporteSe usa paraEndpoint
stdio (predeterminado)Un cliente local que inicia el servidor como subproceso—
httpVarios clientes que comparten un servidor; admite OAuth, comprobaciones de estado y trabajadores en el servidor operativohttp://<host>:<port>/mcp

Configure el transporte con CB_MCP_TRANSPORT, la dirección de enlace con CB_MCP_HOST (predeterminada 127.0.0.1) y el puerto con CB_MCP_PORT (el puerto predeterminado de cada servidor si no se configura). Sin OAuth, el endpoint HTTP no requiere autenticación.

uvx couchbase-mcp-server operational \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http

A continuación, configure el cliente para que use la URL:

{
  "mcpServers": {
    "couchbase-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Varios trabajadores

Un proceso utiliza como máximo aproximadamente un núcleo de CPU. --workers N (CB_MCP_WORKERS) ejecuta N procesos detrás del mismo host y puerto; el número de núcleos disponibles es un buen punto de partida. Solo el servidor operativo admite trabajadores. Con más de un trabajador:

  • Se requiere el transporte http y el servidor se ejecuta en modo HTTP sin estado, porque las solicitudes de un cliente pueden llegar a distintos trabajadores. También puede configurar --stateless-http=true con un solo trabajador, por ejemplo, detrás de un balanceador de carga sin sesiones persistentes.
  • No se pueden usar las herramientas que requieren confirmación.
  • Cada proceso escribe sus propios archivos de registro, identificados por host e ID de proceso (mcp_server.<host>.<pid>.info.log): un conjunto para el supervisor y otro por cada trabajador.

Balanceadores de carga

Puede ejecutar varias instancias del servidor detrás de un balanceador de carga. Cada instancia mantiene sus sesiones MCP en su propia memoria, por lo que la configuración del balanceador determina qué funciona:

Balanceador de cargaConfiguración del servidorHerramientas que requieren confirmación
Sesiones persistentes, enrutadas según el encabezado de solicitud Mcp-Session-IdUn trabajador, con estado (predeterminado)Admitidas
Sin sesiones persistentes--stateless-http=trueNo admitidas: el servidor se niega a iniciarse si están configuradas
  • Sin sesiones persistentes, una instancia con estado rechaza todas las solicitudes cuya sesión se haya creado en otra instancia. En ese caso, use el modo sin estado.
  • Enrute según el encabezado Mcp-Session-Id, no según las cookies. Muchos clientes MCP no conservan las cookies.
  • Si una instancia se reinicia o se produce una conmutación por error, se pierden sus sesiones y cualquier solicitud de confirmación pendiente. El cliente debe iniciar una sesión nueva.
  • Las consultas asíncronas de Operational Insights mantienen su query_handle en la memoria de la instancia que inició la consulta, también en modo sin estado. Consultar, descartar o cancelar la consulta en otra instancia devuelve Unknown query_handle. Use estas herramientas con una sola instancia o con sesiones persistentes para que todas las llamadas lleguen a la instancia que inició la consulta. El modo sin estado no envía Mcp-Session-Id, por lo que necesita otra clave de afinidad, como la dirección IP del cliente.

Comprobación de estado

En modo HTTP, GET /health devuelve {"status": "ok", "server": "<server>"} en el puerto MCP. Es una comprobación de disponibilidad: no se conecta al clúster (por lo que una interrupción del clúster no reinicia contenedores que funcionan correctamente), no requiere autenticación aunque OAuth esté habilitado y la atienden todos los trabajadores. Consulte Docker para ver ejemplos de sondas.

Autorización OAuth 2.1

Con --transport=http, cualquiera de los servidores puede actuar como servidor de recursos OAuth 2.1 y validar JWT de portador con el JWKS de su proveedor de identidad. Funciona con cualquier proveedor OAuth 2.1/OIDC que publique un JWKS y no emite tokens ni administra usuarios. La configuración de OAuth se ignora en stdio.

  • OAuth se activa solo cuando se configuran los tres elementos CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER y CB_MCP_OAUTH_JWT_AUDIENCE; si solo se configuran algunos, el inicio falla.
  • CB_MCP_OAUTH_MCP_BASE_URL también publica metadatos de recursos protegidos RFC 9728 para que los clientes puedan detectar el servidor de autorización.
  • El acceso se controla mediante dos ámbitos en la declaración scope/scp del token: couchbase-mcp:read (herramientas de lectura) y couchbase-mcp:write (herramientas de escritura). El acceso completo requiere ambos. Cámbielos con CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL si su IdP no puede emitir estas etiquetas. Ambos servidores usan las mismas etiquetas, por lo que una sola configuración de IdP sirve para los dos.
uvx couchbase-mcp-server operational \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http \
  --oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
  --oauth-issuer='https://auth.example.com/' \
  --oauth-audience='couchbase-mcp-server' \
  --oauth-mcp-base-url='<public_base_url_of_this_server>'

Consulte la documentación de OAuth del servidor operativo y del servidor Operational Insights para configurar el IdP.

Registro

De forma predeterminada, cada servidor registra en stderr con el nivel info.

  • CB_MCP_LOG_LEVEL — off, error, warning, info (eventos del ciclo de vida y llamadas a herramientas) o debug.
  • CB_MCP_LOG_SINKS — stderr, file o ambos. Con file, se escribe un archivo rotativo por nivel junto a CB_MCP_LOG_FILE (mcp_server.info.log, mcp_server.error.log, …).
  • Rotación y retención — CB_MCP_LOG_ROTATION_MAX_SIZE_MB (1 MB de forma predeterminada) y CB_MCP_LOG_RETENTION_BACKUP_COUNT (1 de forma predeterminada) se aplican a todos los niveles; se pueden anular por nivel con CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB / CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT. Los tamaños no válidos recurren al valor predeterminado y generan una advertencia al iniciar. CB_MCP_LOG_MAX_BYTES está obsoleto.
  • Instantánea de configuración — con el destino file, se escribe un registro JSON del entorno y de la configuración del servidor con datos confidenciales ocultos en mcp_server_config.log.json en cada inicio, para facilitar el soporte.
# Debug logging to stderr and rotating per-level files
uvx couchbase-mcp-server operational --log-level=debug --log-sinks=stderr,file

Tu cliente MCP normalmente también captura stderr del servidor; consulta Configuración del cliente para saber dónde. Detalles: documentación de registro para el servidor operativo y el servidor Operational Insights.

Auditoría

El registro de auditoría registra quién hizo qué y si se permitió — por separado de los registros operativos, que registran lo que salió mal. El servidor MCP es la única capa que puede responder a esto para un agente: cada solicitud llega al clúster como un único usuario de base de datos, y decisiones como denegar un ámbito, bloquear una operación de solo lectura o rechazar una confirmación nunca llegan al clúster.

La auditoría está desactivada de forma predeterminada. Actívala con CB_MCP_AUDIT_LOG_ENABLED=true; escribe en stderr, a menos que configures CB_MCP_AUDIT_LOG_SINKS=file y CB_MCP_AUDIT_LOG_FILE_PATH.

# 90 days of daily, gzipped audit files
uvx couchbase-mcp-server operational --audit-log-enabled=true \
  --audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
  --audit-log-rotation-interval=1d --audit-log-rotation-max-size-mb=0 \
  --audit-log-retention-max-backups=90

Los registros son JSON Lines y usan el mismo vocabulario de campos que Couchbase Server y Sync Gateway:

{"id":61522,"name":"document write","description":"A document write operation was requested through a tool","timestamp":"2026-09-29T09:14:22.418Z","real_userid":{"domain":"oauth","user":"agent-svc-7"},"server":{"version":"1.0.2","host":"mcp-01"},"cid":"9f2c...","outcome":"success","tool_name":"upsert_document_by_id","required_scope":"write","ks":"travel-sample.inventory.airline","cb_userid":"mcp_service"}
Cómo funciona la auditoría
  • Identidad — real_userid es quien realiza la llamada: oauth (el sujeto del token), local (el usuario del sistema operativo, en stdio) o anonymous (HTTP sin OAuth, que genera una advertencia al iniciar).
  • Correlación — cid agrupa todos los registros de una solicitud y se envía como client_context_id de SQL++, por lo que se une exactamente con clientContextId de Couchbase Server. Deliberadamente no hay identificador de sesión.
  • Eventos — un catálogo fijo y numerado (ciclo de vida, inicialización, token rechazado, ámbito denegado, bloqueo de solo lectura, confirmación rechazada/omitida y un par de lectura/escritura por categoría de herramienta). query y search son las excepciones: cada uno se registra como un único evento en lugar de un par de lectura/escritura, porque no se pudo distinguir de forma fiable en las superficies basadas en instrucciones y de búsqueda. Las operaciones vectoriales se incluyen en esas dos categorías. El catálogo completo se incluye como descriptor.json en el paquete. El servidor operativo usa el bloque 0xF000 (61440), Operational Insights usa 0x10000 (65536) y ambos comparten 0xE000 (57344) para los eventos principales.
  • Filtrado — CB_MCP_AUDIT_LOG_DISABLED_EVENTS suprime los eventos de lectura por ID numérico (p. ej., 61490,61492). Los eventos de escritura y seguridad no se pueden desactivar, como tampoco las categorías de evento único query (61507, o 65603 en Operational Insights) y search (61510): un evento cubre tanto las escrituras como las lecturas de cada categoría, por lo que desactivarlo haría que se perdiera un registro de mutación.
  • Rotación — por tamaño (CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB, 10 de forma predeterminada) y antigüedad (CB_MCP_AUDIT_LOG_ROTATION_INTERVAL, 1d de forma predeterminada), lo que ocurra primero; 0 desactiva cualquiera de las dos. Los archivos rotados llevan una marca de tiempo y se comprimen con gzip; el archivo activo permanece como texto sin formato para tail -f.
  • Archivos por proceso — se insertan el host y el PID en el nombre (audit.log → audit.<host>.<pid>.log), de modo que los procesos simultáneos nunca comparten un archivo.
  • La retención se aplica por archivo — CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS (10 de forma predeterminada) limita las copias de seguridad de un archivo. Cada proceso nuevo escribe un archivo nuevo y no elimina los anteriores, así que dimensiona el volumen o limpia los archivos audit.*.log* antiguos.
  • Continuidad ante fallos — si no se puede escribir el archivo, el servidor sigue atendiendo solicitudes y cuenta los registros descartados; get_server_configuration_status informa de written / dropped / write_errors.
  • Argumentos de herramientas — solo se registran con CB_MCP_AUDIT_LOG_TOOL_ARGS=true, que genera una advertencia al iniciar. En esta versión no hay ocultación de datos, por lo que los argumentos, incluidos los cuerpos completos de los documentos, se escriben literalmente.

Configuración del cliente

Cada cliente necesita una configuración del servidor, tomada del inicio rápido operativo o de Operational Insights, en su propia ubicación de configuración. Los ejemplos siguientes usan el servidor operativo.

Claude Desktop
  1. Abre el archivo de configuración (consulta la guía de inicio rápido de MCP):
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Añade el servidor en mcpServers y reinicia Claude Desktop.

Registros: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. Consulta la guía de solución de problemas de MCP.

Cursor
  1. Ve a Cursor Settings > Tools & Integrations > MCP Tools (consulta la documentación de MCP de Cursor), o usa el enlace de un solo clic Instalar en Cursor y luego sustituye la cadena de conexión y las credenciales de marcador de posición.
  2. Añade la configuración en mcpServers y guárdala.
  3. Actualiza la lista de servidores MCP para comprobar que couchbase esté habilitado.

Registros: en el panel inferior, abre Output y selecciona Cursor MCP.

Windsurf Editor
  1. Abre Command Palette > Windsurf MCP Configuration Panel o Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (consulta la documentación de MCP de Windsurf).
  2. Haz clic en Add Server > Add custom server, pega la configuración y guárdala.
  3. Actualiza la lista de servidores para comprobar que couchbase esté habilitado.
VS Code

VS Code usa servers como clave de nivel superior en lugar de mcpServers. Coloca la configuración en .vscode/mcp.json para un espacio de trabajo, o ejecuta MCP: Open User Configuration para todos los espacios de trabajo (consulta la documentación de MCP de VS Code):

{
  "servers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

Al guardar el archivo se inicia el servidor; usa las acciones Running | Stop | n Tools que aparecen encima para administrarlo.

Registros: ejecuta MCP: List Servers, selecciona couchbase y luego Show Output.

JetBrains IDEs
  1. Instala el complemento AI Assistant o Junie.
  2. Ve a Settings > Tools > AI Assistant (or Junie) > MCP Server, haz clic en +, añade la configuración y haz clic en Apply.
  3. Pasa el cursor sobre el estado del servidor para ver sus herramientas.

Registros: Help > Show Log in Finder (Explorer) > mcp > couchbase.

Docker

Las imágenes precompiladas se publican en Docker Hub como couchbase/mcp-server, y el servidor aparece en el catálogo MCP de Docker. Configura el contenedor con las mismas variables de entorno indicadas anteriormente. Consulta la página de Docker Hub (DOCKER.md) para ver ejemplos de etiquetas, volúmenes y comprobaciones de estado.

Ejecución mediante HTTP: ten en cuenta que el servidor debe enlazarse a 0.0.0.0 para que sea accesible desde fuera del contenedor:

docker run --rm \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT=http \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 8000:8000 \
  couchbase/mcp-server:latest operational
  • Si Couchbase se ejecuta en tu máquina anfitriona, usa couchbase://host.docker.internal como cadena de conexión (consulta Redes de Docker). Usa --network=<your_network> para unirte a la red de otro contenedor.
  • Añade operational-insights en lugar de operational para ejecutar el servidor Operational Insights (puerto 8001).
Compilar la imagen desde el código fuente
docker build -t mcp/couchbase-src .

./build.sh [image-name] compila con los mismos argumentos que CI: establece los argumentos de compilación GIT_COMMIT_HASH y BUILD_DATE, y etiqueta la imagen como latest y <short-commit> (nombre predeterminado: mcp/couchbase-src). Para compilar manualmente con las etiquetas:

docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mcp/couchbase-src .

# Check the labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest

Solución de problemas

Para consultar las guías completas, visita la documentación de solución de problemas del servidor operativo y del servidor Operational Insights, así como las directrices de seguridad del servidor operativo y del servidor Operational Insights. Comprobaciones rápidas:

  • Comprueba la cadena de conexión, el nombre de usuario y la contraseña, o las rutas de los certificados.
  • Para Capella, asegúrate de que el clúster permita conexiones desde la máquina que ejecuta el servidor.
  • Asegúrate de que el usuario de la base de datos pueda acceder al menos a un bucket.
  • Si el cliente no encuentra uv/uvx, indica la ruta absoluta en command.
  • Si ejecutas desde el código fuente, comprueba la ruta del repositorio en la configuración y ejecuta uv sync después de descargar las actualizaciones.
  • Llama a get_server_configuration_status para ver la configuración que el servidor resolvió realmente y comprueba los registros de tu cliente (consulta Configuración del cliente).

Preguntas frecuentes

¿Cómo conecto Claude Desktop a Couchbase? Añade la configuración de inicio rápido a claude_desktop_config.json y reinicia Claude Desktop; consulta Configuración del cliente.

¿Puedo usarlo con Couchbase Capella? Sí, con el servidor operativo: la misma configuración funciona con Capella y con clústeres autogestionados, aunque algunas herramientas de administración solo están disponibles en clústeres autogestionados (consulta Herramientas). El servidor Operational Insights es solo para clústeres autogestionados de Operational Insights.

¿Es seguro permitir que un agente de IA escriba en mi base de datos? De forma predeterminada, no se carga ninguna herramienta de escritura y se bloquea SQL++ que modifica datos. Si habilitas las escrituras, aún puedes desactivar herramientas individuales o exigir confirmación, pero los permisos RBAC de tu usuario de Couchbase siguen siendo el límite de seguridad real. Consulta Controles de seguridad.

¿Necesito saber SQL++? No. Pregunta en lenguaje natural y el asistente escribirá SQL++ para run_sql_plus_plus_query. También puede explicar un plan de consulta o pedir recomendaciones al asesor de índices.

¿STDIO o Streamable HTTP? STDIO para un único cliente local. Streamable HTTP para compartir un servidor entre clientes, con OAuth. Consulta Transportes.

¿Couchbase ofrece soporte oficial para esto? Sí, con una licencia de Couchbase AI Data Plane. Sin ella, los ingenieros de Couchbase ofrecen ayuda según su disponibilidad a través de incidencias de GitHub. Consulta la Política de soporte.

Contribuciones

Se agradecen las contribuciones: correcciones de errores, funciones y documentación. Para informar de un error o pedir ayuda, abre una incidencia en GitHub.

Consulta CONTRIBUTING.md para obtener información sobre la configuración del entorno de desarrollo, el análisis estático, las pruebas, la estructura del proyecto y el flujo de trabajo. Para empezar:

git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase
uv sync --extra dev
uv run pre-commit install
./scripts/lint.sh

Las pruebas de integración se ejecutan contra un clúster activo. Exporta CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD y, opcionalmente, CB_MCP_TEST_BUCKET; las pruebas de Operational Insights también usan CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / _USERNAME / _PASSWORD y se omiten si esas variables no están definidas. Luego ejecuta:

uv run --extra dev pytest tests/integration -v

Datos de uso, riesgos de los LLM y política de soporte

Recopilación de datos de uso

Este producto recopila automáticamente datos de uso y rendimiento (como el nombre y la versión del producto) e información del navegador (como la dirección IP) (en conjunto, «Datos de uso»). Couchbase utiliza los Datos de uso, junto con otros datos que usted pueda proporcionar a Couchbase (como su nombre de usuario o dirección de correo electrónico), para desarrollar y mejorar nuestros productos, así como para informar nuestros programas de ventas y marketing. No accedemos a ningún dato que almacene en los productos de Couchbase ni lo recopilamos. Utilizamos los Datos de uso para comprender los patrones de uso agregados y hacer que nuestros productos le resulten más útiles. Para obtener más información sobre cómo Couchbase recopila, protege y procesa la información, consulte la Política de privacidad de Couchbase, disponible en https://www.couchbase.com/privacy-policy.

Riesgos asociados con los LLM

  • El uso de modelos de lenguaje grandes y tecnologías similares conlleva riesgos, incluida la posibilidad de generar resultados inexactos o perjudiciales.
  • Couchbase no revisa ni evalúa la calidad o exactitud de dichos resultados, y estos podrían no reflejar las opiniones de Couchbase.
  • Usted es el único responsable de decidir si utiliza modelos de lenguaje grandes y tecnologías relacionadas, así como de cumplir las condiciones de licencia, las condiciones de uso y las políticas de su organización que rigen su uso.

Política de soporte

Couchbase MCP Server es de código abierto y cuenta con el mantenimiento de ingenieros de Couchbase. La forma de obtener ayuda depende de cómo lo utilice:

  • Uso comunitario — informe de errores, haga preguntas y solicite funciones abriendo un issue en GitHub. Los ingenieros de Couchbase supervisan el repositorio y responden según sus posibilidades, sin compromiso de tiempo de respuesta. El portal de soporte de Couchbase no puede ayudar con el uso comunitario.
  • Soporte empresarial — disponible mediante la licencia de Couchbase AI Data Plane, que también cubre Couchbase Agent Memory y Couchbase Agent Catalog. Los clientes con licencia reciben ayuda a través de sus canales habituales de soporte de Couchbase.

¡Gracias por utilizar el proyecto y contribuir a él!