Hydrolix MCP Server

oficial

Integración de datalake de series temporales Hydrolix que proporciona capacidades de exploración de esquemas y consultas para flujos de trabajo basados en LLM.

GitHub

Documentación

Hydrolix MCP Server

Un servidor MCP para Hydrolix.

Inicio rápido

Ponte en marcha en pocos minutos. Esta sección cubre Claude Desktop y Claude Code.

Paso 1 — Requisitos previos

Antes de empezar, asegúrate de tener:

Credenciales de Hydrolix — el nombre de host de tu clúster más un nombre de usuario/contraseña o un token de cuenta de servicio. Si no los tienes, solicítalos a tu administrador de Hydrolix.
Claude Desktop — descárgalo desde claude.ai/download.

Paso 2 — Instalar el servidor MCP

Elige el método que se adapte a tu configuración:

Opción A: Usando uv (recomendado)

uv gestiona Python automáticamente y descarga mcp-hydrolix bajo demanda, por lo que no se necesita un paso de instalación separado. Si no tienes uv, instálalo:

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"

Opción B: Usando pip

Requiere Python 3.13+. Si necesitas instalar Python, descárgalo desde python.org.

pip install mcp-hydrolix

Paso 3 — Configurar Claude Desktop

Abre el archivo de configuración 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
Añade la siguiente entrada al objeto "mcpServers" (crea el archivo con este contenido si aún no existe):

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

Reemplaza <your-hydrolix-hostname>, <your-username> y <your-password> con tus credenciales reales.

[!NOTE] Si usaste la Opción B (pip), utiliza "command": "mcp-hydrolix" sin el campo "args" en su lugar.

[!TIP] Si el archivo ya tiene otras entradas, añade el bloque "mcp-hydrolix" dentro del objeto "mcpServers" existente en lugar de reemplazar todo el archivo.

[!NOTE] Si te autenticas con un token de cuenta de servicio en lugar de nombre de usuario/contraseña, consulta Autenticación.

¿Comando no encontrado?

Claude Desktop se inicia sin el PATH de tu shell, por lo que podría no localizar el binario incluso si está instalado. Encuentra la ruta completa y úsala como el valor de "command" en la configuración.

Opción A (uv): encuentra uvx:

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

Opción B (pip): encuentra mcp-hydrolix:

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

Si which/where.exe no devuelve nada, el binario no está en tu PATH. La solución más limpia es cambiar a la Opción A (uv), que gestiona el entorno Python y el PATH por ti.

Paso 4 — Reiniciar Claude Desktop

Reinicia la aplicación para aplicar la configuración.

Usuarios de macOS / Windows: Asegúrate de cerrar completamente Claude antes de reiniciar. En macOS, presiona Cmd+Q o haz clic derecho en el icono del Dock y elige Salir. En Windows, usa el icono de la bandeja del sistema.

Paso 5 — Verificar que funciona

Abre una nueva conversación en Claude Desktop. Busca un icono de herramientas/martillo cerca de la entrada de texto — esto confirma que el servidor MCP se conectó correctamente.
Prueba este prompt para confirmar que todo funciona:

Usando tus herramientas MCP de Hydrolix, lista las bases de datos disponibles.

Claude debería llamar a la herramienta list_databases y devolver una lista de bases de datos de tu clúster.

¿Prefieres usar Claude Code?

Si prefieres la línea de comandos, asegúrate de que uv esté instalado (Opción A del Paso 2), luego ejecuta:

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

Luego abre Claude Code y pruébalo con el mismo prompt:

Usando tus herramientas MCP de Hydrolix, lista las bases de datos disponibles.

¿Prefieres usar VS Code?

Haz clic en la insignia Instalar en VS Code en la parte superior de este README para una instalación con un solo clic. Si prefieres el flujo de la interfaz de usuario, abre la Paleta de Comandos (Cmd+Shift+P / Ctrl+Shift+P), ejecuta MCP: Agregar servidor, elige Comando (stdio) y reutiliza el comando uvx ... y el bloque env del Paso 3.

