Skip to main content
Glama
deenesjakoruzh
hydrolix

mcp-hydrolix

Official
by hydrolix
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Hydrolix MCP Server

PyPI - Version Install in VS Code Install in VS Code Insiders

An MCP server for Hydrolix.

Quickstart

Get up and running in a few minutes. This section covers Claude Desktop and Claude Code.

Step 1 — Prerequisites

Before you begin, make sure you have:

  • Hydrolix credentials — your cluster hostname plus either a username/password or a service account token. If you don't have these, ask your Hydrolix administrator.

  • Claude Desktop — download from claude.ai/download.

Step 2 — Install the MCP server

Choose the method that matches your setup:

Option A: Using uv (recommended)

uv manages Python automatically and downloads mcp-hydrolix on demand, so no separate install step is needed. If you don't have uv, install it:

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: Using pip

Requires Python 3.13+. If you need to install Python, download it from python.org.

pip install mcp-hydrolix

Step 3 — Configure Claude Desktop

  1. Open the Claude Desktop configuration file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. Add the following entry to the "mcpServers" object (create the file with this content if it doesn't exist yet):

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

Replace <your-hydrolix-hostname>, <your-username>, and <your-password> with your actual credentials.

NOTE

If you used Option B (pip), use"command": "mcp-hydrolix" with no "args" field instead.

TIP

If the file already has other entries, add the"mcp-hydrolix" block inside the existing "mcpServers" object rather than replacing the whole file.

NOTE

If you authenticate with a service account token instead of username/password, seeAuthentication.

Claude Desktop launches without your shell's PATH, so it may not locate the binary even if it is installed. Find the full path and use it as the "command" value in the config.

Option A (uv): find uvx:

  • macOS / Linux: which uvx

  • Windows: where.exe uvx

Option B (pip): find mcp-hydrolix:

  • macOS / Linux: which mcp-hydrolix

  • Windows: where.exe mcp-hydrolix

If which/where.exe returns nothing, the binary isn't on your PATH. The cleanest fix is to switch to Option A (uv), which manages the Python environment and PATH for you.

Step 4 — Restart Claude Desktop

Restart the app to apply the configuration.

macOS / Windows users: Make sure to fully quit Claude before restarting. On macOS, press Cmd+Q or right-click the Dock icon and choose Quit. On Windows, use the system tray icon.

Step 5 — Verify it's working

  1. Open a new conversation in Claude Desktop. Look for a tools/hammer icon near the text input — this confirms the MCP server connected successfully.

  2. Try this prompt to confirm everything is working:

    Using your Hydrolix MCP tools, list the available databases.

Claude should call the list_databases tool and return a list of databases from your cluster.

Using Claude Code instead?

If you prefer the command line, make sure uv is installed (Option A from Step 2), then run:

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

Then open Claude Code and test with the same prompt:

Using your Hydrolix MCP tools, list the available databases.

Using VS Code instead?

Click the Install in VS Code badge at the top of this README for a one-click install. If you prefer the UI flow, open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P), run MCP: Add Server, choose Command (stdio), and reuse the uvx ... command and env block from Step 3.

Related MCP server: buildkite-mcp-server

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.

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

MCP Server definition using service account token (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>"
  }
}

MCP Server definition using username and password (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>

MCP Server definition using service account token (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>

Configuration Example (Claude Desktop)

  1. Open the Claude Desktop configuration file located at:

    • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • On Windows: %APPDATA%/Claude/claude_desktop_config.json

  2. Add a mcp-hydrolix server entry to the mcpServers config block to use username and password:

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

To leverage service account use the following config block:

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

  1. Update the environment variable definitions to point to your Hydrolix cluster.

  2. (Recommended) Locate the command entry for uvx and replace it with the absolute path to the uvx executable. This ensures that the correct version of uvx is used when starting the server. You can find this path using which uvx or where.exe uvx.

  3. Restart Claude Desktop to apply the changes. If you are using Windows, ensure Claude is stopped completely by closing the client using the system tray icon.

Configuration Example (Claude Code)

To configure the Hydrolix MCP server for Claude Code, run the following command:

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

Environment Variables

The following variables are used to configure the Hydrolix connection. These variables may be provided via the MCP config block (as shown above), a .env file, or traditional environment variables.

Required Variables

You MUST set one of the following to identify the cluster:

  • HYDROLIX_URL (recommended): The canonical public URL of your Hydrolix cluster, e.g. https://mycluster.hydrolix.live. For typical out-of-cluster deployments this single variable is sufficient — it supplies the host, port (scheme-default 443/80), and TLS settings for both the HTTP query endpoint and the REST /version probe.

  • HYDROLIX_HOST (deprecated): The hostname of your Hydrolix server. Still honored for backwards compatibility but should be replaced by HYDROLIX_URL.

When HYDROLIX_MCP_SERVER_TRANSPORT is http or sse, HYDROLIX_URL specifically is required (a forthcoming OAuth metadata endpoint would advertise it). HYDROLIX_HOST alone is not sufficient for these transports.

Authentication Variables

At least one authentication method must be configured when using the stdio transport:

  • HYDROLIX_TOKEN: Service account token for environment-based authentication

  • HYDROLIX_USER and HYDROLIX_PASSWORD: Username and password for environment-based authentication (both must be provided together)

In summary:

  • For stdio, you MUST use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials)

  • For http/sse, you MAY use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials), but you may instead use per-request credentials.

