Skip to content

MCP Server

The Hydrolix MCP Server enables Claude and other 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.

Overview⚓︎

The MCP Server provides a standardized interface for AI assistants to access Hydrolix data. When configured, LLMs such as Claude by Anthropic can execute queries, discover available databases and tables, and help analyze data through natural language interactions.

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

Transport modes⚓︎

The MCP Server supports three transport modes.

  • stdio (default): Standard input/output for local communication
  • HTTP: Remote access through HTTP protocol
  • SSE: Server-Sent Events for streaming responses

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

Before you begin⚓︎

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

Authentication⚓︎

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

  1. Header: Per-request auth token provided by the Authorization: Bearer <my-api-token> header. See Claude Code for an example.
  2. Query parameter: Per-request auth token provided by the ?token=<my-api-token> query parameter. See Claude Code for an example.
  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 above.

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

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:

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.

Configuration⚓︎

The Hydrolix MCP Server requires certain environment variables to connect to your cluster. Once configured, it can be used with any client that supports the Model Context Protocol.

Environment variables⚓︎

Required⚓︎

HYDROLIX_HOST: The hostname of your Hydrolix cluster (required for all configurations).

Set Hydrolix Host
1
export HYDROLIX_HOST="{myhost}.hydrolix.live"

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.

Client configuration examples⚓︎

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

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
15
16
17
{
  "mcpServers": {
    "hydrolix": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-hydrolix",
        "run",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_HOST": "{myhost}.hydrolix.live",
        "HYDROLIX_TOKEN": "my-api-token"
      }
    }
  }
}

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://{myhost}.hydrolix.live/mcp --header \
  "Authorization: Bearer {my-api-token}"

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

1
2
3
4
5
claude mcp add --transport stdio mcp-hydrolix \
  --env HYDROLIX_TOKEN={my-api-token} \
  --env HYDROLIX_HOST={myhost}.hydrolix.live \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uv run --with mcp-hydrolix --python 3.13 mcp-hydrolix

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
15
16
17
{
  "mcpServers": {
    "hydrolix": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-hydrolix",
        "run",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_HOST": "{myhost}.hydrolix.live",
        "HYDROLIX_TOKEN": "my-api-token"
      }
    }
  }
}

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.

Usage⚓︎

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.