Herramientas

run_select_query
- Ejecuta consultas SQL en tu clúster de Hydrolix.
- Entrada: sql (string): La consulta SQL a ejecutar.
list_databases
- Lista todas las bases de datos en tu clúster de Hydrolix.
list_tables
- Lista todas las tablas en una base de datos.
- Entrada: database (string): El nombre de la base de datos.
get_table_info
- Obtiene metadatos de la tabla como el esquema
- Entrada: database (string): El nombre de la base de datos.
- Entrada: table (string): El nombre de la tabla.

Uso efectivo

Debido a la amplia variedad en arquitecturas de LLM, no todos los modelos usarán proactivamente las herramientas anteriores, y pocos las usarán eficazmente sin orientación, incluso con las descripciones de herramientas cuidadosamente construidas proporcionadas al modelo. Para obtener los mejores resultados de tu modelo al usar el servidor MCP de Hydrolix, recomendamos lo siguiente:

Refiérete a tu base de datos Hydrolix por su nombre y solicita el uso de herramientas en tus prompts (por ejemplo, "Usando herramientas MCP para acceder a mi base de datos Hydrolix, por favor ...")
- Esto anima al modelo a usar las herramientas MCP disponibles y minimiza las alucinaciones.
Incluye rangos de tiempo en tus prompts (por ejemplo, "Entre el 5 de diciembre de 2023 y el 18 de enero de 2024, ...") y solicita específicamente que la salida se ordene por marca de tiempo.
- Esto incita al modelo a escribir consultas más eficientes que aprovechan las optimizaciones de clave primaria

Endpoint de verificación de estado

Cuando se ejecuta con transporte HTTP o SSE, un endpoint de verificación de estado está disponible en /health. Este endpoint:

Devuelve 200 OK con la versión de Clickhouse del query-head de Hydrolix si el servidor está saludable y puede conectarse a Hydrolix
Devuelve 503 Service Unavailable si el servidor no puede conectarse al query-head de Hydrolix

Ejemplo:

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

Configuración

El servidor MCP de Hydrolix se configura usando una entrada de servidor MCP estándar. Consulta la documentación de tu cliente para obtener instrucciones específicas sobre dónde encontrar o declarar servidores MCP. A continuación se documenta un ejemplo de configuración usando Claude Desktop.

La forma recomendada de iniciar el servidor MCP de Hydrolix es a través del gestor de proyectos uv, que gestionará la instalación de todas las demás dependencias en un entorno aislado.

Autenticación

El servidor soporta múltiples métodos de autenticación con la siguiente precedencia (de mayor a menor):

Token Bearer por solicitud: Token de cuenta de servicio proporcionado a través del encabezado Authorization: Bearer <token>
Parámetro GET por solicitud: Token de cuenta de servicio proporcionado a través del parámetro de consulta ?token=<token>
Credenciales basadas en entorno: Credenciales configuradas a través de variables de entorno
- Token de cuenta de servicio (HYDROLIX_TOKEN), o
- Nombre de usuario y contraseña (HYDROLIX_USER y HYDROLIX_PASSWORD)

Cuando se configuran múltiples métodos de autenticación, el servidor usará el primer método disponible en el orden de precedencia anterior. La autenticación por solicitud solo está disponible cuando se usan modos de transporte HTTP o SSE.

Nota: Se recomienda usar un token de cuenta de servicio con un rol de solo lectura.

Definición del servidor MCP usando nombre de usuario y contraseña (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>"
  }
}

Definición del servidor MCP usando token de cuenta de servicio (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>"
  }
}

