Hydrolix

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

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.

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

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, see Authentication.

<details>
<summary><strong>Command not found?</strong></summary>

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.

</details>

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.
- This prompts the model to write more efficient queries that take advantage of primary key optimizations

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>

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

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

4. (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.

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

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

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.

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.

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