Hydrolix MCP Server

officiel

Intégration du datalake de séries temporelles Hydrolix offrant des capacités d'exploration de schéma et de requête pour les workflows basés sur LLM.

GitHub

Documentation

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 Python automatiquement 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

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
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 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 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 cela fonctionne

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.
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 horaires 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 santé

Lors de l'exécution avec le 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 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) :

Jeton Bearer par requête : Jeton de compte de service fourni via l'en-tête Authorization: Bearer <token>
Paramètre GET par requête : Jeton de compte de service fourni via le paramètre de requête ?token=<token>
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)

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

Mettez à jour les définitions des variables d'environnement pour pointer vers votre cluster Hydrolix.
(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.
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 spécifiquement est requis (le point de terminaison des métadonnées OAuth l'annonce). HYDROLIX_HOST seul n'est pas suffisant pour ces transports.

Remplacements de point de terminaison

Ceux-ci remplacent les valeurs dérivées de HYDROLIX_URL. Ils sont utiles pour les déploiements en cluster où le point de terminaison de requête HTTP et l'API de version résident à des noms d'hôte ou ports internes différents. Priorité de remplacement : nouvelle variable explicite > alias obsolète > dérivé de HYDROLIX_URL > valeur par défaut codée en dur.

HYDROLIX_HTTP_QUERY_HOST / HYDROLIX_HTTP_QUERY_PORT / HYDROLIX_HTTP_QUERY_SECURE : remplacent le point de terminaison de requête HTTP ClickHouse.
HYDROLIX_VERSION_API_HOST / HYDROLIX_VERSION_API_PORT / HYDROLIX_VERSION_API_SECURE : remplacent le point de terminaison de la sonde REST /version. HYDROLIX_VERSION_API_SECURE hérite de la valeur sécurisée de la requête HTTP résolue par défaut.

Variables obsolètes

Les variables suivantes sont toujours honorées pendant la fenêtre de transition mais seront supprimées dans une version future. Migrez à votre convenance :

Obsolète	Remplacement
`HYDROLIX_HOST`	`HYDROLIX_URL` (préféré) ou `HYDROLIX_HTTP_QUERY_HOST`
`HYDROLIX_PORT`	`HYDROLIX_HTTP_QUERY_PORT`
`HYDROLIX_SECURE`	`HYDROLIX_HTTP_QUERY_SECURE`
`HYDROLIX_API_HOST`	`HYDROLIX_VERSION_API_HOST`
`HYDROLIX_API_PORT`	`HYDROLIX_VERSION_API_PORT`

Les opérateurs externes utilisant l'une de ces variables verront un avertissement unique au démarrage conseillant la migration vers HYDROLIX_URL. Les déploiements en cluster (gérés par o6r) ne verront pas cet avertissement ; leur migration est gérée par la plateforme.

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.

Variables optionnelles

HYDROLIX_VERIFY : Activer/désactiver la vérification du certificat SSL
- Par défaut : "true"
- Mettre à "false" pour désactiver la vérification du certificat (non recommandé en production)
HYDROLIX_DATABASE : Base de données par défaut à utiliser
- Par défaut : Aucune (utilise la valeur par défaut du serveur)
- Définissez cette variable pour vous connecter automatiquement à une base de données spécifique
HYDROLIX_MCP_SERVER_TRANSPORT : Définit la méthode de transport pour le serveur MCP.
- Par défaut : "stdio"
- Options valides : "stdio", "http", "sse". Utile pour le développement local avec des outils comme MCP Inspector.
HYDROLIX_MCP_BIND_HOST : Hôte auquel lier le serveur MCP lors de l'utilisation du transport HTTP ou SSE
- Par défaut : "127.0.0.1"
- Mettre à "0.0.0.0" pour lier à toutes les interfaces réseau (utile pour Docker ou l'accès distant)
- Utilisé uniquement lorsque le transport est "http" ou "sse"
HYDROLIX_MCP_BIND_PORT : Port auquel lier le serveur MCP lors de l'utilisation du transport HTTP ou SSE
- Par défaut : "8000"
- Utilisé uniquement lorsque le transport est "http" ou "sse"
HYDROLIX_MAX_RAW_TIMERANGE : Plage de temps maximale en secondes autorisée pour les requêtes sur les tables non résumées
- Par défaut : 21600 (6 heures)
- Les requêtes ciblant les tables résumées ne sont pas affectées par cette limite

Pour MCP Inspector ou l'accès distant avec le transport HTTP :

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_USER=default
HYDROLIX_PASSWORD=myPassword
HYDROLIX_MCP_SERVER_TRANSPORT=http
HYDROLIX_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
HYDROLIX_MCP_BIND_PORT=4200  # Custom port (default: 8000)

Lors de l'utilisation du transport HTTP, le serveur s'exécutera sur le port configuré (par défaut 8000). Par exemple, avec la configuration ci-dessus :

Point de terminaison MCP : http://localhost:4200/mcp
Vérification de l'état : http://localhost:4200/health

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

Lors de l'utilisation du transport HTTP ou SSE, vous pouvez omettre les informations d'identification basées sur l'environnement et fournir à la place une authentification par requête. Cela est utile pour les scénarios multi-utilisateurs ou avec les 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 informations d'identification 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 sont utilisés uniquement lorsque le transport est défini sur « http » ou « sse ».

Tests de bout en bout

Une suite distincte sous tests/e2e/ déploie l'arbre de travail local vers un cluster Kubernetes Hydrolix en direct et effectue des tests de fumée des outils MCP sur le pod en cours d'exécution. Elle est exclue des exécutions de test par défaut et du hook de pré-push ; son exécution nécessite une adhésion explicite via le marqueur pytest end_to_end ainsi que des informations d'identification. Voir tests/e2e/README.md pour le manuel d'exécution.