If no credentials are provided via the environment or the request, the request will fail.

Using Per-Request Authentication with HTTP Transport

When using HTTP or SSE transport, you can omit environment-based credentials and instead provide authentication per-request. This is useful for multi-user scenarios or with clients that don't support running MCP servers locally.

Example mcpServers configuration connecting to a remote HTTP server with per-request authentication:

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

Example minimal .env configuration for running your own HTTP server without environment credentials:

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

Though not part of the MCP specification, many MCP clients allow adding headers to MCP-issued requests. When this is possible, we recommend configuring the MCP client to pass a service account token via the Authorization: Bearer <sa-token-here> header instead of as a query parameter for greater security.

Note: The bind host and port settings are only used when transport is set to "http" or "sse".

Optional Variables

See docs/CONFIG.md for endpoint overrides, deprecated variable aliases, and the full set of optional tuning variables (timeouts, query SETTINGS overrides, result truncation, HTTP/SSE worker tuning, proxy, metrics, and escape hatches).

Maintainers

Tasks that need operational privileges — running the end-to-end suite against a live Hydrolix cluster, and cutting a release — are documented separately in MAINTAINERS.md.

Available Tools

4 tools
get_table_infoGet Table InfoA
Read-onlyIdempotent

Get detailed metadata for a specific table including columns and summary table detection.

REQUIRED USAGE: Call this tool BEFORE querying ANY table to check if it's a summary table and get column metadata. This is mandatory to avoid query errors.

This tool provides:

  • is_summary_table: Boolean indicating if table has pre-aggregated data

  • columns: List of column objects, each with a column_category field:

    • column_category='Column': plain dimension column

    • column_category='AliasColumn': non-aggregate ALIAS column, has default_expr

    • column_category='AggregateColumn': AggregateFunction/SimpleAggregateFunction type, has base_function and merge_function

    • column_category='SummaryColumn': ALIAS column that transitively depends on aggregates, has default_expr

  • summary_table_info: Human-readable description for summary tables

  • total_rows, total_bytes: Table statistics

WORKFLOW for querying tables:

  1. Call get_table_info('database', 'table_name')

  2. Check is_summary_table field

  3. If is_summary_table=True:

    • Read column_category and merge_function for each column

    • Use merge_function to wrap aggregate columns in queries

    • Example: SELECT countMerge(count(vendor_id)) FROM table

  4. If is_summary_table=False:

    • Use standard SQL (SELECT count(*), sum(col), etc.)

  5. Execute query with run_select_query

For summary tables, aggregate columns MUST be wrapped with their corresponding -Merge functions from the merge_function field. Querying without checking this metadata first will cause errors.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
databaseYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral details like column categories (Column, AliasColumn, AggregateColumn, SummaryColumn), merge_function usage, and the distinction between summary and non-summary tables, which beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose, bullet points for return fields, and a numbered workflow. However, it is slightly verbose, repeating the workflow in both narrative and list form. Front-loaded with the essential usage instruction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the lack of parameter descriptions, the description fully covers the tool's purpose, return fields (including column categories and merge_function), and the complete workflow for using the tool alongside run_select_query. Given the output schema exists, return values are adequately explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has two required parameters (database, table) with no descriptions (0% coverage). The description only mentions 'Call get_table_info('database', 'table_name')' but does not define what database or table mean, leaving the agent to infer from context. This is insufficient compensation for the missing schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get detailed metadata for a specific table including columns and summary table detection.' It uses a specific verb ('Get') and resource ('table metadata'), and the sibling tools (list_databases, list_tables, run_select_query) are distinct, so there is no confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly mandates 'Call this tool BEFORE querying ANY table' and provides a numbered workflow detailing when and how to use it. It also implicitly guides when not to use it (after metadata is obtained) by linking to run_select_query.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_databasesList DatabasesA
Read-onlyIdempotent

