run_select_queryLABSCO SUMMARY
SQL against Hydrolix, with the schema discovery to aim it.
list_databases, list_tables and get_table_info let an agent map the cluster before writing a query, which is where the failed attempts otherwise go. Hydrolix's own advice is a service account token with a read-only role — the grants on that token are the real boundary, not the tool list.
What it is
Hydrolix's own server for its log-analytics clusters. Four tools over one cluster connection: the databases it holds, the tables inside them, one table's schema, and a SQL query of your own.
What you get
- Every database on the cluster — list_databases
- The tables in a database — list_tables
- One table's metadata, schema included — get_table_info
- A SQL query executed against the cluster — run_select_query
- A /health endpoint under HTTP or SSE transport, returning the query head's ClickHouse version, or 503 when the cluster cannot be reached
Requirements
HYDROLIX_URL pointing at your cluster, plus credentials: either HYDROLIX_TOKEN, a service account token, or HYDROLIX_USER and HYDROLIX_PASSWORD together. Ships on PyPI as mcp-hydrolix 0.3.6 and runs under Python 3.13, usually launched through uvx. Under HTTP or SSE the token can instead travel per request, as a bearer header or a ?token= parameter.
Setup effort
One command plus credentials — pip install mcp-hydrolix, then supply credentials
USE CASES
01
Finding your way around an unfamiliar cluster
List the databases, then the tables in the one you care about, then read the schema — three calls before a single query is written.
02
Answering a question about recent logs
Name the database in the prompt and include a time range; the primary key optimisation only helps when the query carries one.
03
Confirming the connection before you debug the query
Under HTTP or SSE transport, /health returns the ClickHouse version the query head is compatible with, or 503 when the cluster is unreachable.
4 tools
Listed in project docs. Your client may show a different list.
list_databaseslist_tablesget_table_infoBEFORE YOU INSTALL
What to know first
Tools you get
4 tools named in the project's documentation.
Requires
- Python 3.13+
- HYDROLIX_URL pointing at your cluster
- HYDROLIX_TOKEN, or HYDROLIX_USER and HYDROLIX_PASSWORD together
INSTALLATION
Connect your client
Server setup
TERMINAL
pip install mcp-hydrolixMCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add --transport stdio hydrolix --env HYDROLIX_URL=https://<YOUR_HYDROLIX_HOSTNAME> --env HYDROLIX_USER=<YOUR_HYDROLIX_USER> --env HYDROLIX_PASSWORD=<YOUR_HYDROLIX_PASSWORD> --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolixAuthenticate with either HYDROLIX_TOKEN (a service account token) or HYDROLIX_USER and HYDROLIX_PASSWORD together. A server you run yourself over HTTP can instead take the token with each request, as ?token= in the URL or an Authorization: Bearer header.
VS Code, VS Code Insiders
JSON
{
"inputs": [
{
"id": "hydrolix_url",
"type": "promptString",
"description": "Hydrolix URL (e.g. https://mycluster.hydrolix.live)"
},
{
"id": "hydrolix_user",
"type": "promptString",
"description": "Hydrolix username"
},
{
"id": "hydrolix_password",
"type": "promptString",
"description": "Hydrolix password",
"password": true
}
],
"servers": {
"mcp-hydrolix": {
"type": "stdio",
"command": "uvx",
"args": [
"--python",
"3.13",
"--refresh-package",
"mcp-hydrolix",
"mcp-hydrolix"
],
"env": {
"HYDROLIX_URL": "${input:hydrolix_url}",
"HYDROLIX_USER": "${input:hydrolix_user}",
"HYDROLIX_PASSWORD": "${input:hydrolix_password}"
}
}
}
}VS Code asks for the Hydrolix URL, username and password the first time it starts the server.
Authenticate with either HYDROLIX_TOKEN (a service account token) or HYDROLIX_USER and HYDROLIX_PASSWORD together. A server you run yourself over HTTP can instead take the token with each request, as ?token= in the URL or an Authorization: Bearer header.
Any MCP client — remote HTTP
This connects to an mcp-hydrolix server you run yourself with HYDROLIX_MCP_SERVER_TRANSPORT=http and HYDROLIX_URL set. <YOUR_HYDROLIX_HOST> is that server's address and <YOUR_TOKEN> a Hydrolix service account token (a read-only role is recommended):
ANY MCP CLIENT — REMOTE HTTP · JSON
{
"mcpServers": {
"mcp-hydrolix-remote": {
"url": "<YOUR_HYDROLIX_URL>/mcp?token=<YOUR_TOKEN>"
}
}
}Authenticate with either HYDROLIX_TOKEN (a service account token) or HYDROLIX_USER and HYDROLIX_PASSWORD together. A server you run yourself over HTTP can instead take the token with each request, as ?token= in the URL or an Authorization: Bearer header.
