Activer et se connecter au serveur MCP distant de ClickHouse Cloud

Ce guide explique comment activer le serveur MCP distant de ClickHouse Cloud et le configurer pour l’utiliser avec les outils de développement courants. Prérequis

Un service ClickHouse Cloud actif
Votre IDE ou l’outil de développement agentique de votre choix
Pour l’authentification sans interface graphique, une API key ClickHouse Cloud ayant accès à l’organisation et aux services requis

Activer le serveur MCP distant dans Cloud

Connectez-vous au service ClickHouse Cloud pour lequel vous souhaitez activer le serveur MCP distant. Dans le menu de gauche, cliquez sur Connect. Une fenêtre contenant les informations de connexion s’ouvre. Sélectionnez Connect with MCP : Activez le bouton pour activer MCP sur le service. L’activation ou la désactivation de MCP nécessite la permission control-plane:service:manage-mcp (voir Console roles and permissions) : Copiez l’URL affichée, qui est identique à celle ci-dessous :

https://mcp.clickhouse.cloud/mcp

Configurer MCP distant pour le développement

Choisissez votre IDE ou votre outil ci-dessous, puis suivez les instructions de configuration correspondantes.

S’authentifier depuis un environnement sans interface graphique

Si votre client MCP s’exécute sur un hôte distant ou sans interface graphique, où un flux OAuth via un navigateur n’est pas envisageable, authentifiez-vous plutôt avec une API key ClickHouse Cloud.

Dans la console ClickHouse Cloud, ouvrez votre organisation et sélectionnez API Keys.
Créez une clé dotée des rôles et permissions minimaux nécessaires pour les organisations et les services auxquels le client MCP doit accéder, puis téléchargez l’ID et le secret de la clé.
Sur l’hôte distant, fournissez les identifiants via votre système de gestion des secrets et générez une valeur d’autorisation HTTP Basic :

export CLICKHOUSE_CLOUD_API_KEY="<key_id>"
export CLICKHOUSE_CLOUD_API_SECRET="<key_secret>"

export CH_AUTH="Basic $(
  printf '%s:%s' \
    "$CLICKHOUSE_CLOUD_API_KEY" \
    "$CLICKHOUSE_CLOUD_API_SECRET" |
  base64 | tr -d '\n'
)"

Sélectionnez votre client MCP et ajoutez le serveur MCP distant :

Claude Code
Codex
OpenCode

claude mcp add \
  --scope user \
  --transport http \
  clickhouse-cloud \
  https://mcp.clickhouse.cloud/mcp \
  --header 'Authorization: ${CH_AUTH}'

Claude Code lit la valeur de CH_AUTH dans l’environnement au moment de la connexion. Lancez Claude Code et exécutez /mcp pour vérifier que clickhouse-cloud est connecté.Consultez la documentation MCP de Claude Code pour plus de détails sur les serveurs HTTP distants et la configuration des en-têtes.

Ajoutez l’entrée suivante au fichier ~/.codex/config.toml :

[mcp_servers.clickhouse-cloud]
url = "https://mcp.clickhouse.cloud/mcp"
env_http_headers = { Authorization = "CH_AUTH" }

Exécutez codex mcp list pour vérifier que clickhouse-cloud est configuré.Consultez la référence de configuration de Codex pour plus de détails sur mcp_servers.<id>.env_http_headers.

Ajoutez l’entrée suivante à votre fichier de configuration opencode.jsonc :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "clickhouse-cloud": {
        "type": "remote",
        "url": "https://mcp.clickhouse.cloud/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "{env:CH_AUTH}"
        }
      }
    }
  }
}

Exécutez opencode mcp list pour vérifier que clickhouse-cloud est connecté.Consultez la documentation MCP d’OpenCode pour plus de détails sur les serveurs distants, les en-têtes et la substitution de variables d’environnement.

Veillez à ce que CH_AUTH reste disponible dans chaque session client, et ne commitez jamais l’API key, le secret ni la valeur de CH_AUTH dans votre système de gestion de versions. L’encodage Base64 ne chiffre pas les identifiants. Cette méthode d’authentification par API key ne nécessite ni navigateur ni connexion distincte via clickhousectl.

Claude Code

Depuis votre répertoire de travail, exécutez la commande suivante pour ajouter la configuration du MCP Server de ClickHouse Cloud à Claude Code :

claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp

Lancez ensuite Claude Code :

claude

Exécutez la commande suivante pour afficher la liste des serveurs MCP :

/mcp

Sélectionnez clickhouse-cloud et authentifiez-vous via OAuth avec vos identifiants ClickHouse Cloud.

Claude web UI

Accédez à Customize > Connectors
Cliquez sur l’icône « + », puis sur Add custom connector
Donnez au connecteur personnalisé un nom tel que clickhouse-cloud, puis ajoutez-le
Cliquez sur le connecteur clickhouse-cloud que vous venez d’ajouter, puis sur Connect
Authentifiez-vous avec vos identifiants ClickHouse Cloud via OAuth

