Hydrolix MCP Server

An MCP server for Hydrolix.

Tools

• run_select_query

  • Execute SQL queries on your Hydrolix cluster.
  • Input: sql (string): The SQL query to execute.

• list_databases

  • List all databases on your Hydrolix cluster.

• list_tables

  • List all tables in a database.
  • Input: database (string): The name of the database.

• get_table_info

  • Get table metadata such as schema
  • Input: database (string): The name of the database.
  • Input: table (string): The name of the table.

Effective Usage

Due to the wide variety in LLM architectures, not all models will proactively use the tools above, and few will use them effectively without guidance, even with the carefully-constructed tool descriptions provided to the model. To get the best results out of your model while using the Hydrolix MCP server, we recommend the following:

• Refer to your Hydrolix database by name and request tool usage in your prompts (e.g., "Using MCP tools to access my Hydrolix database, please ...")
  • This encourages the model to use the MCP tools available and minimizes hallucinations.
• Include time ranges in your prompts (e.g., "Between December 5 2023 and January 18 2024, ...") and specifically request that the output be ordered by timestamp.
  • This prompts the model to write more efficient queries that take advantage of primary key optimizations

Health Check Endpoint

When running with HTTP or SSE transport, a health check endpoint is available at /health. This endpoint:

• Returns 200 OK with the Hydrolix query-head's Clickhouse version if the server is healthy and can connect to Hydrolix
• Returns 503 Service Unavailable if the server cannot connect to the Hydrolix query-head

Example:

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

Configuration

The Hydrolix MCP server is configured using a standard MCP server entry. Consult your client's documentation for specific instructions on where to find or declare MCP servers. An example setup using Claude Desktop is documented below.

The recommended way to launch the Hydrolix MCP server is via the uv project manager, which will manage installing all other dependencies in an isolated environment.

Authentication

The server supports multiple authentication methods with the following precedence (highest to lowest):

1. Per-request Bearer token: Service account token provided via Authorization: Bearer <token> header
2. Per-request GET parameter: Service account token provided via ?token=<token> query parameter
3. Environment-based credentials: Credentials configured via environment variables
   • Service account token (HYDROLIX_TOKEN), or
   • Username and password (HYDROLIX_USER and HYDROLIX_PASSWORD)

When multiple authentication methods are configured, the server will use the first available method in the precedence order above. Per-request authentication is only available when using HTTP or SSE transport modes.

Note: Using a service account token with a readonly role is recommended.

MCP Server definition using username and password (JSON):

{
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp-hydrolix",
    "--python",
    "3.13",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_HOST": "<hydrolix-host>",
    "HYDROLIX_USER": "<hydrolix-user>",
    "HYDROLIX_PASSWORD": "<hydrolix-password>"
  }
}

MCP Server definition using service account token (JSON):

{
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp-hydrolix",
    "--python",
    "3.13",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_HOST": "<hydrolix-host>",
    "HYDROLIX_TO

... [View full README on GitHub](https://github.com/hydrolix/mcp-hydrolix#readme)