Hydrolix

Serveur MCP Hydrolix

Un serveur MCP pour Hydrolix.

Démarrage rapide

Mettez-vous en route en quelques minutes. Cette section couvre Claude Desktop et Claude Code.

Étape 1 — Prérequis

Avant de commencer, assurez-vous d'avoir :

• Identifiants Hydrolix — le nom d'hôte de votre cluster ainsi qu'un nom d'utilisateur/mot de passe ou un jeton de compte de service. Si vous ne les avez pas, demandez à votre administrateur Hydrolix.
• Claude Desktop — téléchargez-le depuis claude.ai/download.

Étape 2 — Installer le serveur MCP

Choisissez la méthode qui correspond à votre configuration :

Option A : Utiliser uv (recommandé)

uv gère Python automatiquement et télécharge mcp-hydrolix à la demande, donc aucune étape d'installation séparée n'est nécessaire. Si vous n'avez pas uv, installez-le :

macOS / Linux :

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell) :

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Option B : Utiliser pip

Nécessite Python 3.13+. Si vous devez installer Python, téléchargez-le depuis python.org.

pip install mcp-hydrolix

Étape 3 — Configurer Claude Desktop

1. Ouvrez le fichier de configuration de Claude Desktop :

   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows : %APPDATA%\Claude\claude_desktop_config.json
   • Linux : ~/.config/Claude/claude_desktop_config.json

2. Ajoutez l'entrée suivante à l'objet "mcpServers" (créez le fichier avec ce contenu s'il n'existe pas encore) :

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<your-hydrolix-hostname>",
        "HYDROLIX_USER": "<your-username>",
        "HYDROLIX_PASSWORD": "<your-password>"
      }
    }
  }
}

Remplacez <your-hydrolix-hostname>, <your-username> et <your-password> par vos identifiants réels.

[!NOTE] Si vous avez utilisé l'option B (pip), utilisez "command": "mcp-hydrolix" sans champ "args" à la place.

[!TIP] Si le fichier contient déjà d'autres entrées, ajoutez le bloc "mcp-hydrolix" à l'intérieur de l'objet "mcpServers" existant plutôt que de remplacer tout le fichier.

[!NOTE] Si vous vous authentifiez avec un jeton de compte de service au lieu d'un nom d'utilisateur/mot de passe, consultez Authentification.

Commande introuvable ?

Claude Desktop se lance sans le PATH de votre shell, il peut donc ne pas localiser le binaire même s'il est installé. Trouvez le chemin complet et utilisez-le comme valeur "command" dans la configuration.

Option A (uv) : trouvez uvx :

• macOS / Linux : which uvx
• Windows : where.exe uvx

Option B (pip) : trouvez mcp-hydrolix :

• macOS / Linux : which mcp-hydrolix
• Windows : where.exe mcp-hydrolix

Si which/where.exe ne renvoie rien, le binaire n'est pas dans votre PATH. La solution la plus propre est de passer à l'option A (uv), qui gère l'environnement Python et le PATH pour vous.

Étape 4 — Redémarrer Claude Desktop

Redémarrez l'application pour appliquer la configuration.

Utilisateurs macOS / Windows : Assurez-vous de quitter complètement Claude avant de redémarrer. Sur macOS, appuyez sur Cmd+Q ou faites un clic droit sur l'icône du Dock et choisissez Quitter. Sur Windows, utilisez l'icône de la barre d'état système.

Étape 5 — Vérifier que tout fonctionne

1. Ouvrez une nouvelle conversation dans Claude Desktop. Recherchez une icône d'outils/marteau près de la zone de saisie de texte — cela confirme que le serveur MCP s'est connecté avec succès.

2. Essayez cette invite pour confirmer que tout fonctionne :

   En utilisant vos outils MCP Hydrolix, listez les bases de données disponibles.

Claude devrait appeler l'outil list_databases et renvoyer une liste de bases de données depuis votre cluster.