List available Hydrolix databases

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
databasesYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds no further behavioral context (e.g., filtering, sorting, output format), so it neither adds nor contradicts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, highly efficient sentence that front-loads the core purpose. No extraneous information is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, rich annotations, output schema available), the description is sufficient. It clearly states what the tool does, and the return values are documented externally.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters and 100% schema coverage, the baseline is 4. The description does not need to add parameter details, as the schema already fully documents the empty parameter set.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'List available Hydrolix databases' uses a specific verb and resource, clearly differentiating from siblings like list_tables and get_table_info that operate at the table level.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives. Usage is implied by the name and sibling context, but no when-not or alternative suggestions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tablesList TablesA
Read-onlyIdempotent

List all tables in a database for exploration and discovery.

Use this tool to:

  • Discover what tables exist in a database

  • Filter tables by name pattern (like/not_like)

  • Get basic table metadata (name, engine, row counts, sizes, primary keys)

Returns basic table information WITHOUT column details for performance. Tables are returned with empty columns lists and is_summary_table not set.

IMPORTANT: Always call get_table_info(database, table) before querying a specific table. Column metadata (types, categories, merge functions) is required to build correct queries, especially for summary tables which need special -Merge function syntax. list_tables() is intentionally lightweight to avoid loading schema for all tables at once.

ParametersJSON Schema
NameRequiredDescriptionDefault
likeNo
databaseYes
not_likeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
tablesYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that the tool returns basic table info WITHOUT column details, with empty columns lists and is_summary_table not set, and explains the performance rationale. There is no contradiction between description and annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, well-structured with a lead sentence, bullet points, and an important note. It front-loads the purpose and uses efficient language without redundancy. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity, existence of output schema, and annotations, the description is complete. It explains what the tool returns and what it deliberately omits (column details, is_summary_table), and provides guidance on next steps (get_table_info). This suffices for an agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description needs to compensate. It explains the 'database' parameter and that 'like' and 'not_like' are for pattern filtering. However, it does not specify the exact pattern format (e.g., SQL LIKE syntax), which would be helpful. Overall, it adds meaning beyond the schema but could be slightly more precise.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists tables in a database for exploration and discovery. It specifies the verb 'list', the resource 'tables', and the context 'in a database'. It differentiates from siblings by noting it is lightweight and that column details are intentionally omitted, with a reference to get_table_info for more detail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use the tool: to discover tables, filter by name pattern, and get basic metadata. It gives an 'IMPORTANT' instruction to call get_table_info before querying a specific table, and explains that this tool is intentionally lightweight to avoid loading schema, thus guiding the agent to alternative tools when needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_select_queryRun SELECT QueryA
Read-onlyIdempotent

Run a SELECT query in a Hydrolix time-series database using the Clickhouse SQL dialect. Queries run using this tool will timeout after 30 seconds.

FULLY-QUALIFIED TABLE NAMES:

Every table reference MUST be fully qualified as database.table (e.g. FROM my_db.my_table). The connection has no default database, so an unqualified table name will fail to resolve.

RESULT TRUNCATION:

Query results are automatically truncated when the total cell count (rows * columns) exceeds the configured limit.

Response shape: - Always present: columns, rows, truncated (bool), row_count - Only when truncated=true: total_row_count, message Note: total_row_count is the number of rows fetched from the server, which is capped at 100,000. The actual table may contain more rows than this value suggests.

Note: if the cell limit is smaller than the number of columns, row_count will be 0 — in that case you must either refine the query (fewer columns, stricter filters) or increase max_cells.

MANDATORY PRE-QUERY CHECK:

Before running ANY query, call get_table_info(database, table_name) if you haven't already. Check is_summary_table and read column metadata (column_category, merge_function per column). If is_summary_table=True: follow summary_table_info from get_table_info response and rules below. If is_summary_table=False: use standard SQL (count, sum, avg, etc.).

The primary key on tables queried this way is always a timestamp. Queries should include either a LIMIT clause or a filter based on the primary key as a performance guard to ensure they return in a reasonable amount of time. Queries should select specific fields and avoid the use of SELECT * to avoid performance issues. The performance guard used for the query should be clearly communicated with the user, and the user should be informed that the query may take a long time to run if the performance guard is not used. When choosing a performance guard, the user's preference should be requested and used if available. When using aggregations, the performance guard should take form of a primary key filter, or else the LIMIT should be applied in a subquery before applying the aggregations.

