Hydrolix

You can use the Hydrolix MCP Server to expose Hydrolix data as an MCP service, enabling secure, remote queries and database exploration from compatible clients. This server translates MCP requests into Hydrolix actions, letting you run read-only SQL queries, list databases, and enumerate tables across your Hydrolix cluster.

How to use

You interact with the Hydrolix MCP Server through a compatible MCP client. Start by choosing an appropriate transport (stdio for local development or http/sse for remote access) and then connect using the configured MCP endpoint. Use the provided tools to perform common data operations: execute SQL queries, list databases, and list tables.

How to install

Prerequisites: you need a runtime to run the MCP server and a way to launch it via your chosen MCP client workflow. The standard path is to run the server using the UV workflow manager, which installs dependencies in an isolated environment.

Step-by-step setup for a local stdio MCP server (direct command shown for clarity): you will run the UV-based command to start the Hydrolix MCP server with the Hydrolix MCP package.

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

Additional configuration and notes

You can connect in two main ways: via service account tokens or via per-request credentials. The system prefers per-request Bearer tokens if provided, then per-request tokens via query parameters, and finally environment-based credentials if needed.

Health checks are available when using HTTP or SSE transport. The health endpoint confirms connectivity to the Hydrolix query-head and reports the ClickHouse version when healthy.

Configuration examples

API-style server definitions are shown in configuration blocks. The following examples illustrate both remote HTTP access and local stdio startup.

# HTTP remote MCP server config (remote URL)
{
  "mcpServers": {
    "hydrolix_remote": {
      "type": "http",
      "url": "https://my-hydrolix-mcp.example.com/mcp?token=<service-account-token>",
      "args": []
    }
  }
}

# Standard IO startup (local, using uv to run the Hydrolix MCP server)
{
  "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>"
  }
}

Environment variables

Configure the Hydrolix connection using environment variables. The host is required, and authentication can be provided via a service account token or a username/password pair. You can also set connection details and transport preferences to tailor security and access.

HYDROLIX_HOST=<hydrolix-host>
HYDROLIX_TOKEN=<service-account-token>           # for per-request or environment-based auth
HYDROLIX_USER=<hydrolix-user>
HYDROLIX_PASSWORD=<hydrolix-password>
HYDROLIX_MCP_SERVER_TRANSPORT=http               # or stdio
HYDROLIX_MCP_BIND_HOST=0.0.0.0
HYDROLIX_MCP_BIND_PORT=4200

Health endpoint

If you run with HTTP or SSE transport, you can check health at /health to verify connectivity to Hydrolix. A healthy response includes the Hydrolix query-head version, while a failure returns a 503.

Available tools

run_select_query

Execute SQL queries on your Hydrolix cluster with read-only queries to ensure safety.

list_databases

List all databases on your Hydrolix cluster.

list_tables

List all tables within a specified database.