Couchbase

officiel

Interagissez avec les données stockées dans les clusters Couchbase en utilisant le langage naturel.

Que pouvez-vous faire avec Couchbase MCP ?

  • Explorer les données du cluster — Lister les buckets, les scopes et les collections, puis déduire le schéma d’une collection comme orders.
  • Exécuter des requêtes SQL++ — Exécuter des requêtes SQL++ en lecture seule sur un bucket et un scope, et expliquer les plans de requête.
  • Inspecter des documents — Récupérer un document par son ID ou lire des chemins de sous-documents spécifiques sans charger le document entier.
  • Vérifier l’état du cluster — Indiquer l’état du cluster, les services en cours d’exécution et les diagnostics de connexion.
  • Analyser les performances des requêtes — Trouver les requêtes les plus longues, les plus fréquentes ou qui ne sont pas couvertes par un index.
  • Recherche et requêtes vectorielles — Exécuter des recherches en texte intégral et des requêtes de similarité vectorielle sur les index configurés.

Documentation

Serveur MCP Couchbase

Le serveur MCP Couchbase est un serveur MCP auto-hébergé qui permet aux agents d’IA de se connecter aux données des serveurs Couchbase (hébergés sur Capella ou autogérés) ou d’interagir avec elles, ainsi qu’à Operational Insights Enterprise. Il fournit des outils dans plusieurs catégories, notamment l’état du cluster, le schéma des données, les requêtes et bien d’autres, avec des contrôles de sécurité grâce au mode lecture seule et à la désactivation précise des outils. Il prend en charge les transports STDIO et Streamable HTTP, ainsi que les fonctionnalités OAuth.

Le serveur MCP Couchbase est distribué sous forme de package Python Package Index (PyPI) et via Docker. L’assistance Enterprise pour le serveur MCP Couchbase est disponible sous licence Couchbase AI Data Plane, qui donne également droit à l’utilisation et à l’assistance Enterprise de Couchbase Agent Memory et Couchbase Agent Catalog.

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

Documentation complète : docs.couchbase.com/mcp-server

Couchbase Server MCP server

Table des matières

Pourquoi choisir le serveur MCP Couchbase

  • Sécurisé par défaut — les outils d’écriture ne sont pas chargés et les requêtes qui modifient les données sont bloquées, sauf si vous définissez CB_MCP_READ_ONLY_MODE=false ; les outils peuvent également être désactivés individuellement ou soumis à la confirmation de l’utilisateur.
  • Couchbase Server et Operational Insights — le serveur opérationnel se connecte à Couchbase Capella ou à un cluster Couchbase Server autogéré avec la même configuration ; le serveur Operational Insights se connecte aux clusters Operational Insights autogérés.
  • Compatible avec le RBAC — les contrôles des outils guident le LLM ; le contrôle d’accès basé sur les rôles de l’utilisateur Couchbase reste la limite de sécurité faisant autorité.
  • Transports prêts pour la production — STDIO pour les clients de bureau locaux, ou Streamable HTTP avec OAuth 2.1 facultatif (tout fournisseur d’identité publiant des JWKS : Auth0, Okta, Keycloak, Entra, Cognito, …), des vérifications d’état et la journalisation d’audit pour les déploiements partagés. Le serveur opérationnel peut également exécuter plusieurs workers afin d’utiliser davantage de cœurs de processeur.
  • Compatible avec tout client MCP — testé avec Claude Desktop, Cursor, Windsurf, VS Code et JetBrains AI Assistant/Junie.

Une fois connecté, vous pouvez poser des questions telles que :

  • « Quels buckets, scopes et collections ai-je, et quel est le schéma de la collection orders ? »
  • « Trouve les 10 documents les plus récents dans users où status = 'active'. »
  • « Quelles sont les 5 requêtes les plus lentes de la dernière heure, et certaines n’ont-elles pas d’index couvrant ? »
  • « Ce cluster est-il sain, et quels services sont en cours d’exécution ? »
  • « Insère un nouveau document dans products avec ces champs : … » (nécessite CB_MCP_READ_ONLY_MODE=false)

Choisir un serveur

Ce package fournit deux serveurs MCP. Chacun est lancé par sa propre sous-commande, se connecte à un type de cluster différent et dispose de ses propres outils. Choisissez celui qui correspond à votre cluster, suivez la section correspondante pour la configuration et les outils, puis consultez Configuration commune pour les paramètres partagés. Pour utiliser les deux, enregistrez-les comme serveurs distincts dans votre client MCP.

Serveur opérationnelServeur Operational Insights
À utiliser avecUn cluster Couchbase (Capella ou autogéré)Un cluster Operational Insights autogéré (non disponible sur Capella)
Sous-commandeoperational (par défaut)operational-insights
Chaîne de connexioncouchbase:// / couchbases://URL HTTP(S), p. ex. http://localhost:8095
Variables d’identifiantsCB_CONNECTION_STRING, CB_USERNAME, …CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, …
Outils52 — état du cluster, schéma, KV, SQL++, index, recherche en texte intégral et vectorielle, performances des requêtes13 — schéma, SQL++ (synchrone et asynchrone), index, exportations
Port HTTP par défaut80008001
Fichier journal par défautmcp_server.logmcp_server_operational_insights.log

La sous-commande est actuellement facultative pour le serveur opérationnel — un simple couchbase-mcp-server le lance — mais la préciser rend votre configuration plus claire. Les options se placent après la sous-commande : couchbase-mcp-server operational --transport=http. Vérifiez la version installée avec uvx couchbase-mcp-server --version.

Serveur opérationnel

Le serveur operational se connecte à un cluster Couchbase sur Capella ou à un Couchbase Server autogéré, à l’aide du SDK Python couchbase.

Démarrage rapide du serveur opérationnel

Vous avez besoin d’un cluster Couchbase en cours d’exécution — le niveau gratuit de Capella est le moyen le plus rapide d’en obtenir un (vous pouvez importer un jeu de données d’exemple) — et d’un client MCP. Ajoutez une de ces configurations à votre client (consultez Configuration du client pour savoir où chaque client stocke sa configuration). Si le client dispose déjà d’autres serveurs, ajoutez couchbase à l’objet mcpServers existant.

Depuis PyPI avec uvx (nécessite uv et Python 3.11+) :

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

Avec Docker (Docker est le seul prérequis) :

{
  "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"
      ]
    }
  }
}
Depuis les sources
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/ correspond au chemin de votre clone — conservez la barre oblique finale. Après avoir récupéré les mises à jour, exécutez uv sync pour mettre à jour les dépendances.

Connexion et authentification du serveur opérationnel

Utilisez soit un nom d’utilisateur et un mot de passe, soit un certificat client (mTLS). Si les deux sont définis, le certificat est utilisé.

Variable d’environnementArgument CLIDescription
CB_CONNECTION_STRING--connection-stringChaîne de connexion au cluster. Obligatoire
CB_USERNAME / CB_PASSWORD--username / --passwordAuthentification de base
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH--client-cert-path / --client-key-pathAuthentification mTLS
CB_CA_CERT_PATH--ca-cert-pathCertificat racine pour un certificat de serveur auto-signé ou non approuvé (inutile pour Capella)
Exemple 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"
      }
    }
  }
}

Outils du serveur opérationnel