When matching columns based on substrings, prefix or suffix matches should be used instead of full-text search whenever possible. When searching for substrings, the syntax column LIKE '%suffix' or column LIKE 'prefix%' should be used.

SUMMARY TABLE RULES (if is_summary_table=True):

Use column_category from get_table_info to determine column usage — do NOT infer from names.

  1. column_category='AggregateColumn': MUST be wrapped in its merge_function

    • Stores binary AggregateFunction state — direct SELECT causes deserialization errors

    • Use exact merge_function from column metadata (do NOT infer from column name)

    • count(vendor_id) → countMerge(count(vendor_id)), countIf(c) → countIfMerge(countIf(c))

    • Always use backticks for column names with special characters

  2. column_category='SummaryColumn': select directly, no wrapping

    • ALIAS that wraps -Merge internally — NEVER wrap in sum()/count()/avg() (ILLEGAL_AGGREGATION)

    • Per-row value — for grand totals use the corresponding AggregateColumn + merge_function

  3. column_category='Column'/'AliasColumn': dimension columns, use as-is

    • Many have function-like names (e.g., toStartOfMinute(dt)) — LITERAL names, not expressions

    • WRONG: SELECT toStartOfMinute(dt) RIGHT: SELECT toStartOfMinute(dt)

    • For time filters: use '2022-06-01' or '2022-06-01 00:00:00' — NOT partial '2022-06-01 00:00'

    • Use >= and < for ranges: WHERE col >= '2022-06-01' AND col < '2022-06-02'

  4. GROUP BY: required when SELECT mixes dimension columns with aggregates

    • Only Column/AliasColumn go in GROUP BY — never AggregateColumn or SummaryColumn

  5. NEVER use SELECT * on summary tables (causes deserialization errors)

Summary table query patterns (after calling get_table_info first):

Pattern 1: Aggregate entire table -- First: get_table_info('database', 'summary_table') -- Read column.merge_function for count(column_name) = "countMerge" SELECT countMerge(count(column_name)) as total FROM database.summary_table

Pattern 2: Aggregate with grouping by dimension and optional time range filter -- First: get_table_info('database', 'summary_table') -- Read merge_function for each aggregate column SELECT toStartOfMinute(datetime_field) as time_bucket, countMerge(count(column_name)) as total, avgMerge(avg(other_column)) as avg_value FROM database.summary_table WHERE toStartOfMinute(datetime_field) >= '2022-06-01' AND toStartOfMinute(datetime_field) < '2022-06-02' GROUP BY toStartOfMinute(datetime_field) ORDER BY time_bucket DESC

Pattern 3: Multiple aggregates (no dimensions, no GROUP BY) -- First: get_table_info('database', 'summary_table') SELECT countMerge(count(column_name)) as count_result, sumMerge(sum(other_column)) as sum_result FROM database.summary_table

Pattern 4: Using column_category='SummaryColumn' -- First: get_table_info('database', 'summary_table') -- SummaryColumns are per-row values — use with GROUP BY to break down by dimension SELECT cdn, cnt_all, sum_bytes FROM database.summary_table GROUP BY cdn -- No -Merge needed, these are pre-defined aliases -- For a grand total across all rows, use AggregateColumn + merge_function instead: SELECT countMerge(count()) AS grand_total FROM database.summary_table

Pattern 5: Using dimensions with function-like names (common pattern) -- First: get_table_info('database', 'summary_table') -- Dimension column named: toStartOfMinute(primary_datetime) — LITERAL name, not an expression -- WRONG: SELECT toStartOfMinute(primary_datetime) ... (tries to call function) -- RIGHT: Use the literal column name with backticks SELECT toStartOfMinute(primary_datetime) as time_bucket, countMerge(count()) as cnt, maxMerge(max(value)) as max_val FROM database.summary_table GROUP BY toStartOfMinute(primary_datetime) ORDER BY time_bucket DESC LIMIT 10

Regular table examples (non-summary):

Example query. Purpose: get logs from the application.logs table. Primary key: timestamp. Performance guard: 10 minute recency filter.

SELECT message, timestamp FROM application.logs WHERE timestamp > now() - INTERVAL 10 MINUTES

Example query. Purpose: get the median humidity from the weather.measurements table. Primary key: date. Performance guard: 1000 row limit, applied before aggregation.

SELECT median(humidity) FROM (SELECT humidity FROM weather.measurements LIMIT 1000)