---

Vous préférez utiliser Claude Code ?

Si vous préférez la ligne de commande, assurez-vous que uv est installé (Option A de l'Étape 2), puis exécutez :

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_URL=https://<your-hydrolix-hostname> \
  --env HYDROLIX_USER=<your-username> \
  --env HYDROLIX_PASSWORD=<your-password> \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

Ensuite, ouvrez Claude Code et testez avec la même invite :

En utilisant vos outils MCP Hydrolix, listez les bases de données disponibles.

Vous préférez utiliser VS Code ?

Cliquez sur le badge Installer dans VS Code en haut de ce README pour une installation en un clic. Si vous préférez le flux d'interface, ouvrez la Palette de commandes (Cmd+Shift+P / Ctrl+Shift+P), exécutez MCP : Ajouter un serveur, choisissez Commande (stdio), et réutilisez la commande uvx ... et le bloc env de l'Étape 3.

Outils

• run_select_query

  • Exécutez des requêtes SQL sur votre cluster Hydrolix.
  • Entrée : query (chaîne) : La requête SQL à exécuter.
  • Entrée : max_cells (entier, facultatif) : Budget de cellules de résultat (lignes × colonnes) ; lorsque le serveur définit un plafond, un appelant ne peut que le réduire.
  • Entrée : purpose (chaîne, obligatoire) : Pourquoi la requête est exécutée ; enregistré avec la requête comme hdx_query_comment.
  • Une clause FORMAT finale est supprimée ; le serveur sélectionne le format de transmission.

• list_databases

  • Listez toutes les bases de données sur votre cluster Hydrolix.

• list_tables

  • Listez toutes les tables dans une base de données.
  • Entrée : database (chaîne) : Le nom de la base de données.

• get_table_info

  • Obtenez les métadonnées de table telles que le schéma
  • Entrée : database (chaîne) : Le nom de la base de données.
  • Entrée : table (chaîne) : Le nom de la table.

Utilisation efficace

En raison de la grande variété des architectures LLM, tous les modèles n'utiliseront pas proactivement les outils ci-dessus, et peu les utiliseront efficacement sans conseils, même avec les descriptions d'outils soigneusement construites fournies au modèle. Pour obtenir les meilleurs résultats de votre modèle tout en utilisant le serveur MCP Hydrolix, nous recommandons ce qui suit :

• Référez-vous à votre base de données Hydrolix par son nom et demandez l'utilisation des outils dans vos invites (par exemple, « En utilisant les outils MCP pour accéder à ma base de données Hydrolix, veuillez... »)
  • Cela encourage le modèle à utiliser les outils MCP disponibles et minimise les hallucinations.
• Incluez des plages de temps dans vos invites (par exemple, « Entre le 5 décembre 2023 et le 18 janvier 2024, ... ») et demandez spécifiquement que la sortie soit triée par horodatage.
  • Cela incite le modèle à écrire des requêtes plus efficaces qui tirent parti des optimisations de clé primaire

Point de terminaison de vérification de santé

Lors de l'exécution avec un transport HTTP ou SSE, un point de terminaison de vérification de santé est disponible à /health. Ce point de terminaison :

• Renvoie 200 OK avec la version Clickhouse de la tête de requête Hydrolix si le serveur est sain et peut se connecter à Hydrolix
• Renvoie 503 Service Unavailable si le serveur ne peut pas se connecter à la tête de requête Hydrolix

Exemple :

curl http://localhost:8000/health
# Response: OK - Connected to Hydrolix compatible with ClickHouse 24.3.1

Configuration

Le serveur MCP Hydrolix est configuré à l'aide d'une entrée de serveur MCP standard. Consultez la documentation de votre client pour des instructions spécifiques sur où trouver ou déclarer les serveurs MCP. Un exemple de configuration utilisant Claude Desktop est documenté ci-dessous.

La méthode recommandée pour lancer le serveur MCP Hydrolix est via le gestionnaire de projet uv, qui gérera l'installation de toutes les autres dépendances dans un environnement isolé.

Authentification

Le serveur prend en charge plusieurs méthodes d'authentification avec la précédence suivante (de la plus élevée à la plus basse) :

1. Jeton Bearer par requête : Jeton de compte de service fourni via l'en-tête Authorization: Bearer <token>
2. Paramètre GET par requête : Jeton de compte de service fourni via le paramètre de requête ?token=<token>
3. Identifiants basés sur l'environnement : Identifiants configurés via des variables d'environnement
   • Jeton de compte de service (HYDROLIX_TOKEN), ou
   • Nom d'utilisateur et mot de passe (HYDROLIX_USER et HYDROLIX_PASSWORD)

Lorsque plusieurs méthodes d'authentification sont configurées, le serveur utilisera la première méthode disponible dans l'ordre de précédence ci-dessus. L'authentification par requête n'est disponible qu'avec les modes de transport HTTP ou SSE. La forme ?token= existe pour les clients qui ne peuvent pas envoyer d'en-têtes ; définissez HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false sur les déploiements où chaque client envoie l'en-tête Authorization (voir Identifiants par requête).

Remarque : L'utilisation d'un jeton de compte de service avec un rôle en lecture seule est recommandée.

Définition du serveur MCP utilisant un nom d'utilisateur et un mot de passe (JSON) :

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_USER": "<hydrolix-user>",
    "HYDROLIX_PASSWORD": "<hydrolix-password>"
  }
}

Définition du serveur MCP utilisant un jeton de compte de service (JSON) :

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
  }
}

Définition du serveur MCP utilisant un nom d'utilisateur et un mot de passe (YAML) :

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_URL: https://<hydrolix-host>
  HYDROLIX_USER: <hydrolix-user>
  HYDROLIX_PASSWORD: <hydrolix-password>

Définition du serveur MCP utilisant un jeton de compte de service (YAML) :

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_URL: https://<hydrolix-host>
  HYDROLIX_TOKEN: <hydrolix-service-account-token>

Exemple de configuration (Claude Desktop)

1. Ouvrez le fichier de configuration de Claude Desktop situé à :

   • Sur macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
   • Sur Windows : %APPDATA%/Claude/claude_desktop_config.json

2. Ajoutez une entrée de serveur mcp-hydrolix au bloc de configuration mcpServers pour utiliser un nom d'utilisateur et un mot de passe :

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<hydrolix-host>",
        "HYDROLIX_USER": "<hydrolix-user>",
        "HYDROLIX_PASSWORD": "<hydrolix-password>"
      }
    }
  }
}

Pour utiliser un compte de service, utilisez le bloc de configuration suivant :

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<hydrolix-host>",
        "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
      }
    }
  }
}

3. Mettez à jour les définitions de variables d'environnement pour pointer vers votre cluster Hydrolix.

4. (Recommandé) Localisez l'entrée de commande pour uvx et remplacez-la par le chemin absolu vers l'exécutable uvx. Cela garantit que la version correcte de uvx est utilisée au démarrage du serveur. Vous pouvez trouver ce chemin en utilisant which uvx ou where.exe uvx.

5. Redémarrez Claude Desktop pour appliquer les modifications. Si vous utilisez Windows, assurez-vous que Claude est complètement arrêté en fermant le client via l'icône de la barre d'état système.

Exemple de configuration (Claude Code)

Pour configurer le serveur MCP Hydrolix pour Claude Code, exécutez la commande suivante :

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_USER=<hydrolix-user> \
  --env HYDROLIX_PASSWORD=<hydrolix-password> \
  --env HYDROLIX_URL=https://<hydrolix-host> \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

Variables d'environnement

Les variables suivantes sont utilisées pour configurer la connexion Hydrolix. Ces variables peuvent être fournies via le bloc de configuration MCP (comme indiqué ci-dessus), un fichier .env, ou des variables d'environnement traditionnelles.

Variables requises

Vous DEVEZ définir l'une des suivantes pour identifier le cluster :

• HYDROLIX_URL (recommandé) : L'URL publique canonique de votre cluster Hydrolix, par exemple https://mycluster.hydrolix.live. Pour les déploiements typiques hors cluster, cette seule variable est suffisante — elle fournit l'hôte, le port (défaut du schéma 443/80) et les paramètres TLS pour le point de terminaison de requête HTTP et la sonde REST /version.
• HYDROLIX_HOST (obsolète) : Le nom d'hôte de votre serveur Hydrolix. Toujours honoré pour la rétrocompatibilité mais doit être remplacé par HYDROLIX_URL.

Lorsque HYDROLIX_MCP_SERVER_TRANSPORT est http ou sse, HYDROLIX_URL spécifiquement est requis (un futur point de terminaison de métadonnées OAuth l'annoncerait). HYDROLIX_HOST seul n'est pas suffisant pour ces transports.

Variables d'authentification

Au moins une méthode d'authentification doit être configurée lors de l'utilisation du transport stdio :

• HYDROLIX_TOKEN : Jeton de compte de service pour l'authentification basée sur l'environnement
• HYDROLIX_USER et HYDROLIX_PASSWORD : Nom d'utilisateur et mot de passe pour l'authentification basée sur l'environnement (les deux doivent être fournis ensemble)

En résumé :

• Pour stdio, vous DEVEZ utiliser HYDROLIX_TOKEN ou HYDROLIX_USER+HYDROLIX_PASS (identifiants environnementaux)
• Pour http/sse, vous POUVEZ utiliser HYDROLIX_TOKEN ou HYDROLIX_USER+HYDROLIX_PASS (identifiants environnementaux), mais vous pouvez également utiliser des identifiants par requête.

Si aucun identifiant n'est fourni via l'environnement ou la requête, la requête échouera.

Utilisation de l'authentification par requête avec le transport HTTP

Lors de l'utilisation du transport HTTP ou SSE, vous pouvez omettre les identifiants basés sur l'environnement et fournir à la place une authentification par requête. Cela est utile pour les scénarios multi-utilisateurs ou avec des clients qui ne prennent pas en charge l'exécution de serveurs MCP localement.

Exemple de configuration mcpServers se connectant à un serveur HTTP distant avec authentification par requête :

{
  "mcpServers": {
    "mcp-hydrolix-remote": {
      "url": "https://my-hydrolix-mcp.example.com/mcp?token=<service-account-token>"
    }
  }
}

Exemple de configuration minimale .env pour exécuter votre propre serveur HTTP sans identifiants d'environnement :

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_MCP_SERVER_TRANSPORT=http

Bien que cela ne fasse pas partie de la spécification MCP, de nombreux clients MCP permettent d'ajouter des en-têtes aux requêtes émises par MCP. Lorsque cela est possible, nous recommandons de configurer le client MCP pour transmettre un jeton de compte de service via l'en-tête Authorization: Bearer <sa-token-here> plutôt que comme paramètre de requête pour une plus grande sécurité.

Remarque : Les paramètres d'hôte et de port de liaison ne sont utilisés que lorsque le transport est défini sur « http » ou « sse ».

Variables facultatives

Consultez docs/CONFIG.md pour les remplacements de points de terminaison, les alias de variables obsolètes et l'ensemble complet des variables de réglage facultatives (délais d'attente, remplacements des paramètres SETTINGS de requête, troncature des résultats, réglage des travailleurs HTTP/SSE, proxy, métriques et échappatoires).

Mainteneurs

Les tâches nécessitant des privilèges opérationnels — exécution de la suite complète de bout en bout contre un cluster Hydrolix en production, et préparation d’une version — sont documentées séparément dans MAINTAINERS.md.