Les outils d’écriture (marqués ✏️) ne sont pas chargés lorsque le mode lecture seule est activé, ce qui est le comportement par défaut. Les outils marqués 🖥️ sont réservés aux déploiements autogérés — ils utilisent des points de terminaison REST d’administration que Capella n’expose pas, ou (discover_tool_input_values) ne fournissent que des données de référence pour un outil qui les utilise — et nécessitent donc Couchbase Server 7.6+ autogéré ; ils ne sont pas enregistrés pour les connexions Capella.

Configuration et état du cluster

OutilDescription
get_server_configuration_statusÉtat et configuration du serveur sans connexion au cluster : mode lecture seule, outils désactivés ou soumis à confirmation, OAuth, journalisation et compteurs d’audit
test_cluster_connectionVérifier les identifiants du cluster en s’y connectant
get_cluster_health_and_servicesÉtat du cluster et services en cours d’exécution, avec filtrage facultatif via service_types
get_client_connectivity_reportDiagnostics de connexion mis en cache par le SDK, sans sondage réseau actif
get_cluster_metrics 🖥️Statistiques du cluster sur une période historique (point de terminaison stats-range)
get_cluster_tasks 🖥️Tâches en cours — rééquilibrage, compactage, XDCR, création d’index. Nécessite ro_admin
get_cluster_health_snapshot 🖥️État de santé par nœud : topologie des services, appartenance au cluster, orchestrateur et synthèse de l’état de santé. Nécessite ro_admin
get_bucket_config 🖥️Configuration et état en temps réel d’un bucket (ou de tous les buckets) — quotas, éviction, réplicas, durabilité, stockage, compactage. Nécessite ro_admin
get_cluster_system_events 🖥️Journal des événements système (modifications de configuration, basculements, rééquilibrages, redémarrages), limité à une période avec since_time. Nécessite Full Admin ou Cluster Admin
discover_tool_input_values 🖥️Rechercher les valeurs d’entrée exactes requises par d’autres outils (p. ex. chaque nom de métrique pour get_cluster_metrics). Fonctionne hors ligne

Découverte du modèle de données et du schéma

OutilDescription
get_buckets_in_clusterRépertorier tous les buckets du cluster
get_scopes_in_bucketRépertorier tous les scopes d’un bucket
get_collections_in_scopeRépertorier toutes les collections d’un scope (nécessite le service Query)
get_scopes_and_collections_in_bucketRépertorier tous les scopes et collections d’un bucket
get_schema_for_collectionDéduire la structure d’une collection
create_scope ✏️Créer un scope dans un bucket (Server 7.6+ et Capella)
create_collection ✏️Créer une collection dans un scope existant (Server 7.6+ et Capella)
delete_scope ✏️Supprimer un scope et toutes ses collections — opération définitive
delete_collection ✏️Supprimer une collection et tous ses documents — opération définitive

Opérations sur les documents (KV)

OutilDescription
get_document_by_idRécupérer un document par son ID
lookup_subdocumentLire des chemins spécifiques, vérifier l’existence ou compter des éléments sans récupérer le document entier
upsert_document_by_id ✏️Insérer ou remplacer un document par son ID
insert_document_by_id ✏️Insérer un nouveau document (échoue s’il existe déjà)
replace_document_by_id ✏️Remplacer un document existant (échoue s’il n’existe pas)
delete_document_by_id ✏️Supprimer un document par son ID
mutate_subdocument ✏️Modifier des chemins dans un document existant (upsert, insertion, remplacement, suppression, opérations sur les tableaux, compteurs)

Requêtes et indexation

OutilDescription
run_sql_plus_plus_queryExécuter une requête SQL++ limitée à un bucket et à un scope — utiliser directement les noms de collections (SELECT * FROM users). Les instructions qui modifient les données sont bloquées en mode lecture seule
explain_sql_plus_plus_queryGénérer et évaluer un plan EXPLAIN : métadonnées, plan extrait et résultats
get_index_advisor_recommendationsRecommandations d’Index Advisor pour une requête SQL++
list_indexesRépertorier les index avec leurs définitions, filtrables par bucket/scope/collection/nom ; signale les index vectoriels (is_vector, vector_type)
get_index_stats 🖥️Taille, fragmentation, trafic de balayage et latence de chaque index, par nœud — repère les problèmes de pression et les index inutilisés
create_query_index ✏️Créer un index GSI scalaire, vectoriel Hyperscale ou vectoriel composite (index_type). Différé par défaut — poursuivre avec build_index
create_index ✏️Obsolète — utiliser create_query_index. Supprimé dans la version 2.0
build_index ✏️Créer tous les index différés d’une collection
drop_index ✏️Supprimer un index GSI (scalaire ou vectoriel)

Recherche en texte intégral (FTS)

Nécessite Couchbase Server 7.6+ et le service Search. Les index au niveau du scope et du cluster (anciens) sont tous deux pris en charge : transmettez bucket_name et scope_name ensemble pour un index au niveau du scope, ou omettez les deux.

OutilDescription
list_search_indexesLister les index Search — au niveau du cluster, par bucket ou par scope
get_search_index_definitionDéfinition complète d’un index Search (mappings, analyseurs, paramètres du plan)
run_searchExécuter n’importe quelle requête FTS non vectorielle à partir de son corps JSON brut ; explain=true renvoie le plan d’exécution
upsert_search_index ✏️Créer ou mettre à jour un index Search, y compris les mappings de champs vectoriels. Les mises à jour déclenchent une reconstruction complète — transmettez le uuid actuel pour éviter d’écraser des modifications concurrentes
drop_search_index ✏️Supprimer un index Search — définitivement

Recherche vectorielle

Les deux outils vectorisent le texte brut de la requête avec le modèle configuré dans Fournisseurs d’embeddings. Disponible sur Couchbase Server autogéré et Capella.

OutilDescription
run_vector_queryRecherche par similarité dans un index vectoriel GSI (Server 8.0+) via APPROX_VECTOR_DISTANCE(). L’index est sélectionné automatiquement ; prend en charge un préfiltre SQL++ where et le réglage Hyperscale (num_probes, rerank, top_n_scan). Renvoie les documents complets
run_vector_searchRecherche vectorielle du service Search (Server 7.6+) dans un index nommé. scalar_query la rend hybride ; prefilter réduit d’abord le nombre de candidats. Renvoie les champs stockés dans l’index pour chaque résultat

Analyse des performances des requêtes

OutilDescription
get_longest_running_queriesRequêtes les plus longues selon le temps de service moyen
get_most_frequent_queriesRequêtes exécutées le plus fréquemment
get_queries_with_largest_response_sizesRequêtes avec les réponses les plus volumineuses
get_queries_with_large_result_countRequêtes avec le plus grand nombre de résultats
get_queries_using_primary_indexRequêtes utilisant un index primaire
get_queries_not_using_covering_indexRequêtes n’utilisant pas d’index couvrant
get_queries_not_selectiveRequêtes dont les scans — index secondaire, index primaire ou séquentiel — renvoient bien plus de documents que le résultat final

État du service Query 🖥️

Ces outils appellent l’API REST d’administration du service Query sur chaque nœud Query.

