Couchbase
officielInteragissez 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.
Documentation complète : docs.couchbase.com/mcp-server
Table des matières
- Pourquoi choisir le serveur MCP Couchbase
- Choisir un serveur
- Serveur opérationnel
- Serveur Operational Insights
- Configuration commune
- Configuration du client
- Docker
- Dépannage
- FAQ
- Contribution
- Données d’utilisation, risques liés aux LLM et politique d’assistance
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
usersoù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
productsavec ces champs : … » (nécessiteCB_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érationnel | Serveur Operational Insights | |
|---|---|---|
| À utiliser avec | Un cluster Couchbase (Capella ou autogéré) | Un cluster Operational Insights autogéré (non disponible sur Capella) |
| Sous-commande | operational (par défaut) | operational-insights |
| Chaîne de connexion | couchbase:// / couchbases:// | URL HTTP(S), p. ex. http://localhost:8095 |
| Variables d’identifiants | CB_CONNECTION_STRING, CB_USERNAME, … | CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, … |
| Outils | 52 — état du cluster, schéma, KV, SQL++, index, recherche en texte intégral et vectorielle, performances des requêtes | 13 — schéma, SQL++ (synchrone et asynchrone), index, exportations |
| Port HTTP par défaut | 8000 | 8001 |
| Fichier journal par défaut | mcp_server.log | mcp_server_operational_insights.log |
La sous-commande est actuellement facultative pour le serveur opérationnel — un simple
couchbase-mcp-serverle 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 avecuvx 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’environnement | Argument CLI | Description |
|---|---|---|
CB_CONNECTION_STRING | --connection-string | Chaîne de connexion au cluster. Obligatoire |
CB_USERNAME / CB_PASSWORD | --username / --password | Authentification de base |
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH | --client-cert-path / --client-key-path | Authentification mTLS |
CB_CA_CERT_PATH | --ca-cert-path | Certificat 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
| Outil | Description |
|---|---|
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_connection | Vé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_report | Diagnostics 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
| Outil | Description |
|---|---|
get_buckets_in_cluster | Répertorier tous les buckets du cluster |
get_scopes_in_bucket | Répertorier tous les scopes d’un bucket |
get_collections_in_scope | Répertorier toutes les collections d’un scope (nécessite le service Query) |
get_scopes_and_collections_in_bucket | Répertorier tous les scopes et collections d’un bucket |
get_schema_for_collection | Dé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)
| Outil | Description |
|---|---|
get_document_by_id | Récupérer un document par son ID |
lookup_subdocument | Lire 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
| Outil | Description |
|---|---|
run_sql_plus_plus_query | Exé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_query | Générer et évaluer un plan EXPLAIN : métadonnées, plan extrait et résultats |
get_index_advisor_recommendations | Recommandations d’Index Advisor pour une requête SQL++ |
list_indexes | Ré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.
| Outil | Description |
|---|---|
list_search_indexes | Lister les index Search — au niveau du cluster, par bucket ou par scope |
get_search_index_definition | Définition complète d’un index Search (mappings, analyseurs, paramètres du plan) |
run_search | Exé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.
| Outil | Description |
|---|---|
run_vector_query | Recherche 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_search | Recherche 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
| Outil | Description |
|---|---|
get_longest_running_queries | Requêtes les plus longues selon le temps de service moyen |
get_most_frequent_queries | Requêtes exécutées le plus fréquemment |
get_queries_with_largest_response_sizes | Requêtes avec les réponses les plus volumineuses |
get_queries_with_large_result_count | Requêtes avec le plus grand nombre de résultats |
get_queries_using_primary_index | Requêtes utilisant un index primaire |
get_queries_not_using_covering_index | Requêtes n’utilisant pas d’index couvrant |
get_queries_not_selective | Requê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.
| Outil | Description |
|---|---|
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_queries | Requê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.
| Outil | Point de terminaison requis |
|---|---|
get_cluster_metrics | REST de gestion (/pools/default/stats/range) |
get_cluster_tasks | REST de gestion (/pools/default/tasks) |
get_bucket_config | REST de gestion (/pools/default/buckets[/<name>]) |
get_cluster_health_snapshot | REST de gestion, ainsi que des points de terminaison par nœud |
get_cluster_system_events | REST de gestion (/events) |
get_index_stats | REST du service Index (le /api/v1/stats de chaque indexeur) |
get_cluster_query_vitals | REST du service Query (/admin/vitals) |
get_active_queries | REST du service Query (/admin/active_requests) |
delete_active_query | REST du service Query (DELETE /admin/active_requests/{id}) |
discover_tool_input_values | Aucun (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_PROVIDER | Obligatoire | Facultatif | Remarques |
|---|---|---|---|
capella | CB_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 |
openai | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | Définissez le point de terminaison pour utiliser un serveur local compatible avec 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 | Modè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’environnement | Argument CLI | Description | Valeur par défaut |
|---|---|---|---|
CB_CONNECTION_STRING | --connection-string | Chaîne de connexion au cluster Couchbase | Obligatoire |
CB_USERNAME | --username | Nom d’utilisateur ayant accès aux buckets requis pour l’authentification de base | Obligatoire (ou certificat client et clé requis pour mTLS) |
CB_PASSWORD | --password | Mot de passe pour l’authentification de base | Obligatoire (ou certificat client et clé requis pour mTLS) |
CB_CLIENT_CERT_PATH | --client-cert-path | Chemin vers le fichier de certificat client pour l’authentification mTLS | Obligatoire si mTLS est utilisé (ou nom d’utilisateur et mot de passe requis) |
CB_CLIENT_KEY_PATH | --client-key-path | Chemin vers le fichier de clé client pour l’authentification mTLS | Obligatoire si mTLS est utilisé (ou nom d’utilisateur et mot de passe requis) |
CB_CA_CERT_PATH | --ca-cert-path | Chemin 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-mode | Empê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 | --transport | Mode de transport : stdio, http | stdio |
CB_MCP_HOST | --host | Hôte pour le mode de transport HTTP | 127.0.0.1 |
CB_MCP_PORT | --port | Port pour le mode de transport HTTP | 8000 |
CB_MCP_WORKERS | --workers | Nombre 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-http | Traiter 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-tools | Outils à désactiver (voir Désactivation des outils) | Aucun |
CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | Outils 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-level | Niveau de journalisation du serveur MCP : off, debug, info, warning, error (voir Journalisation) | info |
CB_MCP_LOG_SINKS | --log-sinks | Destinations des journaux, séparées par des virgules : stderr, file, ou les deux (voir Journalisation) | stderr |
CB_MCP_LOG_FILE | --log-file | Chemin 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-mb | Taille 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émarrage | 1 (1 Mo) |
CB_MCP_LOG_MAX_BYTES | --log-max-bytes | Obsolè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éfini | Non défini |
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB | --log-error-rotation-max-size-mb | Taille de rotation en Mo du fichier journal ERROR ; remplace CB_MCP_LOG_ROTATION_MAX_SIZE_MB pour ERROR | Hérite de CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB | --log-warning-rotation-max-size-mb | Taille de rotation en Mo du fichier journal WARNING ; remplace CB_MCP_LOG_ROTATION_MAX_SIZE_MB pour WARNING | Hérite de CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB | --log-info-rotation-max-size-mb | Taille de rotation en Mo du fichier journal INFO ; remplace CB_MCP_LOG_ROTATION_MAX_SIZE_MB pour INFO | Hérite de CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB | --log-debug-rotation-max-size-mb | Taille de rotation en Mo du fichier journal DEBUG ; remplace CB_MCP_LOG_ROTATION_MAX_SIZE_MB pour DEBUG | Hérite de CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_RETENTION_BACKUP_COUNT | --log-retention-backup-count | Nombre 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-count | Nombre de fichiers de sauvegarde après rotation conservés pour le fichier journal ERROR ; remplace le nombre global pour ERROR | Hérite de CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT | --log-warning-retention-backup-count | Nombre de fichiers de sauvegarde après rotation conservés pour le fichier journal WARNING ; remplace le nombre global pour WARNING | Hérite de CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT | --log-info-retention-backup-count | Nombre de fichiers de sauvegarde après rotation conservés pour le fichier journal INFO ; remplace le nombre global pour INFO | Hérite de CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT | --log-debug-retention-backup-count | Nombre de fichiers de sauvegarde après rotation conservés pour le fichier journal DEBUG ; remplace le nombre global pour DEBUG | Hérite de CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_OAUTH_JWT_JWKS_URI | --oauth-jwks-uri | Point 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-issuer | Claim JWT iss attendu. Obligatoire pour activer OAuth | Aucun |
CB_MCP_OAUTH_JWT_AUDIENCE | --oauth-audience | Claim JWT aud attendu. Obligatoire pour activer OAuth | Aucun |
CB_MCP_OAUTH_JWT_ALGORITHM | --oauth-algorithm | Algorithme de signature JWT : l’un de RS256/384/512, ES256/384/512, PS256/384/512 | RS256 |
CB_MCP_OAUTH_MCP_BASE_URL | --oauth-mcp-base-url | URL 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-label | Remplacer 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 canonique | couchbase-mcp:read |
CB_MCP_OAUTH_SCOPE_WRITE_LABEL | --oauth-scope-write-label | Remplacer le libellé de scope OAuth considéré comme un accès « écriture » ; même sémantique que pour le libellé de lecture | couchbase-mcp:write |
CB_MCP_AUDIT_LOG_ENABLED | --audit-log-enabled | Activer 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-sinks | Destinations 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 stdio | console |
CB_MCP_AUDIT_LOG_FILE_PATH | --audit-log-file-path | Chemin 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-mb | Taille maximale en Mo que le fichier d’audit actif peut atteindre avant sa rotation. 0 désactive la rotation basée sur la taille | 10 (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 intervalle | 1d |
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS | --audit-log-retention-max-backups | Nombre 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 Audit | 10 |
CB_MCP_AUDIT_LOG_TOOL_ARGS | --audit-log-tool-args | Enregistrer 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 documents | false |
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és | Aucun |
CB_MCP_EMBEDDING_MODEL_PROVIDER | --embedding-model-provider | Fournisseur 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’embeddings | Aucun |
CB_MCP_EMBEDDING_MODEL | --embedding-model | Nom/ID du modèle pour le fournisseur d’embeddings configuré | Aucun |
CB_MCP_EMBEDDING_MODEL_API_KEY | --embedding-model-api-key | Clé 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-endpoint | Remplacement 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-id | ID de clé d’accès AWS, fournisseur bedrock uniquement. Omettre pour utiliser la chaîne d’identifiants AWS par défaut | Aucun |
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY | --embedding-model-aws-secret-access-key | Clé d’accès secrète AWS, fournisseur bedrock uniquement | Aucun |
CB_MCP_EMBEDDING_MODEL_AWS_REGION | --embedding-model-aws-region | Région AWS, fournisseur bedrock uniquement. Si elle n’est pas définie, la résolution de région propre au SDK AWS est utilisée | Aucun |
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_STRINGest une URL HTTP(S), et non une chaîne de connexioncouchbase://— par exemplehttp://localhost:8095, ouhttps://<host>:18095avec 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’environnement | Argument CLI | Description |
|---|---|---|
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING | --connection-string | URL du point de terminaison (HTTP/HTTPS). Obligatoire |
CB_OPERATIONAL_INSIGHTS_USERNAME | --username | Nom d’utilisateur |
CB_OPERATIONAL_INSIGHTS_PASSWORD | --password | Mot de passe |
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH | --ca-cert-path | Certificat racine (PEM) pour un certificat de serveur auto-signé/non approuvé |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH | --client-cert-path | Certificat 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-path | Clé privée (PEM) du certificat client. Laisser non défini pour PKCS#12 |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD | --client-cert-password | Mot 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-size | Taille 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-timeout | Dé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
8001et le fichier journal par défaut estmcp_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
| Outil | Description |
|---|---|
get_server_configuration_status | Même outil que sur le serveur opérationnel |
Découverte du modèle de données et du schéma
| Outil | Description |
|---|---|
operational_insights_get_databases_in_cluster | Répertorier les bases de données |
operational_insights_get_scopes_in_database | Répertorier les scopes d’une base de données |
operational_insights_get_collections_in_scope | Répertorier les collections (ensembles de données) d’un scope |
operational_insights_get_schema_for_collection | Déduire le schéma JSON d’une collection par échantillonnage |
Requêtes et index
| Outil | Description |
|---|---|
operational_insights_list_indexes | Répertorier les index secondaires de System.Metadata.Index |
operational_insights_explain_query | Expliquer une instruction SQL++ sans l’exécuter |
operational_insights_run_query_sync | Exé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_async | Dé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_results | Interroger une requête asynchrone ; renvoie les lignes (ou la destination d’exportation) lorsqu’elles sont prêtes |
operational_insights_discard_async_query_results | Libérer les résultats d’une requête asynchrone terminée |
operational_insights_cancel_async_query | Arrê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=falseou un jeton aveccouchbase-mcp:write. csvn’est pas proposé, car il nécessite un schéma de sortie explicite qui ne peut pas être déduit d’unSELECTarbitraire.
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_TOOLSpour 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_idetdelete_document_by_idn’empêche pasrun_sql_plus_plus_queryd’exécuterINSERT/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=trueouCB_MCP_WORKERSsupé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 pour | Point de terminaison |
|---|---|---|
stdio (par défaut) | Un client local qui lance le serveur en tant que sous-processus | — |
http | Plusieurs clients partageant un serveur ; prend en charge OAuth, les vérifications d’état et les workers sur le serveur opérationnel | http://<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
httpest 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=trueavec 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 charge | Paramètre du serveur | Outils nécessitant une confirmation |
|---|---|---|
Sessions persistantes, routées selon l’en-tête de requête Mcp-Session-Id | Un worker, avec état (par défaut) | Pris en charge |
| Aucune session persistante | --stateless-http=true | Non 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_handledans 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 renvoieUnknown 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 aucunMcp-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_ISSUERetCB_MCP_OAUTH_JWT_AUDIENCEsont définis ; si certains seulement le sont, le démarrage échoue. CB_MCP_OAUTH_MCP_BASE_URLpublie é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/scpdu jeton :couchbase-mcp:read(outils de lecture) etcouchbase-mcp:write(outils d’écriture). L’accès complet nécessite les deux. Renommez-les avecCB_MCP_OAUTH_SCOPE_READ_LABEL/CB_MCP_OAUTH_SCOPE_WRITE_LABELsi 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) oudebug.CB_MCP_LOG_SINKS—stderr,file, ou les deux. Avecfile, un fichier rotatif par niveau est écrit à côté deCB_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) etCB_MCP_LOG_RETENTION_BACKUP_COUNT(1 par défaut) s’appliquent à chaque niveau ; remplacez-les par niveau avecCB_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_BYTESest 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 dansmcp_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_useriddésigne l’appelant :oauth(le sujet du jeton),local(l’utilisateur du système d’exploitation, avec stdio) ouanonymous(HTTP sans OAuth, avec avertissement au démarrage). - Corrélation —
cidregroupe tous les enregistrements d’une requête et est transmis commeclient_context_idSQL++, ce qui permet une jointure exacte avecclientContextIdde 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).
queryetsearchfont 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 dedescriptor.json. Le serveur opérationnel utilise le bloc0xF000(61440), Operational Insights utilise0x10000(65536), et les deux partagent0xE000(57344) pour les événements principaux. - Filtrage —
CB_MCP_AUDIT_LOG_DISABLED_EVENTSsupprime 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 uniquequery(61507, ou 65603 pour Operational Insights) etsearch(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,1dpar défaut), selon la première limite atteinte ;0dé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 pourtail -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 fichiersaudit.*.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_statusindiquewritten/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
- 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
- macOS :
- Ajoutez le serveur sous
mcpServerset redémarrez Claude Desktop.
Journaux : macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. Consultez le guide de dépannage MCP.
Cursor
- 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.
- Ajoutez la configuration sous
mcpServerset enregistrez. - Actualisez la liste des serveurs MCP pour vérifier que
couchbaseest activé.
Journaux : dans le panneau inférieur, ouvrez Output et sélectionnez Cursor MCP.
Windsurf Editor
- Ouvrez Command Palette > Windsurf MCP Configuration Panel, ou Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (voir la documentation MCP de Windsurf).
- Cliquez sur Add Server > Add custom server, collez la configuration et enregistrez.
- Actualisez la liste des serveurs pour vérifier que
couchbaseest 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
- Installez le plugin AI Assistant ou Junie.
- Accédez à Settings > Tools > AI Assistant (or Junie) > MCP Server, cliquez sur +, ajoutez la configuration et cliquez sur Apply.
- 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.internalcomme chaîne de connexion (voir Réseau Docker). Utilisez--network=<your_network>pour rejoindre le réseau d’un autre conteneur. - Ajoutez
operational-insightsau lieu deoperationalpour exécuter le serveur Operational Insights (port8001).
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 danscommand. - Si vous exécutez le serveur à partir des sources, vérifiez le chemin du dépôt dans la configuration et exécutez
uv syncaprès avoir récupéré les mises à jour. - Appelez
get_server_configuration_statuspour 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 !