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 via 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 supporeds 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.ai⚓︎

Open Claude.ai and go to Settings → Integrations
Add a new MCP server with URL: https://hostname.hydrolix.live/mcp
Provide your auth token when prompted

Remote Claude Code⚓︎

Configuration

Header authentication (recommended)Query parameter authentication

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}`

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 auth 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 auth token as an 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:

Python 3.13 or later
uv package manager
Set the environment variables
Authentication credentials (API token or username/password)

Installing uv⚓︎

The uv package manager is required to run the Hydrolix MCP Server in the stdio mode. Install it using one of the following methods:

Install uv via curlInstall via pip

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

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_HOST: The hostname of your Hydrolix cluster (required for all configurations).
Optional: Additional configuration options control port settings, SSL verification, default database, transport method, and server binding preferences. Refer to the MCP Hydrolix GitHub repository for the complete list of optional variables.

Local client configurations⚓︎

Below are configuration examples for 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
{
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp-hydrolix",
    "--python",
    "3.13",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_HOST": "<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:

HTTP: Header AuthHTTP: Query Parameter AuthStdio: Environment Variable Auth

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}`

claude mcp add --transport stdio mcp-hydrolix \
  --env HYDROLIX_TOKEN={my-api-token} \
  --env HYDROLIX_HOST=hostname.hydrolix.live \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uv run --with mcp-hydrolix --python 3.13 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
{
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp-hydrolix",
    "--python",
    "3.13",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_HOST": "<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 uv command as the server executor
Arguments pointing to the mcp-hydrolix installation directory
Environment variables for HYDROLIX_HOST 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):

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

Token Authentication by Environment VariableBasic Authentication by Environment Variable

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 above.

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 with read-only protections
list_databases: Displays all databases on the cluster
list_tables: Shows tables within 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.

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