OutilDescription
get_cluster_query_vitalsÉtat du moteur Query : taux de requêtes, requêtes actives/en attente, mémoire, GC, durée de fonctionnement. Nécessite ro_admin
get_active_queriesRequêtes en cours d’exécution sur tous les nœuds Query. Nécessite ro_admin
delete_active_query ✏️Annuler une requête en cours à l’aide de son ID de requête. Nécessite Full Admin ou Cluster Admin

Outils désactivés automatiquement sur Capella

Les outils 🖥️ accèdent à Couchbase via des points de terminaison REST d’administration que Capella n’expose pas (à l’exception de discover_tool_input_values, qui est exclu car il ne sert qu’un outil qui en a besoin). Lorsque tous les hôtes de CB_CONNECTION_STRING se terminent par .cloud.couchbase.com, le serveur ne les enregistre pas et les signale avec vos propres outils désactivés dans get_server_configuration_status et dans le journal de démarrage. Les outils basés sur le SDK, tels que get_cluster_health_and_services et get_client_connectivity_report, restent disponibles.

OutilPoint de terminaison requis
get_cluster_metricsREST de gestion (/pools/default/stats/range)
get_cluster_tasksREST de gestion (/pools/default/tasks)
get_bucket_configREST de gestion (/pools/default/buckets[/<name>])
get_cluster_health_snapshotREST de gestion, ainsi que des points de terminaison par nœud
get_cluster_system_eventsREST de gestion (/events)
get_index_statsREST du service Index (le /api/v1/stats de chaque indexeur)
get_cluster_query_vitalsREST du service Query (/admin/vitals)
get_active_queriesREST du service Query (/admin/active_requests)
delete_active_queryREST du service Query (DELETE /admin/active_requests/{id})
discover_tool_input_valuesAucun (fonctionne hors ligne), mais ne sert que get_cluster_metrics, absent de Capella

Fournisseurs d’embeddings

run_vector_query et run_vector_search vectorisent le texte de la requête avec le fournisseur défini dans CB_MCP_EMBEDDING_MODEL_PROVIDER. Cette configuration est facultative : sans elle, le serveur démarre normalement et les deux outils restent enregistrés, mais leur appel renvoie une erreur indiquant quoi configurer.

CB_MCP_EMBEDDING_MODEL_PROVIDERObligatoireFacultatifRemarques
capellaCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL, CB_MCP_EMBEDDING_MODEL_ENDPOINT—Capella Model Service. CB_MCP_EMBEDDING_MODEL_ENDPOINT est l’URL propre à votre déploiement (par ex. https://<id>.ai.couchbase.com) dans AI Data Plane > Models de Capella
openaiCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINTDéfinissez le point de terminaison pour utiliser un serveur local compatible avec 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_REGIONModèles d’embeddings Amazon Titan (par ex. amazon.titan-embed-text-v2:0) — le fournisseur envoie le format de requête inputText de Titan ; les autres modèles d’embeddings Bedrock, tels que Cohere Embed, ne sont donc pas encore pris en charge. Omettez les identifiants pour utiliser la chaîne AWS par défaut. Nécessite l’élément supplémentaire : 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-..."
}

Toutes les options

Toutes les variables d’environnement et options CLI du serveur opérationnel serveur

Le serveur Operational Insights accepte les mêmes options, à l’exception de ses propres paramètres de connexion et de l’absence d’options CB_MCP_EMBEDDING_MODEL_*.

