Couchbase
oficialInteractú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.
Documentación completa: docs.couchbase.com/mcp-server
Tabla de contenido
- Por qué Couchbase MCP Server
- Cómo elegir un servidor
- Servidor operativo
- Servidor Operational Insights
- Configuración común
- Configuración del cliente
- Docker
- Solución de problemas
- Preguntas frecuentes
- Contribuciones
- Datos de uso, riesgos de los LLM y política de soporte
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
usersdondestatus = '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
productscon estos campos: …» (requiereCB_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 operativo | Servidor Operational Insights | |
|---|---|---|
| Úsalo con | Un clúster de Couchbase (Capella o autogestionado) | Un clúster autogestionado de Operational Insights (no disponible en Capella) |
| Subcomando | operational (predeterminado) | operational-insights |
| Cadena de conexión | couchbase:// / couchbases:// | URL HTTP(S), p. ej., http://localhost:8095 |
| Variables de credenciales | CB_CONNECTION_STRING, CB_USERNAME, … | CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, … |
| Herramientas | 52: estado del clúster, esquema, KV, SQL++, índices, búsqueda de texto completo y vectorial, rendimiento de consultas | 13: esquema, SQL++ (síncrono y asíncrono), índices, exportaciones |
| Puerto HTTP predeterminado | 8000 | 8001 |
| Archivo de registro predeterminado | mcp_server.log | mcp_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 conuvx 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 entorno | Argumento de CLI | Descripción |
|---|---|---|
CB_CONNECTION_STRING | --connection-string | Cadena de conexión al clúster. Obligatoria |
CB_USERNAME / CB_PASSWORD | --username / --password | Autenticación básica |
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH | --client-cert-path / --client-key-path | Autenticación mTLS |
CB_CA_CERT_PATH | --ca-cert-path | Certificado 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
| Herramienta | Descripción |
|---|---|
get_server_configuration_status | Estado 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_connection | Comprueba las credenciales del clúster conectándote a él |
get_cluster_health_and_services | Estado del clúster y servicios en ejecución, con filtrado opcional mediante service_types |
get_client_connectivity_report | Diagnó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
| Herramienta | Descripción |
|---|---|
get_buckets_in_cluster | Enumera todos los buckets del clúster |
get_scopes_in_bucket | Enumera todos los scopes de un bucket |
get_collections_in_scope | Enumera todas las collections de un scope (requiere el servicio Query) |
get_scopes_and_collections_in_bucket | Enumera todos los scopes y collections de un bucket |
get_schema_for_collection | Deduce 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)
| Herramienta | Descripción |
|---|---|
get_document_by_id | Obtiene un documento por ID |
lookup_subdocument | Lee 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
| Herramienta | Descripción |
|---|---|
run_sql_plus_plus_query | Ejecuta 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_query | Genera y evalúa un plan EXPLAIN: metadatos, plan extraído y hallazgos |
get_index_advisor_recommendations | Recomendaciones de Index Advisor para una consulta SQL++ |
list_indexes | Enumera í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.
| Herramienta | Descripción |
|---|---|
list_search_indexes | Lista los índices de Search: a nivel de clúster, por bucket o por scope |
get_search_index_definition | Definición completa de un índice de Search (asignaciones, analizadores, parámetros del plan) |
run_search | Ejecuta 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.
| Herramienta | Descripción |
|---|---|
run_vector_query | Bú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_search | Bú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
| Herramienta | Descripción |
|---|---|
get_longest_running_queries | Consultas de mayor duración según el tiempo medio de servicio |
get_most_frequent_queries | Consultas ejecutadas con mayor frecuencia |
get_queries_with_largest_response_sizes | Consultas con los tamaños de respuesta más grandes |
get_queries_with_large_result_count | Consultas con la mayor cantidad de resultados |
get_queries_using_primary_index | Consultas que usan un índice primario |
get_queries_not_using_covering_index | Consultas que no usan un índice de cobertura |
get_queries_not_selective | Consultas 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.
| Herramienta | Descripción |
|---|---|
get_cluster_query_vitals | Estado del motor de consultas: tasa de solicitudes, solicitudes activas/en cola, memoria, GC y tiempo de actividad. Requiere ro_admin |
get_active_queries | Consultas 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.
| Herramienta | Endpoint necesario |
|---|---|
get_cluster_metrics | REST de administración (/pools/default/stats/range) |
get_cluster_tasks | REST de administración (/pools/default/tasks) |
get_bucket_config | REST de administración (/pools/default/buckets[/<name>]) |
get_cluster_health_snapshot | REST de administración, además de endpoints por nodo |
get_cluster_system_events | REST de administración (/events) |
get_index_stats | REST del servicio Index (el /api/v1/stats de cada indexador) |
get_cluster_query_vitals | REST del servicio Query (/admin/vitals) |
get_active_queries | REST del servicio Query (/admin/active_requests) |
delete_active_query | REST del servicio Query (DELETE /admin/active_requests/{id}) |
discover_tool_input_values | Ninguno (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_PROVIDER | Obligatorio | Opcional | Notas |
|---|---|---|---|
capella | CB_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 |
openai | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | Establece el endpoint para usar un servidor local compatible con OpenAI (Ollama, vLLM, LM Studio) |
cohere | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
voyage | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
bedrock | CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID, CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY, CB_MCP_EMBEDDING_MODEL_AWS_REGION | Modelos 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 entorno | Argumento de CLI | Descripción | Valor predeterminado |
|---|---|---|---|
CB_CONNECTION_STRING | --connection-string | Cadena de conexión al clúster de Couchbase | Obligatorio |
CB_USERNAME | --username | Nombre de usuario con acceso a los buckets necesarios para la autenticación básica | Obligatorio (o se necesitan el certificado y la clave del cliente para mTLS) |
CB_PASSWORD | --password | Contraseña para la autenticación básica | Obligatorio (o se necesitan el certificado y la clave del cliente para mTLS) |
CB_CLIENT_CERT_PATH | --client-cert-path | Ruta al archivo de certificado del cliente para la autenticación mTLS | Obligatorio si se usa mTLS (o se necesitan el nombre de usuario y la contraseña) |
CB_CLIENT_KEY_PATH | --client-key-path | Ruta al archivo de clave del cliente para la autenticación mTLS | Obligatorio si se usa mTLS (o se necesitan el nombre de usuario y la contraseña) |
CB_CA_CERT_PATH | --ca-cert-path | Ruta 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-mode | Impide 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 | --transport | Modo de transporte: stdio, http | stdio |
CB_MCP_HOST | --host | Host para el modo de transporte HTTP | 127.0.0.1 |
CB_MCP_PORT | --port | Puerto para el modo de transporte HTTP | 8000 |
CB_MCP_WORKERS | --workers | Nú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-http | Gestiona 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-tools | Herramientas que se deshabilitarán (consulta Deshabilitar herramientas) | Ninguna |
CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | Herramientas 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-level | Nivel de registro del servidor MCP: off, debug, info, warning, error (consulta Registro) | info |
CB_MCP_LOG_SINKS | --log-sinks | Destinos de registro separados por comas: stderr, file o ambos (consulta Registro) | stderr |
CB_MCP_LOG_FILE | --log-file | Ruta 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-mb | Tamañ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 iniciar | 1 (1 MB) |
CB_MCP_LOG_MAX_BYTES | --log-max-bytes | Obsoleto — 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_MB | Sin establecer |
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB | --log-error-rotation-max-size-mb | Tamaño de rotación en MB para el archivo de registro ERROR; sobrescribe CB_MCP_LOG_ROTATION_MAX_SIZE_MB para ERROR | Hereda CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB | --log-warning-rotation-max-size-mb | Tamaño de rotación en MB para el archivo de registro WARNING; sobrescribe CB_MCP_LOG_ROTATION_MAX_SIZE_MB para WARNING | Hereda CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB | --log-info-rotation-max-size-mb | Tamaño de rotación en MB para el archivo de registro INFO; sobrescribe CB_MCP_LOG_ROTATION_MAX_SIZE_MB para INFO | Hereda CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB | --log-debug-rotation-max-size-mb | Tamaño de rotación en MB para el archivo de registro DEBUG; sobrescribe CB_MCP_LOG_ROTATION_MAX_SIZE_MB para DEBUG | Hereda CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_RETENTION_BACKUP_COUNT | --log-retention-backup-count | Archivos 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-count | Copias de seguridad rotadas que se conservan para el archivo de registro ERROR; sobrescribe el recuento global para ERROR | Hereda CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT | --log-warning-retention-backup-count | Copias de seguridad rotadas que se conservan para el archivo de registro WARNING; sobrescribe el recuento global para WARNING | Hereda CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT | --log-info-retention-backup-count | Copias de seguridad rotadas que se conservan para el archivo de registro INFO; sobrescribe el recuento global para INFO | Hereda CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT | --log-debug-retention-backup-count | Copias de seguridad rotadas que se conservan para el archivo de registro DEBUG; sobrescribe el recuento global para DEBUG | Hereda CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_OAUTH_JWT_JWKS_URI | --oauth-jwks-uri | Punto 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-issuer | Claim iss esperado del JWT. Obligatorio para habilitar OAuth | Ninguno |
CB_MCP_OAUTH_JWT_AUDIENCE | --oauth-audience | Claim aud esperado del JWT. Obligatorio para habilitar OAuth | Ninguno |
CB_MCP_OAUTH_JWT_ALGORITHM | --oauth-algorithm | Algoritmo de firma JWT: uno de RS256/384/512, ES256/384/512, PS256/384/512 | RS256 |
CB_MCP_OAUTH_MCP_BASE_URL | --oauth-mcp-base-url | URL 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 IdP | Ninguno |
CB_MCP_OAUTH_SCOPE_READ_LABEL | --oauth-scope-read-label | Sobrescribe 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ónica | couchbase-mcp:read |
CB_MCP_OAUTH_SCOPE_WRITE_LABEL | --oauth-scope-write-label | Sobrescribe la etiqueta de ámbito OAuth que se trata como acceso de «escritura»; tiene la misma semántica que la etiqueta de lectura | couchbase-mcp:write |
CB_MCP_AUDIT_LOG_ENABLED | --audit-log-enabled | Habilita 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-sinks | Destinos 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-path | Ruta 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-mb | Tamaño máximo en MB que puede alcanzar el archivo de auditoría activo antes de rotarse. 0 desactiva la rotación por tamaño | 10 (10 MB) |
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL | --audit-log-rotation-interval | Antigü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 intervalo | 1d |
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS | --audit-log-retention-max-backups | Copias 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ía | 10 |
CB_MCP_AUDIT_LOG_TOOL_ARGS | --audit-log-tool-args | Registra 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-events | Eventos 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 filtrables | Ninguno |
CB_MCP_EMBEDDING_MODEL_PROVIDER | --embedding-model-provider | Proveedor 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 embeddings | Ninguno |
CB_MCP_EMBEDDING_MODEL | --embedding-model | Nombre/ID del modelo para el proveedor de embeddings configurado | Ninguno |
CB_MCP_EMBEDDING_MODEL_API_KEY | --embedding-model-api-key | Clave 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-endpoint | Sobrescritura 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-id | ID de clave de acceso de AWS; solo para el proveedor bedrock. Omítelo para usar la cadena de credenciales predeterminada de AWS | Ninguno |
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY | --embedding-model-aws-secret-access-key | Clave de acceso secreta de AWS; solo para el proveedor bedrock | Ninguno |
CB_MCP_EMBEDDING_MODEL_AWS_REGION | --embedding-model-aws-region | Regió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 AWS | Ninguno |
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_STRINGes una URL HTTP(S), no una cadena de conexióncouchbase://; por ejemplo,http://localhost:8095ohttps://<host>:18095con 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 entorno | Argumento de CLI | Descripción |
|---|---|---|
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING | --connection-string | URL del endpoint (HTTP/HTTPS). Obligatorio |
CB_OPERATIONAL_INSIGHTS_USERNAME | --username | Nombre de usuario |
CB_OPERATIONAL_INSIGHTS_PASSWORD | --password | Contraseña |
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH | --ca-cert-path | Certificado raíz (PEM) para un certificado de servidor autofirmado o no confiable |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH | --client-cert-path | Certificado 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-path | Clave privada (PEM) del certificado de cliente. Déjela sin configurar para PKCS#12 |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD | --client-cert-password | Contraseña de una clave cifrada o un paquete PKCS#12 |
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE | --operational-insights-query-result-max-size | Tamañ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-timeout | Tiempo 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
8001y el archivo de registro predeterminado esmcp_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
| Herramienta | Descripción |
|---|---|
get_server_configuration_status | La misma herramienta que en el servidor operativo |
Detección del modelo de datos y el esquema
| Herramienta | Descripción |
|---|---|
operational_insights_get_databases_in_cluster | Enumerar bases de datos |
operational_insights_get_scopes_in_database | Enumerar ámbitos de una base de datos |
operational_insights_get_collections_in_scope | Enumerar colecciones (conjuntos de datos) de un ámbito |
operational_insights_get_schema_for_collection | Inferir el esquema JSON de una colección mediante muestreo |
Consultas e índices
| Herramienta | Descripción |
|---|---|
operational_insights_list_indexes | Enumerar índices secundarios de System.Metadata.Index |
operational_insights_explain_query | Explicar una instrucción SQL++ sin ejecutarla |
operational_insights_run_query_sync | Ejecutar 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_async | Iniciar 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_results | Consultar una consulta asíncrona; devuelve filas (o el destino de exportación) cuando está lista |
operational_insights_discard_async_query_results | Liberar los resultados de una consulta asíncrona finalizada |
operational_insights_cancel_async_query | Detener 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=falseo un token concouchbase-mcp:write. csvno está disponible, porque necesita un esquema de salida explícito que no se puede inferir de unSELECTarbitrario.
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_TOOLSpara 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_idydelete_document_by_idno impide querun_sql_plus_plus_queryejecuteINSERT/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=trueoCB_MCP_WORKERSsuperior 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
| Transporte | Se usa para | Endpoint |
|---|---|---|
stdio (predeterminado) | Un cliente local que inicia el servidor como subproceso | — |
http | Varios clientes que comparten un servidor; admite OAuth, comprobaciones de estado y trabajadores en el servidor operativo | http://<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
httpy 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=truecon 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 carga | Configuración del servidor | Herramientas que requieren confirmación |
|---|---|---|
Sesiones persistentes, enrutadas según el encabezado de solicitud Mcp-Session-Id | Un trabajador, con estado (predeterminado) | Admitidas |
| Sin sesiones persistentes | --stateless-http=true | No 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_handleen la memoria de la instancia que inició la consulta, también en modo sin estado. Consultar, descartar o cancelar la consulta en otra instancia devuelveUnknown 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íaMcp-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_ISSUERyCB_MCP_OAUTH_JWT_AUDIENCE; si solo se configuran algunos, el inicio falla. CB_MCP_OAUTH_MCP_BASE_URLtambié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/scpdel token:couchbase-mcp:read(herramientas de lectura) ycouchbase-mcp:write(herramientas de escritura). El acceso completo requiere ambos. Cámbielos conCB_MCP_OAUTH_SCOPE_READ_LABEL/CB_MCP_OAUTH_SCOPE_WRITE_LABELsi 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) odebug.CB_MCP_LOG_SINKS—stderr,fileo ambos. Confile, se escribe un archivo rotativo por nivel junto aCB_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) yCB_MCP_LOG_RETENTION_BACKUP_COUNT(1 de forma predeterminada) se aplican a todos los niveles; se pueden anular por nivel conCB_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_BYTESestá 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 enmcp_server_config.log.jsonen 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_userides quien realiza la llamada:oauth(el sujeto del token),local(el usuario del sistema operativo, en stdio) oanonymous(HTTP sin OAuth, que genera una advertencia al iniciar). - Correlación —
cidagrupa todos los registros de una solicitud y se envía comoclient_context_idde SQL++, por lo que se une exactamente conclientContextIdde 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).
queryysearchson 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 comodescriptor.jsonen el paquete. El servidor operativo usa el bloque0xF000(61440), Operational Insights usa0x10000(65536) y ambos comparten0xE000(57344) para los eventos principales. - Filtrado —
CB_MCP_AUDIT_LOG_DISABLED_EVENTSsuprime 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 únicoquery(61507, o 65603 en Operational Insights) ysearch(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,1dde forma predeterminada), lo que ocurra primero;0desactiva 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 paratail -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 archivosaudit.*.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_statusinforma dewritten/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
- 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
- macOS:
- Añade el servidor en
mcpServersy reinicia Claude Desktop.
Registros: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. Consulta la guía de solución de problemas de MCP.
Cursor
- 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.
- Añade la configuración en
mcpServersy guárdala. - Actualiza la lista de servidores MCP para comprobar que
couchbaseesté habilitado.
Registros: en el panel inferior, abre Output y selecciona Cursor MCP.
Windsurf Editor
- 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).
- Haz clic en Add Server > Add custom server, pega la configuración y guárdala.
- Actualiza la lista de servidores para comprobar que
couchbaseesté 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
- Instala el complemento AI Assistant o Junie.
- Ve a Settings > Tools > AI Assistant (or Junie) > MCP Server, haz clic en +, añade la configuración y haz clic en Apply.
- 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.internalcomo cadena de conexión (consulta Redes de Docker). Usa--network=<your_network>para unirte a la red de otro contenedor. - Añade
operational-insightsen lugar deoperationalpara ejecutar el servidor Operational Insights (puerto8001).
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 encommand. - Si ejecutas desde el código fuente, comprueba la ruta del repositorio en la configuración y ejecuta
uv syncdespués de descargar las actualizaciones. - Llama a
get_server_configuration_statuspara 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!