Skip to content

MCP Server

The Hydrolix MCP Server enables LLM clients to interact with Hydrolix databases through the Model Context Protocol (MCP). This integration allows language models to query data, explore databases, and analyze information directly from a Hydrolix cluster, letting end users explore their Hydrolix clusters using natural language prompts.

What's the Model Context Protocol

MCP is not the AI application itself, but rather the bridge between the AI application and your data. The AI application handles reasoning and natural language, while the MCP server handles authentication, query execution, and data access.

Choose your deployment mode⚓︎

Hydrolix MCP supports two deployment modes: a remotely hosted MCP server or a local one. Both provide identical capabilities and use the same authentication.

Remote MCP (HTTP/SSE) Local MCP (stdio)
How it runs Server-side in a Hydrolix cluster On a local machine
Installation None. Connect using a URL. Requires Python 3.13+ and the uv package manager
Best for Web-based AI tools, teams that require centralized access Local development
Works with Any client that supports the Model Context Protocol Any client that supports the Model Context Protocol
Available since Hydrolix v5.10 Hydrolix v5.9

Remote MCP (HTTP/SSE)⚓︎

Remote MCP runs in a Hydrolix cluster. No local installation is required. MCP-compatible AI tools connect to the remote MCP server URL using one of two supported transport modes:

  • HTTP: Remote access over HTTP
  • SSE: Server-Sent Events for streaming responses

Quickstart⚓︎

Connect to the MCP server at https://hostname.hydrolix.live/mcp, authenticating with either a service account token (preferred) or basic credentials. See the Authentication section for details.

Remote client configurations⚓︎

Remote Claude Code⚓︎

Configuration

1
claude mcp add --transport http mcp-hydrolix https://hostname.hydrolix.live/mcp --header "Authorization: Bearer {my-api-token}"

1
claude mcp add --transport http mcp-hydrolix https://hostname.hydrolix.live/mcp?token={my-api-token}

If you use query parameter authentication, reconnect to the server using the CLI once per session

Remote ChatGPT Enterprise⚓︎

ChatGPT Enterprise supports HTTP mode only. Follow the instructions in ChatGPT Developer mode, use the URL https://hostname.hydrolix.live/mcp, and provide an authorization token if you are using OAuth or Mixed Authentication modes.

Other HTTP-capable Clients⚓︎

Point any HTTP-capable MCP client at https://hostname.hydrolix.live/mcp and pass your authorization token as in the HTTP Authorization header or ?token= query parameter.

Local MCP (stdio)⚓︎

Local MCP runs as a process on your machine and uses the stdio (Standard input/output) transport mode.

Before you begin⚓︎

Before configuring the Hydrolix MCP Server, ensure you have the following:

Install uv⚓︎

The uv package manager is required to run the Hydrolix MCP Server in the stdio mode. The uvx launcher used in the configuration examples ships with uv. Install it using one of the following methods:

1
curl -LsSf https://astral.sh/uv/install.sh | sh

1
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

1
pip install uv

After installation, verify that uv is available:

Verify uv installation
1
uv --version

For more installation options and details, see the uv documentation.

Environment variables⚓︎

The Hydrolix MCP Server requires certain environment variables to connect to your cluster.

  • Required: HYDROLIX_URL: The canonical public URL of your Hydrolix cluster, for example https://hostname.hydrolix.live (required for all configurations). The deprecated HYDROLIX_HOST variable (hostname only, no scheme) is still honored but should be replaced with HYDROLIX_URL.
  • Optional: Additional configuration options control endpoint overrides, timeouts, query limits, transport method, and server binding preferences. For the complete list, refer to docs/CONFIG.md in the MCP Hydrolix GitHub repository.

Control a local MCP server (stdio) by setting these optional variables in the server's environment. For remote MCP running in a Hydrolix cluster, set the cluster's mcp_hydrolix tunable.

Variable Description Default
HYDROLIX_QUERY_TIMEOUT_SECS Execution timeout for a single query, in seconds. 30
HYDROLIX_MAX_RESULT_CELLS Maximum number of result cells (rows × columns) to return before truncation. 50000
HYDROLIX_MAX_RAW_TIMERANGE Maximum time range, in seconds, for queries against non-summary tables. This limit doesn't apply to summary tables. 21600 (six hours)
HYDROLIX_QUERY_POOL Routes every query to the named query pool by setting the hdx_query_pool_name query option. The named pool must already exist on the cluster. None (the cluster's default query peer pool)
HYDROLIX_QUERY_HEAD_POOL Routes the connection to a query head pool. If the named pool isn't configured on the cluster, the connection falls back to the cluster's default query head pool. None (the cluster's default query head pool)

HYDROLIX_QUERY_POOL selects a query peer pool for each query, while HYDROLIX_QUERY_HEAD_POOL selects a query head pool for the whole connection. Query head pools require Hydrolix version 5.11 or later. On clusters where query head pooling isn't configured, leave HYDROLIX_QUERY_HEAD_POOL unset; a connection routed to a pool that doesn't exist falls back to the cluster's default query head pool.

Certificate trust for the MCP server

When the MCP server connects to a Hydrolix cluster over TLS, it verifies the cluster's certificate against a set of trusted certificate authorities. By default, the server trusts the operating system's certificate store in addition to its default certificate authorities, so it honors certificate authorities installed at the OS level, such as an internal PKI. Set the mcp_hydrolix tunable's truststore_disable attribute to true to ignore the OS certificate store and trust only the default certificate authorities available to the server's Python environment. The attribute defaults to false and is available in Hydrolix v6.1.5 and later.

This attribute controls which certificate authorities the server trusts. It doesn't turn verification off. To disable certificate verification entirely, set HYDROLIX_VERIFY to false.

Local client configurations⚓︎

These configuration examples cover popular MCP clients. Consult your preferred client documentation for specific instructions on how to configure an MCP server.

Local Claude Desktop⚓︎

To configure the MCP server for Claude Desktop, add the following entry to your claude_desktop_config.json file:

Claude Desktop Configuration
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
  }
}