Definición del servidor MCP usando nombre de usuario y contraseña (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>

Definición del servidor MCP usando token de cuenta de servicio (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>

Ejemplo de configuración (Claude Desktop)

Abre el archivo de configuración de Claude Desktop ubicado en:
- En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- En Windows: %APPDATA%/Claude/claude_desktop_config.json
Añade una entrada de servidor mcp-hydrolix al bloque de configuración mcpServers para usar nombre de usuario y contraseña:

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

Para aprovechar la cuenta de servicio, usa el siguiente bloque de configuración:

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

Actualiza las definiciones de variables de entorno para que apunten a tu clúster de Hydrolix.
(Recomendado) Localiza la entrada de comando para uvx y reemplázala con la ruta absoluta al ejecutable uvx. Esto asegura que se use la versión correcta de uvx al iniciar el servidor. Puedes encontrar esta ruta usando which uvx o where.exe uvx.
Reinicia Claude Desktop para aplicar los cambios. Si estás usando Windows, asegúrate de que Claude se detenga por completo cerrando el cliente usando el icono de la bandeja del sistema.

Ejemplo de configuración (Claude Code)

Para configurar el servidor MCP de Hydrolix para Claude Code, ejecuta el siguiente comando:

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 de entorno

Las siguientes variables se utilizan para configurar la conexión a Hydrolix. Estas variables pueden proporcionarse a través del bloque de configuración MCP (como se muestra arriba), un archivo .env o variables de entorno tradicionales.

Variables requeridas

DEBES establecer una de las siguientes para identificar el clúster:

HYDROLIX_URL (recomendado): La URL pública canónica de tu clúster Hydrolix, por ejemplo, https://mycluster.hydrolix.live. Para despliegues típicos fuera del clúster, esta única variable es suficiente — proporciona el host, puerto (predeterminado del esquema 443/80) y configuración TLS tanto para el endpoint de consulta HTTP como para la sonda REST /version.
HYDROLIX_HOST (obsoleto): El nombre de host de tu servidor Hydrolix. Aún se respeta por compatibilidad con versiones anteriores, pero debe reemplazarse por HYDROLIX_URL.

Cuando HYDROLIX_MCP_SERVER_TRANSPORT es http o sse, HYDROLIX_URL específicamente es requerido (el endpoint de metadatos OAuth lo anuncia). HYDROLIX_HOST por sí solo no es suficiente para estos transportes.

Anulaciones de endpoint

Estas anulan los valores derivados de HYDROLIX_URL. Son útiles para despliegues dentro del clúster donde el endpoint de consulta HTTP y la API de versión residen en diferentes nombres de host o puertos internos. Precedencia de anulación: nueva variable explícita > alias obsoleto > derivado de HYDROLIX_URL > predeterminado fijo.

HYDROLIX_HTTP_QUERY_HOST / HYDROLIX_HTTP_QUERY_PORT / HYDROLIX_HTTP_QUERY_SECURE: anulan el endpoint de consulta HTTP de ClickHouse.
HYDROLIX_VERSION_API_HOST / HYDROLIX_VERSION_API_PORT / HYDROLIX_VERSION_API_SECURE: anulan el endpoint de sonda REST /version. HYDROLIX_VERSION_API_SECURE hereda del valor seguro de consulta HTTP resuelto por defecto.

Variables obsoletas

Las siguientes aún se respetan durante la ventana de transición, pero se eliminarán en una versión futura. Migra cuando te sea conveniente:

Obsoleto	Reemplazo
`HYDROLIX_HOST`	`HYDROLIX_URL` (preferido) o `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`

Los operadores externos que utilicen cualquiera de estas verán una advertencia única al inicio aconsejando la migración a HYDROLIX_URL. Los despliegues dentro del clúster (gestionados por o6r) no verán esta advertencia; su migración es manejada por la plataforma.

Variables de autenticación

Se debe configurar al menos un método de autenticación cuando se usa el transporte stdio:

HYDROLIX_TOKEN: Token de cuenta de servicio para autenticación basada en entorno
HYDROLIX_USER y HYDROLIX_PASSWORD: Nombre de usuario y contraseña para autenticación basada en entorno (ambos deben proporcionarse juntos)

En resumen:

Para stdio, DEBES usar HYDROLIX_TOKEN o HYDROLIX_USER+HYDROLIX_PASS (credenciales de entorno)
Para http/sse, PUEDES usar HYDROLIX_TOKEN o HYDROLIX_USER+HYDROLIX_PASS (credenciales de entorno), pero en su lugar puedes usar credenciales por solicitud.

Si no se proporcionan credenciales a través del entorno o la solicitud, la solicitud fallará.

Variables opcionales

HYDROLIX_VERIFY: Activar/desactivar la verificación del certificado SSL
- Predeterminado: "true"
- Establecer en "false" para desactivar la verificación del certificado (no recomendado para producción)
HYDROLIX_DATABASE: Base de datos predeterminada a utilizar
- Predeterminado: Ninguno (usa el predeterminado del servidor)
- Establecer esto para conectarse automáticamente a una base de datos específica
HYDROLIX_MCP_SERVER_TRANSPORT: Establece el método de transporte para el servidor MCP.
- Predeterminado: "stdio"
- Opciones válidas: "stdio", "http", "sse". Esto es útil para el desarrollo local con herramientas como MCP Inspector.
HYDROLIX_MCP_BIND_HOST: Host al que vincular el servidor MCP cuando se usa transporte HTTP o SSE
- Predeterminado: "127.0.0.1"
- Establecer en "0.0.0.0" para vincular a todas las interfaces de red (útil para Docker o acceso remoto)
- Solo se usa cuando el transporte es "http" o "sse"
HYDROLIX_MCP_BIND_PORT: Puerto al que vincular el servidor MCP cuando se usa transporte HTTP o SSE
- Predeterminado: "8000"
- Solo se usa cuando el transporte es "http" o "sse"
HYDROLIX_MAX_RAW_TIMERANGE: Rango de tiempo máximo en segundos permitido para consultas contra tablas no resumidas
- Predeterminado: 21600 (6 horas)
- Las consultas dirigidas a tablas resumidas no se ven afectadas por este límite

Para MCP Inspector o acceso remoto con transporte 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)

Al usar transporte HTTP, el servidor se ejecutará en el puerto configurado (predeterminado 8000). Por ejemplo, con la configuración anterior:

Endpoint MCP: http://localhost:4200/mcp
Verificación de estado: http://localhost:4200/health

Uso de autenticación por solicitud con transporte HTTP

Al usar transporte HTTP o SSE, puede omitir las credenciales basadas en entorno y en su lugar proporcionar autenticación por solicitud. Esto es útil para escenarios multiusuario o con clientes que no admiten ejecutar servidores MCP localmente.

Ejemplo de configuración de mcpServers para conectarse a un servidor HTTP remoto con autenticación por solicitud:

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

Ejemplo de configuración mínima de .env para ejecutar su propio servidor HTTP sin credenciales de entorno:

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

Aunque no forma parte de la especificación MCP, muchos clientes MCP permiten agregar encabezados a las solicitudes emitidas por MCP. Cuando esto es posible, recomendamos configurar el cliente MCP para pasar un token de cuenta de servicio a través del encabezado Authorization: Bearer <sa-token-here> en lugar de como un parámetro de consulta para mayor seguridad.

Nota: La configuración de host y puerto de vinculación solo se usa cuando el transporte se establece en "http" o "sse".

Pruebas de extremo a extremo

Un conjunto separado bajo tests/e2e/ despliega el árbol de trabajo local en un clúster Hydrolix Kubernetes activo y realiza pruebas de humo de las herramientas MCP contra el pod en ejecución. Está excluido de las ejecuciones de prueba predeterminadas y del hook pre-push; ejecutarlo requiere una inclusión explícita a través del marcador pytest end_to_end más credenciales. Consulte tests/e2e/README.md para el manual de procedimientos.