Variable d’environnementArgument CLIDescriptionValeur par défaut
CB_CONNECTION_STRING--connection-stringChaîne de connexion au cluster CouchbaseObligatoire
CB_USERNAME--usernameNom d’utilisateur ayant accès aux buckets requis pour l’authentification de baseObligatoire (ou certificat client et clé requis pour mTLS)
CB_PASSWORD--passwordMot de passe pour l’authentification de baseObligatoire (ou certificat client et clé requis pour mTLS)
CB_CLIENT_CERT_PATH--client-cert-pathChemin vers le fichier de certificat client pour l’authentification mTLSObligatoire si mTLS est utilisé (ou nom d’utilisateur et mot de passe requis)
CB_CLIENT_KEY_PATH--client-key-pathChemin vers le fichier de clé client pour l’authentification mTLSObligatoire si mTLS est utilisé (ou nom d’utilisateur et mot de passe requis)
CB_CA_CERT_PATH--ca-cert-pathChemin vers le certificat racine du serveur pour TLS si le serveur est configuré avec un certificat auto-signé/non approuvé. Ce paramètre n’est pas nécessaire si vous vous connectez à Capella
CB_MCP_READ_ONLY_MODE--read-only-modeEmpêcher toute modification des données (KV, Query, gestion des scopes/collections, gestion des index et gestion des index FTS). Lorsque cette option est activée, les outils d’écriture ne sont pas chargés.true
CB_MCP_TRANSPORT--transportMode de transport : stdio, httpstdio
CB_MCP_HOST--hostHôte pour le mode de transport HTTP127.0.0.1
CB_MCP_PORT--portPort pour le mode de transport HTTP8000
CB_MCP_WORKERS--workersNombre de processus de travail du serveur pour le transport http. Les valeurs supérieures à 1 exécutent le mode HTTP sans état (voir Plusieurs processus de travail)1
CB_MCP_STATELESS_HTTP--stateless-httpTraiter chaque requête HTTP sans état par session. Pris en compte uniquement avec http ; ne peut pas être combiné avec des outils nécessitant une confirmation (voir Plusieurs processus de travail)true lorsque le nombre de processus de travail est > 1, sinon false
CB_MCP_DISABLED_TOOLS--disabled-toolsOutils à désactiver (voir Désactivation des outils)Aucun
CB_MCP_CONFIRMATION_REQUIRED_TOOLS--confirmation-required-toolsOutils nécessitant une confirmation explicite de l’utilisateur avant leur exécution via l’élicitation MCP (voir Exiger une confirmation)Aucun
CB_MCP_LOG_LEVEL--log-levelNiveau de journalisation du serveur MCP : off, debug, info, warning, error (voir Journalisation)info
CB_MCP_LOG_SINKS--log-sinksDestinations des journaux, séparées par des virgules : stderr, file, ou les deux (voir Journalisation)stderr
CB_MCP_LOG_FILE--log-fileChemin de base des fichiers journaux par niveau (utilisé uniquement lorsque le sink file est activé)mcp_server.log
CB_MCP_LOG_ROTATION_MAX_SIZE_MB--log-rotation-max-size-mbTaille maximale globale en Mo de chaque fichier journal avant sa rotation, héritée par chaque niveau sauf remplacement. 0 — ou une valeur inutilisable, telle qu’une valeur négative, nan ou inf — n’est pas valide et entraîne l’utilisation de la valeur par défaut avec un avertissement au démarrage1 (1 Mo)
CB_MCP_LOG_MAX_BYTES--log-max-bytesObsolète — utilisez CB_MCP_LOG_ROTATION_MAX_SIZE_MB (Mo). Taille globale de rotation en octets, toujours prise en charge pour assurer la rétrocompatibilité ; ignorée si CB_MCP_LOG_ROTATION_MAX_SIZE_MB est également définiNon défini
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB--log-error-rotation-max-size-mbTaille de rotation en Mo du fichier journal ERROR ; remplace CB_MCP_LOG_ROTATION_MAX_SIZE_MB pour ERRORHérite de CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB--log-warning-rotation-max-size-mbTaille de rotation en Mo du fichier journal WARNING ; remplace CB_MCP_LOG_ROTATION_MAX_SIZE_MB pour WARNINGHérite de CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB--log-info-rotation-max-size-mbTaille de rotation en Mo du fichier journal INFO ; remplace CB_MCP_LOG_ROTATION_MAX_SIZE_MB pour INFOHérite de CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB--log-debug-rotation-max-size-mbTaille de rotation en Mo du fichier journal DEBUG ; remplace CB_MCP_LOG_ROTATION_MAX_SIZE_MB pour DEBUGHérite de CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_RETENTION_BACKUP_COUNT--log-retention-backup-countNombre de fichiers de sauvegarde après rotation conservés par fichier journal et par niveau (à l’exclusion du fichier actif), appliqué à tous les niveaux sauf remplacement. 0 ne conserve que le fichier actif (voir Journalisation)1
CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT--log-error-retention-backup-countNombre de fichiers de sauvegarde après rotation conservés pour le fichier journal ERROR ; remplace le nombre global pour ERRORHérite de CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT--log-warning-retention-backup-countNombre de fichiers de sauvegarde après rotation conservés pour le fichier journal WARNING ; remplace le nombre global pour WARNINGHérite de CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT--log-info-retention-backup-countNombre de fichiers de sauvegarde après rotation conservés pour le fichier journal INFO ; remplace le nombre global pour INFOHérite de CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT--log-debug-retention-backup-countNombre de fichiers de sauvegarde après rotation conservés pour le fichier journal DEBUG ; remplace le nombre global pour DEBUGHérite de CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_OAUTH_JWT_JWKS_URI--oauth-jwks-uriPoint de terminaison JWKS du fournisseur d’identité utilisé pour vérifier les JWT porteurs. Active OAuth lorsqu’il est défini avec l’émetteur et l’audience (voir Autorisation OAuth 2.1)Aucun
CB_MCP_OAUTH_JWT_ISSUER--oauth-issuerClaim JWT iss attendu. Obligatoire pour activer OAuthAucun
CB_MCP_OAUTH_JWT_AUDIENCE--oauth-audienceClaim JWT aud attendu. Obligatoire pour activer OAuthAucun
CB_MCP_OAUTH_JWT_ALGORITHM--oauth-algorithmAlgorithme de signature JWT : l’un de RS256/384/512, ES256/384/512, PS256/384/512RS256
CB_MCP_OAUTH_MCP_BASE_URL--oauth-mcp-base-urlURL de base publique de ce serveur. Lorsqu’elle est définie, publie les métadonnées de ressource protégée RFC 9728 afin que les clients compatibles PRM puissent découvrir le fournisseur d’identitéAucun
CB_MCP_OAUTH_SCOPE_READ_LABEL--oauth-scope-read-labelRemplacer le libellé de scope OAuth considéré comme un accès « lecture » (annoncé dans PRM et comparé au claim scope/scp du jeton). À utiliser si votre fournisseur d’identité ne peut pas émettre la forme canoniquecouchbase-mcp:read
CB_MCP_OAUTH_SCOPE_WRITE_LABEL--oauth-scope-write-labelRemplacer le libellé de scope OAuth considéré comme un accès « écriture » ; même sémantique que pour le libellé de lecturecouchbase-mcp:write
CB_MCP_AUDIT_LOG_ENABLED--audit-log-enabledActiver la journalisation d’audit — un sink distinct des journaux opérationnels CB_MCP_LOG_*, avec un schéma stable et sa propre durée de conservation (voir Audit)false
CB_MCP_AUDIT_LOG_SINKS--audit-log-sinksDestinations d’audit, séparées par des virgules : console, file, ou les deux. console écrit sur stderr — jamais sur stdout, qui transporte le protocole JSON-RPC en mode stdioconsole
CB_MCP_AUDIT_LOG_FILE_PATH--audit-log-file-pathChemin du fichier journal d’audit. Obligatoire lorsque file figure parmi les sinks ; le nom d’hôte et l’identifiant du processus sont insérés avant l’extension (audit.log → audit.<host>.<pid>.log)Aucun
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB--audit-log-rotation-max-size-mbTaille maximale en Mo que le fichier d’audit actif peut atteindre avant sa rotation. 0 désactive la rotation basée sur la taille10 (10 Mo)
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL--audit-log-rotation-intervalÂge maximal du fichier d’audit actif avant sa rotation, au format <value><unit>, où l’unité est d (24 heures) ou w (7 jours) — par exemple 1d, 30d, 8w. 0 désactive la rotation basée sur un intervalle1d
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS--audit-log-retention-max-backupsNombre de sauvegardes après rotation conservées par fichier d’audit, à l’exclusion du fichier actif. Les sauvegardes sont compressées au format gzip. 0 n’en conserve aucune. Cela limite la taille d’un fichier, pas celle du répertoire — voir Audit10
CB_MCP_AUDIT_LOG_TOOL_ARGS--audit-log-tool-argsEnregistrer les valeurs des arguments des outils dans le journal d’audit. Désactivé par défaut — cette version n’effectue aucune rédaction ; l’activation écrit donc les arguments tels quels, y compris le contenu intégral des documentsfalse
CB_MCP_AUDIT_LOG_DISABLED_EVENTS--audit-log-disabled-eventsÉvénements d’audit à supprimer : identifiants d’événement numériques séparés par des virgules (par ex. 61490,61492), ou fichier contenant un identifiant par ligne. Seuls les événements filtrables peuvent être supprimésAucun
CB_MCP_EMBEDDING_MODEL_PROVIDER--embedding-model-providerFournisseur d’embeddings pour run_vector_query / run_vector_search : l’un de capella, openai, cohere, voyage, bedrock. Si ce paramètre n’est pas défini, l’étape d’embedding des deux outils est désactivée jusqu’à sa configuration — voir Configuration du fournisseur d’embeddingsAucun
CB_MCP_EMBEDDING_MODEL--embedding-modelNom/ID du modèle pour le fournisseur d’embeddings configuréAucun
CB_MCP_EMBEDDING_MODEL_API_KEY--embedding-model-api-keyClé API du fournisseur configuré. Non utilisée par bedrock (qui utilise la chaîne d’identifiants AWS / CB_MCP_EMBEDDING_MODEL_AWS_*)Aucun
CB_MCP_EMBEDDING_MODEL_ENDPOINT--embedding-model-endpointRemplacement de l’URL de base (serveur local compatible avec OpenAI, ou URL propre à un déploiement Capella Model Service — obligatoire lorsque CB_MCP_EMBEDDING_MODEL_PROVIDER=capella)Aucun
CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID--embedding-model-aws-access-key-idID de clé d’accès AWS, fournisseur bedrock uniquement. Omettre pour utiliser la chaîne d’identifiants AWS par défautAucun
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY--embedding-model-aws-secret-access-keyClé d’accès secrète AWS, fournisseur bedrock uniquementAucun
CB_MCP_EMBEDDING_MODEL_AWS_REGION--embedding-model-aws-regionRégion AWS, fournisseur bedrock uniquement. Si elle n’est pas définie, la résolution de région propre au SDK AWS est utiliséeAucun

Serveur Operational Insights