Local Claude Code⚓︎

For Claude Code CLI, use the claude mcp add command to add an MCP server:

1
2
3
claude mcp add --transport http mcp-hydrolix \
  https://hostname.hydrolix.live/mcp --header \
  "Authorization: Bearer {my-api-token}"

1
2
claude mcp add --transport http mcp-hydrolix \
  https://hostname.hydrolix.live/mcp?token={my-api-token}

If you use query parameter authentication, reconnect to the server using the CLI once per session

1
2
3
4
5
claude mcp add --transport stdio mcp-hydrolix \
  --env HYDROLIX_TOKEN={my-api-token} \
  --env HYDROLIX_URL=https://hostname.hydrolix.live \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

Local Cursor IDE⚓︎

To configure the MCP server for Cursor, add the following entry to your Cursor mcp.json settings file:

Cursor MCP Configuration
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
  }
}

Local ChatGPT Enterprise⚓︎

For ChatGPT Enterprise, follow the instructions in ChatGPT Developer mode.

ChatGPT Enterprise only supports HTTP mode

Other clients⚓︎

For other LLM platforms that support MCP integration, follow the client's specific MCP configuration instructions.

The general pattern for stdio mode requires:

  • The uvx command (which ships with uv) as the server executor
  • Arguments that install and launch the package at runtime: --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix
  • Environment variables for HYDROLIX_URL and authentication credentials

Consult the platform's MCP documentation for the exact configuration file location and format.

Authentication⚓︎

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

  1. Header: Per-request authorization token provided by the Authorization: Bearer <my-api-token> header. See Remote Claude Code or Local Claude Code for examples.
  2. Query parameter: Per-request authorization token provided by the ?token=<my-api-token> query parameter. See Remote Claude Code or Local Claude Code for examples.
  3. Environment variables: Basic credentials or an auth token configured using environment variables.
1
export HYDROLIX_TOKEN="my-api-token"

1
2
export HYDROLIX_USER="your-username"
export HYDROLIX_PASSWORD="your-password"

When multiple authentication methods are configured, the server uses the first available method in the precedence order.

Per-request authentication is only available when using HTTP or SSE transport modes

Using a service account token with a read-only role is recommended

Available tools⚓︎

The MCP server provides these tool descriptions to the LLM client.

  • run_select_query: Executes SQL queries
  • list_databases: Displays all databases on the cluster
  • list_tables: Shows tables in a specified database
  • get_table_info: Gets table metadata such as the schema

Usage tips⚓︎

To use the MCP server effectively, follow these best practices to improve query construction.

Take the following basic prompt:

Basic prompt
1
Query logs for all recent errors.

Specify the database and table names clearly in the request.

Prompt with database and table names
1
Query the cdn_request_logs and cdn_edge_logs tables from the logs database for all recent errors.

Include specific time ranges in queries to leverage primary key optimizations.

Prompt with time range
1
Query the cdn_request_logs and cdn_edge_logs tables from the logs database for all errors in the last hour.

Request timestamp-ordered output for better performance.

Final Prompt with ordered output
1
Query the cdn_request_logs and cdn_edge_logs tables from the logs database for all errors in the last hour, ordered by most recent timestamp.

The result is a more efficient query that returns only relevant data.

Reconnect⚓︎

If a session with the MCP server is interrupted, use these steps to reconnect. Use these steps to reconnect a Claude Code client.

  1. Navigate to the Manage MCP servers panel in the client. Select the broken connection to move to the reconnection pane.

    Select the Hydrolix MCP Server connection in the MCP server list

  2. From the reconnection pane, select the Reconnect option.

    1
    Don't select **Authenticate**. This causes the reconnection to fail.

    Initiate a connection attempt using the **Reconnect** option

  3. View the status bar to confirm reconnection success.

    Indication of successful reconnection to the MCP server

Architecture diagrams⚓︎

The MCP server has two deployment models: local (stdio) where it runs on the client machine, and remote (HTTP/SSE) where it runs within the Hydrolix cluster.

Local (stdio)⚓︎

---
config:
  themeVariables:
    fontSize: 30px
---
graph LR
User[User]
LLM[LLM Client]
MCP[Hydrolix MCP Server]
Cluster[Hydrolix Cluster]

    User -->|Prompt| LLM
    LLM -->|"MCP request<br/>(stdio)"| MCP
    MCP -->|SQL Queries| Cluster
    Cluster -->|Query Results| MCP
    MCP -->|Structured Data| LLM
    LLM -->|AI Response| User

    class MCP local
    class Cluster remote

Remote (HTTP/SSE)⚓︎

---
config:
  themeVariables:
    fontSize: 30px
---
graph LR
    User[User]
    LLM[LLM Client]

    subgraph "HydrolixCluster"
        MCP[Hydrolix MCP Server]
        QueryHead[Query Head]
    end

    User -->|Prompt| LLM
    LLM -->|"MCP request<br/>(HTTP/SSE)"| MCP
    MCP -->|SQL Queries| QueryHead
    QueryHead -->|Query Results| MCP
    MCP -->|Structured Data| LLM
    LLM -->|AI Response| User

    style HydrolixCluster fill:transparent,stroke:#666,stroke-width:2px