Cursor

Parcourez et installez des serveurs MCP depuis le Marketplace de Cursor.
Recherchez ClickHouse et cliquez sur “Add to Cursor” sur le serveur de votre choix pour l’installer
Authentifiez-vous avec OAuth.

Visual Studio Code

Ajoutez la configuration suivante dans votre fichier .vscode/mcp.json :

{
  "servers": {
    "clickhouse-cloud": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

Pour plus d’informations, consultez la documentation de Visual Studio Code.

Windsurf

Modifiez votre fichier mcp_config.json comme suit :

{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    }
  }
}

Pour en savoir plus, consultez la documentation Windsurf.

Zed

Ajoutez ClickHouse comme serveur personnalisé. Ajoutez les éléments suivants dans les paramètres de Zed, sous context_servers :

{
  "context_servers": {
    "clickhouse-cloud": {
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

Zed devrait alors vous demander de vous authentifier via OAuth lors de sa première connexion au serveur. Pour plus de détails, consultez la documentation de Zed.

Codex

Exécutez la commande suivante pour ajouter le serveur MCP ClickHouse Cloud via le CLI :

codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp

Exemple d’utilisation

Une fois connecté, vous pouvez interagir avec ClickHouse Cloud à l’aide de prompts en langage naturel. Vous trouverez ci-dessous quelques workflows courants, ainsi que les outils que votre client MCP invoquera en arrière-plan. Pour obtenir la liste complète des outils disponibles, consultez la référence des outils.

Explorer vos données

Commencez par découvrir ce qui est disponible :

Prompt	Outil appelé
”À quelles organisations ai-je accès ?”	`get_organizations`
”Quelles bases de données sont disponibles sur mon service ?”	`list_databases`
”Quelles tables contient la base de données `default` ?”	`list_tables`
”Liste toutes les tables dont le nom commence par `events_`”	`list_tables` (avec le filtre `like`)

Exécuter des requêtes analytiques

Posez vos questions en langage naturel, et l’agent les traduira en SQL :

Prompt	Outil invoqué
”Montre-moi les 10 premières lignes de la table `hits`”	`run_select_query`
”Quelle est la durée moyenne des sessions par pays sur les 7 derniers jours ?”	`run_select_query`
”Combien y a-t-il de lignes dans chaque table de la base de données `analytics` ?”	`run_select_query`

L’outil run_select_query n’autorise que les instructions SELECT. Toutes les requêtes sont en lecture seule.

Gérer les services et l’infrastructure

Obtenez une vue d’ensemble de vos ressources ClickHouse Cloud :

Instruction	Outil invoqué
”Liste tous mes services”	`get_services_list`
”Quel est l’état de mon service de production ?”	`get_service_details`
”Affiche la planification des sauvegardes pour ce service”	`get_service_backup_configuration`
”Liste les sauvegardes récentes”	`list_service_backups`
”Quels ClickPipes sont configurés sur ce service ?”	`list_clickpipes`

Suivi des coûts

Prompt	Outil invoqué
”Quel a été le coût de mon organisation la semaine dernière ?”	`get_organization_cost`
”Affiche-moi les coûts quotidiens du 1er mars au 15 mars”	`get_organization_cost` (avec `from_date` et `to_date`)

ClickHouse agent skills

Premiers pas

Services et infrastructure

Bring Your Own Cloud

Données et intégrations

Se connecter et exécuter des requêtes

Gestion des accès

Sécurité et conformité

Supervision et sauvegardes

Outils et agents d’IA

API Cloud

Facturation

Assistance

ClickHouse Private

Activer et se connecter au serveur MCP distant de ClickHouse Cloud

Activer le serveur MCP distant dans Cloud

Configurer MCP distant pour le développement

S’authentifier depuis un environnement sans interface graphique

Claude Code

Claude web UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Exemple d’utilisation

Explorer vos données

Exécuter des requêtes analytiques

Gérer les services et l’infrastructure

Suivi des coûts

​Activer le serveur MCP distant dans Cloud

​Configurer MCP distant pour le développement

​S’authentifier depuis un environnement sans interface graphique

​Claude Code

​Claude web UI

​Cursor

​Visual Studio Code

​Windsurf

​Zed

​Codex

​Exemple d’utilisation

​Explorer vos données

​Exécuter des requêtes analytiques

​Gérer les services et l’infrastructure

​Suivi des coûts

​Contenu connexe

Activer le serveur MCP distant dans Cloud

Configurer MCP distant pour le développement

S’authentifier depuis un environnement sans interface graphique

Claude Code

Claude web UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Exemple d’utilisation

Explorer vos données

Exécuter des requêtes analytiques

Gérer les services et l’infrastructure

Suivi des coûts

Contenu connexe