Le serveur operational-insights se connecte aux clusters Operational Insights autogérés. Operational Insights est une base de données analytique en temps réel (RT-OLAP) destinée aux applications en temps réel et à l’intelligence opérationnelle. Le serveur n’est pas disponible pour Capella. Il utilise le SDK couchbase-operational-insights. Il s’exécute dans son propre processus, séparément du serveur opérationnel.

[!IMPORTANT] CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING est une URL HTTP(S), et non une chaîne de connexion couchbase:// — par exemple http://localhost:8095, ou https://<host>:18095 avec TLS. C’est l’erreur de configuration la plus fréquente.

Démarrage rapide d’Operational Insights

Depuis PyPI avec 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"
      }
    }
  }
}

Avec 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"
      ]
    }
  }
}

Depuis les sources, utilisez la configuration des sources opérationnelles avec operational-insights comme dernier argument et les variables ci-dessus.

Connexion et authentification à Operational Insights

Variable d’environnementArgument CLIDescription
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING--connection-stringURL du point de terminaison (HTTP/HTTPS). Obligatoire
CB_OPERATIONAL_INSIGHTS_USERNAME--usernameNom d’utilisateur
CB_OPERATIONAL_INSIGHTS_PASSWORD--passwordMot de passe
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH--ca-cert-pathCertificat racine (PEM) pour un certificat de serveur auto-signé/non approuvé
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH--client-cert-pathCertificat client pour mTLS — PEM (avec une clé) ou bundle PKCS#12 (.p12/.pfx, sans clé). Nécessite une URL https:// ; remplace le nom d’utilisateur et le mot de passe
CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH--client-key-pathClé privée (PEM) du certificat client. Laisser non défini pour PKCS#12
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD--client-cert-passwordMot de passe d’une clé chiffrée ou d’un bundle PKCS#12
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE--operational-insights-query-result-max-sizeTaille maximale des résultats de requête en octets. Si non définie, aucune limite. Lorsqu’elle est définie, la lecture s’arrête à la limite et la réponse indique truncated: true ; une ligne qui dépasserait cette limite n’est pas renvoyée. Les valeurs supérieures à 4 MiB (4194304) sont ramenées à 4 MiB, avec un avertissement sur stderr au démarrage
CB_MCP_OPERATIONAL_INSIGHTS_ASYNC_QUERY_RESULT_TIMEOUT--operational-insights-async-query-result-timeoutDélai d’expiration en secondes pour chaque requête asynchrone : démarrage de la requête, vérification de son état, récupération des résultats, suppression et annulation. Pour une récupération, il couvre l’intégralité du téléchargement ; un résultat dont la lecture prend plus longtemps échoue. Augmentez-le pour les résultats volumineux ou les connexions lentes. Entier positif, valeur par défaut 30, maximum 600. Les valeurs supérieures sont ramenées à 600 avec un avertissement ; toute autre valeur non valide est consignée comme avertissement et 30 est utilisée

Toute la configuration commune s’applique, avec les différences suivantes par rapport au serveur opérationnel :

  • Le port par défaut est 8001 et le fichier journal par défaut est mcp_server_operational_insights.log, ce qui permet aux deux serveurs de fonctionner côte à côte.
  • Un seul worker est pris en charge (CB_MCP_WORKERS=1), car les handles de requête asynchrone résident dans la mémoire du processus.
  • Il ne propose aucune option CB_MCP_EMBEDDING_MODEL_*.

Outils Operational Insights

Tous les noms, à l’exception de get_server_configuration_status, sont préfixés par operational_insights_, afin que les deux serveurs puissent être enregistrés dans un même client sans collision. L’outil d’écriture (marqué ✏️) n’est pas chargé lorsque le mode lecture seule, activé par défaut, est en vigueur.

État du serveur

OutilDescription
get_server_configuration_statusMême outil que sur le serveur opérationnel

Découverte du modèle de données et du schéma

OutilDescription
operational_insights_get_databases_in_clusterRépertorier les bases de données
operational_insights_get_scopes_in_databaseRépertorier les scopes d’une base de données
operational_insights_get_collections_in_scopeRépertorier les collections (ensembles de données) d’un scope
operational_insights_get_schema_for_collectionDéduire le schéma JSON d’une collection par échantillonnage

Requêtes et index

OutilDescription
operational_insights_list_indexesRépertorier les index secondaires de System.Metadata.Index
operational_insights_explain_queryExpliquer une instruction SQL++ sans l’exécuter
operational_insights_run_query_syncExécuter SQL++ et renvoyer les lignes, jusqu’à la limite de taille des résultats ; peut aussi exporter. Le mode lecture seule est appliqué côté serveur
operational_insights_run_query_asyncDémarrer une requête de longue durée et renvoyer un query_handle sans attendre les lignes ; également recommandé pour les exportations volumineuses. Le mode lecture seule est appliqué côté serveur
operational_insights_get_async_query_resultsInterroger une requête asynchrone ; renvoie les lignes (ou la destination d’exportation) lorsqu’elles sont prêtes
operational_insights_discard_async_query_resultsLibérer les résultats d’une requête asynchrone terminée
operational_insights_cancel_async_queryArrêter une requête asynchrone toujours en cours (autorisé en mode lecture seule)
operational_insights_create_index ✏️Créer un index secondaire via CREATE INDEX

Les requêtes asynchrones suivent un processus démarrer → interroger → supprimer ou annuler : operational_insights_run_query_async renvoie un query_handle, operational_insights_get_async_query_results est interrogé jusqu’à ce que la requête soit prête, puis operational_insights_discard_async_query_results libère les résultats, ou operational_insights_cancel_async_query arrête une requête toujours en cours.

Exportation de résultats volumineux

Au lieu de renvoyer des lignes, operational_insights_run_query_sync et operational_insights_run_query_async peuvent encapsuler l’instruction dans COPY ... TO et écrire les lignes dans un stockage d’objets externe. Fournissez les trois éléments suivants : copy_to_link (un lien existant créé avec CREATE LINK ... TYPE S3), copy_to_bucket et copy_to_path, ainsi que, facultativement, copy_to_format (json, la valeur par défaut, ou parquet). L’outil renvoie alors une confirmation sans lignes :

{
  "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. ..."
}
  • Une destination partielle est rejetée au lieu de renvoyer silencieusement les lignes.
  • L’outil synchrone attend la fin de l’envoi ; privilégiez l’outil asynchrone pour les exportations volumineuses.
  • Les exportations sont bloquées en mode lecture seule (elles écrivent dans un stockage externe) ; elles nécessitent donc CB_MCP_READ_ONLY_MODE=false ou un jeton avec couchbase-mcp:write.
  • csv n’est pas proposé, car il nécessite un schéma de sortie explicite qui ne peut pas être déduit d’un SELECT arbitraire.

Configuration commune

Ces paramètres fonctionnent de la même manière pour les deux serveurs. Chaque option peut être définie comme variable d’environnement ou comme indicateur CLI après la sous-commande.

Contrôles de sécurité

Suivez ces principes de sécurité :

  • Accordez à l’utilisateur de la base de données le minimum de privilèges — RBAC constitue la limite de sécurité faisant autorité (voir ci-dessous).
  • Ne fournissez à l’agent que les outils dont il a besoin et désactivez les autres — chaque outil chargé peut être appelé par le LLM. Utilisez le mode lecture seule et CB_MCP_DISABLED_TOOLS pour réduire la liste d’outils au minimum.
  • Exigez une confirmation pour les outils sensibles que vous conservez — voir Exiger une confirmation.