Example query. Purpose: get the lowest temperature from the weather.measurements table over the last 10 years. Primary key: date. Performance guard: date range filter.

SELECT min(temperature) FROM weather.measurements WHERE date > now() - INTERVAL 10 YEARS

Example query. Purpose: get the app name with the most log messages from the application.logs table in the window between new year and valentine's day of 2024. Primary key: timestamp. Performance guard: date range filter. SELECT app, count(*) FROM application.logs WHERE timestamp > '2024-01-01' AND timestamp < '2024-02-14' GROUP BY app ORDER BY count(*) DESC LIMIT 1

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
max_cellsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint, destructiveHint), the description discloses critical behaviors: a 30-second timeout, result truncation when cell count exceeds a limit, and the exact response shape with conditions. It explains edge cases like row_count=0 and the meaning of total_row_count. This transparency ensures the agent understands the tool's operational characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but well-structured with clear sections (output shape, pre-query check, summary table rules, examples). It is front-loaded with the core purpose. While every sentence adds value given the tool's complexity, some redundancy exists (e.g., repeating the pre-query check in examples). Slightly more conciseness would elevate it, but overall it is efficient for the domain.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the presence of an output schema (though not shown), and the 0% parameter description coverage, the description covers all necessary aspects: input format, output shape, error conditions, dependencies (get_table_info), performance best practices, and detailed syntax rules for summary tables. It leaves no significant gaps for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema has no parameter descriptions (0% coverage), the description adds substantial meaning. For the required 'query' parameter, it specifies valid SQL dialect, required table naming format, and syntax examples. For 'max_cells', it explains truncation behavior and how to handle row_count=0. The extensive query patterns and examples compensate for the lack of formal schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Run a SELECT query in a Hydrolix time-series database using the Clickhouse SQL dialect.' This specific verb+resource combination, along with the mention of Clickhouse dialect and Hydrolix database, distinguishes it from sibling tools like get_table_info or list_databases, which handle metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance, including a mandatory pre-query check (call get_table_info first), performance guard requirements (LIMIT or primary key filter), and detailed rules for summary vs. regular tables. It also suggests when to use substring matching and warns against SELECT *. This comprehensive guidance helps the agent decide when and how to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.3.2
    • Addedget_table_info
    • Changedlist_databases3 fields changed
      • addedInput schema / additionalProperties
        Added value: +false
      • removedInput schema / title
        Removed value: -"list_databasesArguments"
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "description": "Result of `list_databases` — wraps a list of database names so the\nstructured payload is a JSON object (as MCP requires) with an explicit\nfield name instead of fastmcp's generic `result` wrapper.",
+  "properties": {
+    "databases": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "databases"
+  ],
+  "type": "object"
+}
    • Changedlist_tables8 fields changed
      • addedInput schema / additionalProperties
        Added value: +false
      • removedInput schema / properties / database / title
        Removed value: -"Database"
      • addedInput schema / properties / like / anyOf
        Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
      • removedInput schema / properties / like / title
        Removed value: -"Like"
      • removedInput schema / properties / like / type
        Removed value: -"string"
      • addedInput schema / properties / not_like
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
      • removedInput schema / title
        Removed value: -"list_tablesArguments"
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "description": "Result of `list_tables` — wraps a list of tables so the structured\npayload is a JSON object (as MCP requires) with an explicit field name\ninstead of fastmcp's generic `result` wrapper.",
+  "properties": {
+    "tables": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "tables"
+  ],
+  "type": "object"
+}
    • Changedrun_select_query5 fields changed
      • addedInput schema / additionalProperties
        Added value: +false
      • addedInput schema / properties / max_cells
        Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
      • removedInput schema / properties / query / title
        Removed value: -"Query"
      • removedInput schema / title
        Removed value: -"run_select_queryArguments"
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "type": "object"
+}
  2. 3 tool updatesv1.0.0
    • First observedlist_databases
    • First observedlist_tables
    • First observedrun_select_query
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct purpose: get_table_info provides metadata, list_databases and list_tables handle discovery, and run_select_query executes queries. There is no functional overlap.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (get_table_info, list_databases, list_tables, run_select_query), making the API predictable.

Tool Count5/5

With 4 tools, the server is well-scoped for its purpose: database exploration and querying. Each tool is necessary and none are redundant.

Completeness4/5

The tool surface covers the essential workflow (discover databases/tables, inspect schema, execute queries). Minor gaps include lack of write/administrative operations, but these are likely out of scope.

Maintenance

ActivityNo data
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers