Hydrolix

Serveur MCP Hydrolix

Un serveur MCP pour Hydrolix.

Démarrage rapide

Soyez opérationnel 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-les à 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 automatiquement Python et télécharge mcp-hydrolix à la demande, aucune étape d'installation séparée n'est donc 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.

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

[!ASTUCE] 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.

[!REMARQUE] 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 trouver le binaire même s'il est installé. Trouvez le chemin complet et utilisez-le comme valeur de "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 simple 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 ça fonctionne

1. Ouvrez une nouvelle conversation dans Claude Desktop. Cherchez 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 de 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 de l'interface utilisateur, ouvrez la palette de commandes (Cmd+Maj+P / Ctrl+Maj+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 : sql (chaîne) : La requête SQL à exécuter.

• list_databases

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

• list_tables

  • Listez toutes les tables d'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 la table, comme 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 de LLM, tous les modèles n'utiliseront pas les outils ci-dessus de manière proactive, 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 lors de l'utilisation du serveur MCP Hydrolix, nous recommandons ce qui suit :

• Faites référence à 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 ordonné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 l'état

Lors de l'exécution avec le transport HTTP ou SSE, un point de terminaison de vérification de l'état 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é en utilisant une entrée de serveur MCP standard. Consultez la documentation de votre client pour des instructions spécifiques sur l'emplacement 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 priorité 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 priorité ci-dessus. L'authentification par requête n'est disponible que lors de l'utilisation des modes de transport HTTP ou SSE.

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 des 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 lors du 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 variables 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 hors cluster typiques, cette seule variable est suffisante — elle fournit l'hôte, le port (par 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 devrait être remplacé par HYDROLIX_URL.

Lorsque HYDROLIX_MCP_SERVER_TRANSPORT est http ou sse, HYDROLIX_URL est spécifiquement requis (un point de terminaison de métadonnées OAuth à venir 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 plutôt 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. Ceci est utile pour les scénarios multi-utilisateurs ou avec des clients qui ne prennent pas en charge l'exécution locale des serveurs MCP.

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 sécurité accrue.

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 optionnelles

Voir 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 optionnelles (délais d'attente, remplacements de paramètres de requête, troncature des résultats, réglage des workers HTTP/SSE, proxy, métriques et échappatoires).

Mainteneurs

Les tâches qui nécessitent des privilèges opérationnels — exécuter la suite de bout en bout sur un cluster Hydrolix en direct et effectuer une version — sont documentées séparément dans MAINTAINERS.md.