Les contrôles ci-dessous forment trois couches, de la plus générale à la plus ciblée. Utilisez-les ensemble, mais gardez à l’esprit qu’aucun ne remplace RBAC.

[!IMPORTANT] Les autorisations RBAC de l’utilisateur de la base de données constituent le contrôle de sécurité faisant autorité. Par exemple, désactiver upsert_document_by_id et delete_document_by_id n’empêche pas run_sql_plus_plus_query d’exécuter INSERT/UPDATE/DELETE/MERGE — seul le mode lecture seule ou l’absence des autorisations RBAC nécessaires le permet. N’accordez à l’utilisateur de base de données du serveur que les autorisations dont il a besoin.

Mode lecture seule

CB_MCP_READ_ONLY_MODE (valeur par défaut true) est l’interrupteur unique qui contrôle les écritures :

  • true — les outils d’écriture marqués ✏️ dans la liste des outils de chaque serveur ne sont pas chargés, et les requêtes qui modifient les données ou la structure sont bloquées.
  • false — les outils d’écriture sont chargés et les requêtes de modification sont autorisées.

Désactivation des outils

CB_MCP_DISABLED_TOOLS supprime entièrement des outils de la découverte. Il accepte une liste séparée par des virgules ou le chemin d’un fichier contenant un nom d’outil par ligne (# commence un commentaire) :

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

Sur Capella, le serveur opérationnel désactive également automatiquement certains outils d’administration.

Exiger une confirmation (sollicitation)

CB_MCP_CONFIRMATION_REQUIRED_TOOLS demande à l’utilisateur de confirmer avant l’exécution d’un outil répertorié, à l’aide de la sollicitation MCP. Il accepte les mêmes formats de liste séparée par des virgules ou de fichier que la désactivation des outils :

CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"
  • Si le client prend en charge la sollicitation, l’utilisateur est invité à confirmer avant l’exécution de l’outil.
  • Dans le cas contraire, l’outil s’exécute sans confirmation, pour assurer la rétrocompatibilité.
  • La confirmation nécessite une session MCP ; elle ne peut donc pas être combinée avec HTTP sans état (CB_MCP_STATELESS_HTTP=true ou CB_MCP_WORKERS supérieur à 1). Le serveur refuse de démarrer avec cette combinaison. Derrière un répartiteur de charge, la confirmation nécessite des sessions persistantes — voir Répartiteurs de charge.

Transports

TransportÀ utiliser pourPoint de terminaison
stdio (par défaut)Un client local qui lance le serveur en tant que sous-processus—
httpPlusieurs clients partageant un serveur ; prend en charge OAuth, les vérifications d’état et les workers sur le serveur opérationnelhttp://<host>:<port>/mcp

Définissez le transport avec CB_MCP_TRANSPORT, l’adresse d’écoute avec CB_MCP_HOST (par défaut 127.0.0.1) et le port avec CB_MCP_PORT (port par défaut de chaque serveur si non défini). Sans OAuth, le point de terminaison HTTP n’est pas authentifié.

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

Configurez ensuite votre client pour utiliser l’URL :

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

Plusieurs workers

Un processus utilise au maximum environ un cœur de processeur. --workers N (CB_MCP_WORKERS) exécute N processus derrière le même hôte et le même port ; le nombre de cœurs disponibles constitue un bon point de départ. Seul le serveur opérationnel prend en charge les workers. Avec plusieurs workers :

  • Le transport http est requis et le serveur fonctionne en mode HTTP sans état, car les requêtes d’un client peuvent être traitées par différents workers. Vous pouvez également définir --stateless-http=true avec un seul worker, par exemple derrière un répartiteur de charge sans sessions persistantes.
  • Les outils nécessitant une confirmation ne peuvent pas être utilisés.
  • Chaque processus écrit ses propres fichiers journaux, nommés avec l’hôte et l’identifiant du processus (mcp_server.<host>.<pid>.info.log) — un ensemble pour le superviseur et un par worker.

Répartiteurs de charge

Vous pouvez exécuter plusieurs instances du serveur derrière un répartiteur de charge. Chaque instance conserve ses sessions MCP dans sa propre mémoire ; le paramétrage du répartiteur de charge détermine donc les fonctionnalités disponibles :

Répartiteur de chargeParamètre du serveurOutils nécessitant une confirmation
Sessions persistantes, routées selon l’en-tête de requête Mcp-Session-IdUn worker, avec état (par défaut)Pris en charge
Aucune session persistante--stateless-http=trueNon pris en charge — le serveur refuse de démarrer si ces outils sont configurés
  • Sans sessions persistantes, une instance avec état rejette toute requête dont la session a été créée sur une autre instance. Dans ce cas, utilisez le mode sans état.
  • Effectuez le routage selon l’en-tête Mcp-Session-Id, et non selon les cookies. De nombreux clients MCP ne conservent pas les cookies.
  • Si une instance redémarre ou bascule vers une autre, ses sessions et les éventuelles demandes de confirmation en attente sont perdues. Le client doit démarrer une nouvelle session.
  • Les requêtes asynchrones Operational Insights conservent leur query_handle dans la mémoire de l’instance qui a démarré la requête, y compris en mode sans état. Interroger, supprimer ou annuler la requête sur une autre instance renvoie Unknown query_handle. Utilisez ces outils avec une seule instance ou avec des sessions persistantes afin que tous les appels atteignent l’instance qui a démarré la requête. Le mode sans état n’envoie aucun Mcp-Session-Id ; il nécessite donc une autre clé d’affinité, telle que l’adresse IP du client.

Vérification d’état

En mode HTTP, GET /health renvoie {"status": "ok", "server": "<server>"} sur le port MCP. Il s’agit d’une vérification de disponibilité : elle ne se connecte pas au cluster (une panne du cluster ne redémarre donc pas les conteneurs en bon état), ne nécessite aucune authentification même lorsque OAuth est activé et est prise en charge par chaque worker. Voir Docker pour des exemples de sondes.

Autorisation OAuth 2.1

Avec --transport=http, chaque serveur peut agir comme un serveur de ressources OAuth 2.1, en validant les JWT porteurs à l’aide du JWKS de votre fournisseur d’identité. Cette fonctionnalité fonctionne avec tout fournisseur OAuth 2.1/OIDC qui publie un JWKS et n’émet pas de jetons ni ne gère d’utilisateurs. Les paramètres OAuth sont ignorés avec stdio.

  • OAuth n’est activé que si les trois paramètres CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER et CB_MCP_OAUTH_JWT_AUDIENCE sont définis ; si certains seulement le sont, le démarrage échoue.
  • CB_MCP_OAUTH_MCP_BASE_URL publie également les métadonnées de ressource protégée RFC 9728 afin que les clients puissent découvrir le serveur d’autorisation.
  • L’accès est contrôlé par deux scopes dans la revendication scope/scp du jeton : couchbase-mcp:read (outils de lecture) et couchbase-mcp:write (outils d’écriture). L’accès complet nécessite les deux. Renommez-les avec CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL si votre fournisseur d’identité ne peut pas émettre ces libellés. Les deux serveurs utilisent les mêmes libellés ; une seule configuration du fournisseur d’identité suffit donc pour les deux.
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>'

Consultez la documentation OAuth du serveur opérationnel et du serveur Operational Insights pour configurer le fournisseur d’identité.

Journalisation

Par défaut, chaque serveur écrit ses journaux dans stderr au niveau info.

  • CB_MCP_LOG_LEVEL — off, error, warning, info (événements de cycle de vie et appels d’outils) ou debug.
  • CB_MCP_LOG_SINKS — stderr, file, ou les deux. Avec file, un fichier rotatif par niveau est écrit à côté de CB_MCP_LOG_FILE (mcp_server.info.log, mcp_server.error.log, …).
  • Rotation et conservation — CB_MCP_LOG_ROTATION_MAX_SIZE_MB (1 Mo par défaut) et CB_MCP_LOG_RETENTION_BACKUP_COUNT (1 par défaut) s’appliquent à chaque niveau ; remplacez-les par niveau avec CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB / CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT. Les tailles non valides reprennent la valeur par défaut avec un avertissement au démarrage. CB_MCP_LOG_MAX_BYTES est obsolète.
  • Instantané de configuration — avec le récepteur file, un enregistrement JSON de l’environnement et de la configuration du serveur expurgée est écrit dans mcp_server_config.log.json à chaque démarrage, à des fins d’assistance.
# Debug logging to stderr and rotating per-level files
uvx couchbase-mcp-server operational --log-level=debug --log-sinks=stderr,file

Votre client MCP capture généralement aussi stderr du serveur — voir Configuration du client pour savoir où. Détails : documentation sur la journalisation du serveur opérationnel et du serveur Operational Insights.

Audit

La journalisation d’audit consigne qui a fait quoi et si cela a été autorisé — séparément des journaux opérationnels, qui consignent ce qui a mal tourné. Le serveur MCP est la seule couche capable de répondre à cette question pour un agent : chaque requête atteint le cluster sous la forme d’un seul utilisateur de base de données, et les décisions telles qu’un refus de portée, un blocage en lecture seule ou une confirmation refusée n’atteignent jamais le cluster.

L’audit est désactivé par défaut. Activez-le avec CB_MCP_AUDIT_LOG_ENABLED=true ; il écrit sur stderr, sauf si vous définissez CB_MCP_AUDIT_LOG_SINKS=file et 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

Les enregistrements sont au format JSON Lines et utilisent le même vocabulaire de champs que Couchbase Server et 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"}
Fonctionnement de l’audit
  • Identité — real_userid désigne l’appelant : oauth (le sujet du jeton), local (l’utilisateur du système d’exploitation, avec stdio) ou anonymous (HTTP sans OAuth, avec avertissement au démarrage).
  • Corrélation — cid regroupe tous les enregistrements d’une requête et est transmis comme client_context_id SQL++, ce qui permet une jointure exacte avec clientContextId de Couchbase Server. Il n’y a volontairement aucun identifiant de session.
  • Événements — un catalogue fixe et numéroté (cycle de vie, initialisation, jeton rejeté, portée refusée, blocage en lecture seule, confirmation refusée/ignorée, et une paire lecture/écriture par catégorie d’outils). query et search font exception : chacun est consigné comme un événement unique plutôt que comme une paire lecture/écriture, car il était impossible de distinguer ces cas de manière fiable pour les surfaces pilotées par des instructions et de recherche. Les opérations vectorielles relèvent de ces deux catégories. Le catalogue complet est fourni dans le package sous la forme de descriptor.json. Le serveur opérationnel utilise le bloc 0xF000 (61440), Operational Insights utilise 0x10000 (65536), et les deux partagent 0xE000 (57344) pour les événements principaux.
  • Filtrage — CB_MCP_AUDIT_LOG_DISABLED_EVENTS supprime les événements de lecture par identifiant numérique (par ex. 61490,61492). Les événements d’écriture et de sécurité ne peuvent pas être désactivés, pas plus que les catégories à événement unique query (61507, ou 65603 pour Operational Insights) et search (61510) : un événement couvre les écritures et les lectures de chaque catégorie ; le désactiver ferait donc perdre un enregistrement de mutation.
  • Rotation — par taille (CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB, 10 par défaut) et par ancienneté (CB_MCP_AUDIT_LOG_ROTATION_INTERVAL, 1d par défaut), selon la première limite atteinte ; 0 désactive l’une ou l’autre. Les fichiers rotatifs sont horodatés et compressés au format gzip ; le fichier actif reste en texte brut pour tail -f.
  • Fichiers par processus — l’hôte et le pid sont insérés dans le nom (audit.log → audit.<host>.<pid>.log), afin que les processus simultanés ne partagent jamais un fichier.
  • La conservation s’applique par fichier — CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS (10 par défaut) limite les sauvegardes d’un fichier. Chaque nouveau processus écrit dans un nouveau fichier et aucun ancien fichier n’est supprimé ; dimensionnez donc le volume ou supprimez les anciens fichiers audit.*.log*.
  • Poursuite du service en cas d’échec — si le fichier ne peut pas être écrit, le serveur continue de fonctionner et compte les enregistrements perdus ; get_server_configuration_status indique written / dropped / write_errors.
  • Arguments des outils — consignés uniquement avec CB_MCP_AUDIT_LOG_TOOL_ARGS=true, qui affiche un avertissement au démarrage. Cette version n’effectue aucune expurgation : les arguments, y compris le contenu intégral des documents, sont écrits tels quels.

Configuration du client

Chaque client a besoin d’une configuration de serveur issue du guide de démarrage rapide opérationnel ou Operational Insights, dans son propre emplacement de configuration. Les exemples ci-dessous utilisent le serveur opérationnel.

Claude Desktop
  1. Ouvrez le fichier de configuration (voir le guide de démarrage rapide MCP) :
    • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows : %APPDATA%\Claude\claude_desktop_config.json
  2. Ajoutez le serveur sous mcpServers et redémarrez Claude Desktop.

Journaux : macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. Consultez le guide de dépannage MCP.

Cursor
  1. Accédez à Cursor Settings > Tools & Integrations > MCP Tools (voir la documentation MCP de Cursor), ou utilisez le lien d’installation en un clic Installer dans Cursor — puis remplacez la chaîne de connexion et les identifiants fictifs.
  2. Ajoutez la configuration sous mcpServers et enregistrez.
  3. Actualisez la liste des serveurs MCP pour vérifier que couchbase est activé.

Journaux : dans le panneau inférieur, ouvrez Output et sélectionnez Cursor MCP.

Windsurf Editor
  1. Ouvrez Command Palette > Windsurf MCP Configuration Panel, ou Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (voir la documentation MCP de Windsurf).
  2. Cliquez sur Add Server > Add custom server, collez la configuration et enregistrez.
  3. Actualisez la liste des serveurs pour vérifier que couchbase est activé.
VS Code

VS Code utilise servers comme clé de premier niveau au lieu de mcpServers. Placez la configuration dans .vscode/mcp.json pour un espace de travail, ou exécutez MCP: Open User Configuration pour tous les espaces de travail (voir la documentation 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"
      }
    }
  }
}

L’enregistrement du fichier démarre le serveur ; utilisez les actions Running | Stop | n Tools ci-dessus pour le gérer.

Journaux : exécutez MCP: List Servers, sélectionnez couchbase, puis Show Output.

IDE JetBrains
  1. Installez le plugin AI Assistant ou Junie.
  2. Accédez à Settings > Tools > AI Assistant (or Junie) > MCP Server, cliquez sur +, ajoutez la configuration et cliquez sur Apply.
  3. Survolez l’état du serveur pour afficher ses outils.

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

Docker

Des images préconstruites sont publiées sur Docker Hub sous le nom couchbase/mcp-server, et le serveur figure dans le catalogue Docker MCP. Configurez le conteneur avec les mêmes variables d’environnement que ci-dessus. Consultez la page Docker Hub (DOCKER.md) pour les balises, les volumes et des exemples de vérification d’état.

Exécution sur HTTP — notez que le serveur doit écouter sur 0.0.0.0 pour être accessible depuis l’extérieur du conteneur :

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 s’exécute sur votre machine hôte, utilisez couchbase://host.docker.internal comme chaîne de connexion (voir Réseau Docker). Utilisez --network=<your_network> pour rejoindre le réseau d’un autre conteneur.
  • Ajoutez operational-insights au lieu de operational pour exécuter le serveur Operational Insights (port 8001).
Créer l’image à partir des sources
docker build -t mcp/couchbase-src .

./build.sh [image-name] effectue la compilation avec les mêmes arguments que CI — il définit les arguments de compilation GIT_COMMIT_HASH et BUILD_DATE, et étiquette l’image latest et <short-commit> (nom par défaut mcp/couchbase-src). Pour créer manuellement l’image avec les étiquettes :

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

Dépannage

Pour consulter les guides complets, reportez-vous à la documentation de dépannage du serveur opérationnel et du serveur Operational Insights, ainsi qu’aux consignes de sécurité du serveur opérationnel et du serveur Operational Insights. Vérifications rapides :

  • Vérifiez la chaîne de connexion, le nom d’utilisateur et le mot de passe, ou les chemins des certificats.
  • Pour Capella, assurez-vous que le cluster autorise les connexions depuis la machine qui exécute le serveur.
  • Assurez-vous que l’utilisateur de la base de données peut accéder à au moins un bucket.
  • Si le client ne trouve pas uv/uvx, indiquez le chemin absolu dans command.
  • Si vous exécutez le serveur à partir des sources, vérifiez le chemin du dépôt dans la configuration et exécutez uv sync après avoir récupéré les mises à jour.
  • Appelez get_server_configuration_status pour afficher la configuration effectivement résolue par le serveur, et consultez les journaux de votre client (voir Configuration du client).

FAQ

Comment connecter Claude Desktop à Couchbase ? Ajoutez la configuration de démarrage rapide à claude_desktop_config.json et redémarrez Claude Desktop — voir Configuration du client.

Puis-je utiliser ce serveur avec Couchbase Capella ? Oui, avec le serveur opérationnel : la même configuration fonctionne avec Capella et les clusters autogérés, bien que certains outils d’administration ne soient disponibles que sur les clusters autogérés (voir Outils). Le serveur Operational Insights est réservé aux clusters Operational Insights autogérés.

Est-il sûr d’autoriser un agent IA à écrire dans ma base de données ? Par défaut, non : aucun outil d’écriture n’est chargé et les instructions SQL++ de modification sont bloquées. Si vous activez les écritures, vous pouvez toujours désactiver des outils individuels ou exiger une confirmation — mais les autorisations RBAC de votre utilisateur Couchbase restent la véritable limite de sécurité. Voir Contrôles de sécurité.

Dois-je connaître SQL++ ? Non. Posez votre question en langage courant et l’assistant rédige le SQL++ pour run_sql_plus_plus_query. Il peut aussi expliquer un plan de requête ou demander des recommandations à l’Index Advisor.

STDIO ou Streamable HTTP ? STDIO pour un seul client local. Streamable HTTP pour partager un serveur entre plusieurs clients, avec OAuth. Voir Transports.

Couchbase prend-il officiellement ce serveur en charge ? Oui, avec une licence Couchbase AI Data Plane. Sans licence, les ingénieurs Couchbase apportent une aide dans la mesure du possible via les problèmes GitHub. Voir la Politique d’assistance.

Contribution

Les contributions sont les bienvenues : corrections de bogues, fonctionnalités et documentation. Pour signaler un bogue ou demander de l’aide, ouvrez un problème GitHub.

Consultez CONTRIBUTING.md pour la configuration de développement, le linting, les tests, la structure du projet et le flux de travail. Pour commencer :

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

Les tests d’intégration s’exécutent sur un cluster actif. Définissez CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD et, éventuellement, CB_MCP_TEST_BUCKET ; les tests Operational Insights utilisent également CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / _USERNAME / _PASSWORD et sont ignorés si ces variables ne sont pas définies. Exécutez ensuite :

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

Collecte des données d’utilisation, risques liés aux LLM et politique d’assistance

Collecte des données d’utilisation

Ce produit collecte automatiquement des données d’utilisation et de performance (telles que le nom et la version du produit), ainsi que des informations sur le navigateur (telles que l’adresse IP) (collectivement, les « Données d’utilisation »). Couchbase utilise les Données d’utilisation, ainsi que d’autres données que vous pouvez fournir à Couchbase (telles que votre nom d’utilisateur ou votre adresse e-mail), pour développer et améliorer ses produits, ainsi que pour orienter ses programmes de vente et de marketing. Nous n’accédons à aucune donnée que vous stockez dans les produits Couchbase et n’en collectons aucune. Nous utilisons les Données d’utilisation pour comprendre les tendances d’utilisation globales et rendre nos produits plus utiles pour vous. Pour en savoir plus sur la manière dont Couchbase collecte, protège et traite les informations, veuillez consulter la Politique de confidentialité de Couchbase, disponible à l’adresse https://www.couchbase.com/privacy-policy.

Risques associés aux LLM

  • L’utilisation de grands modèles de langage et de technologies similaires comporte des risques, notamment la possibilité de générer des résultats inexacts ou préjudiciables.
  • Couchbase n’examine ni n’évalue la qualité ou l’exactitude de ces résultats, qui peuvent ne pas refléter les opinions de Couchbase.
  • Il vous incombe exclusivement de décider si vous souhaitez utiliser des grands modèles de langage et des technologies connexes, ainsi que de respecter les conditions de licence, les conditions d’utilisation et les politiques de votre organisation régissant leur utilisation.

Politique d’assistance

Couchbase MCP Server est un logiciel open source maintenu par des ingénieurs de Couchbase. La manière d’obtenir de l’aide dépend de votre utilisation :

  • Utilisation par la communauté — signalez des bogues, posez des questions et demandez des fonctionnalités en ouvrant une issue GitHub. Les ingénieurs de Couchbase surveillent le dépôt et répondent dans la mesure du possible, sans engagement de délai de réponse. Le portail d’assistance Couchbase ne peut pas aider les utilisateurs de la communauté.
  • Assistance aux entreprises — disponible sous licence Couchbase AI Data Plane, qui couvre également Couchbase Agent Memory et Couchbase Agent Catalog. Les clients titulaires d’une licence bénéficient d’une assistance par l’intermédiaire de leurs canaux habituels d’assistance Couchbase.

Merci d’utiliser le projet et d’y contribuer !