Hydrolix

Servidor MCP Hydrolix

Um servidor MCP para Hydrolix.

Início Rápido

Comece a usar em poucos minutos. Esta seção cobre o Claude Desktop e o Claude Code.

Etapa 1 — Pré-requisitos

Antes de começar, certifique-se de ter:

• Credenciais Hydrolix — o hostname do seu cluster, além de um nome de usuário/senha ou um token de conta de serviço. Se você não tiver essas informações, pergunte ao administrador do Hydrolix.
• Claude Desktop — baixe em claude.ai/download.

Etapa 2 — Instale o servidor MCP

Escolha o método que corresponde à sua configuração:

Opção A: Usando uv (recomendado)

uv gerencia o Python automaticamente e baixa o mcp-hydrolix sob demanda, portanto não é necessária uma etapa de instalação separada. Se você não tiver o uv, instale-o:

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"

Opção B: Usando pip

Requer Python 3.13+. Se você precisar instalar o Python, baixe-o em python.org.

pip install mcp-hydrolix

Etapa 3 — Configure o Claude Desktop

1. Abra o arquivo de configuração do Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Adicione a seguinte entrada ao objeto "mcpServers" (crie o arquivo com este conteúdo se ele ainda não existir):

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

Substitua <your-hydrolix-hostname>, <your-username> e <your-password> pelas suas credenciais reais.

[!NOTE] Se você usou a Opção B (pip), use "command": "mcp-hydrolix" sem o campo "args".

[!TIP] Se o arquivo já tiver outras entradas, adicione o bloco "mcp-hydrolix" dentro do objeto "mcpServers" existente, em vez de substituir o arquivo inteiro.

[!NOTE] Se você autenticar com um token de conta de serviço em vez de nome de usuário/senha, consulte Autenticação.

Comando não encontrado?

O Claude Desktop é iniciado sem o PATH do seu shell, então pode não localizar o binário mesmo que ele esteja instalado. Encontre o caminho completo e use-o como o valor de "command" na configuração.

Opção A (uv): encontre uvx:

• macOS / Linux: which uvx
• Windows: where.exe uvx

Opção B (pip): encontre mcp-hydrolix:

• macOS / Linux: which mcp-hydrolix
• Windows: where.exe mcp-hydrolix

Se which/where.exe não retornar nada, o binário não está no seu PATH. A correção mais limpa é mudar para a Opção A (uv), que gerencia o ambiente Python e o PATH para você.

Etapa 4 — Reinicie o Claude Desktop

Reinicie o aplicativo para aplicar a configuração.

Usuários de macOS / Windows: Certifique-se de sair completamente do Claude antes de reiniciar. No macOS, pressione Cmd+Q ou clique com o botão direito no ícone do Dock e escolha Sair. No Windows, use o ícone da bandeja do sistema.

Etapa 5 — Verifique se está funcionando

1. Abra uma nova conversa no Claude Desktop. Procure um ícone de ferramentas/martelo próximo ao campo de texto — isso confirma que o servidor MCP conectou com sucesso.

2. Experimente este prompt para confirmar que tudo está funcionando:

   Usando suas ferramentas MCP Hydrolix, liste os bancos de dados disponíveis.

O Claude deve chamar a ferramenta list_databases e retornar uma lista de bancos de dados do seu cluster.

---

Prefere usar o Claude Code?

Se você preferir a linha de comando, certifique-se de que o uv esteja instalado (Opção A da Etapa 2) e execute:

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

Em seguida, abra o Claude Code e teste com o mesmo prompt:

Usando suas ferramentas MCP Hydrolix, liste os bancos de dados disponíveis.

Prefere usar o VS Code?

Clique no selo Instalar no VS Code no topo deste README para uma instalação com um clique. Se preferir o fluxo pela interface, abra a Paleta de Comandos (Cmd+Shift+P / Ctrl+Shift+P), execute MCP: Adicionar Servidor, escolha Comando (stdio) e reutilize o comando uvx ... e o bloco env da Etapa 3.

Ferramentas

• run_select_query

  • Execute consultas SQL no seu cluster Hydrolix.
  • Entrada: query (string): A consulta SQL a ser executada.
  • Entrada: max_cells (inteiro, opcional): Orçamento de células de resultado (linhas × colunas); quando o servidor define um limite, o chamador só pode reduzi-lo.
  • Entrada: purpose (string, obrigatório): Por que a consulta está sendo executada; registrado com a consulta como hdx_query_comment.
  • Uma cláusula FORMAT final é removida; o servidor seleciona o formato de transmissão.

• list_databases

  • Liste todos os bancos de dados no seu cluster Hydrolix.

• list_tables

  • Liste todas as tabelas em um banco de dados.
  • Entrada: database (string): O nome do banco de dados.

• get_table_info

  • Obtenha metadados da tabela, como esquema.
  • Entrada: database (string): O nome do banco de dados.
  • Entrada: table (string): O nome da tabela.

Uso Eficaz

Devido à grande variedade de arquiteturas de LLM, nem todos os modelos usarão proativamente as ferramentas acima, e poucos as usarão de forma eficaz sem orientação, mesmo com as descrições de ferramentas cuidadosamente construídas fornecidas ao modelo. Para obter os melhores resultados do seu modelo ao usar o servidor MCP Hydrolix, recomendamos o seguinte:

• Refira-se ao seu banco de dados Hydrolix pelo nome e solicite o uso das ferramentas em seus prompts (por exemplo, "Usando ferramentas MCP para acessar meu banco de dados Hydrolix, por favor...")
  • Isso incentiva o modelo a usar as ferramentas MCP disponíveis e minimiza alucinações.
• Inclua intervalos de tempo em seus prompts (por exemplo, "Entre 5 de dezembro de 2023 e 18 de janeiro de 2024, ...") e solicite especificamente que a saída seja ordenada por timestamp.
  • Isso leva o modelo a escrever consultas mais eficientes que aproveitam otimizações de chave primária.

Endpoint de Verificação de Saúde

Ao executar com transporte HTTP ou SSE, um endpoint de verificação de saúde está disponível em /health. Este endpoint:

• Retorna 200 OK com a versão do Clickhouse do query-head Hydrolix se o servidor estiver saudável e puder se conectar ao Hydrolix
• Retorna 503 Service Unavailable se o servidor não puder se conectar ao query-head Hydrolix

Exemplo:

curl http://localhost:8000/health
# Response: OK - Connected to Hydrolix compatible with ClickHouse 24.3.1

Configuração

O servidor MCP Hydrolix é configurado usando uma entrada padrão de servidor MCP. Consulte a documentação do seu cliente para obter instruções específicas sobre onde encontrar ou declarar servidores MCP. Um exemplo de configuração usando Claude Desktop está documentado abaixo.

A maneira recomendada de iniciar o servidor MCP Hydrolix é através do gerenciador de projetos uv, que gerenciará a instalação de todas as outras dependências em um ambiente isolado.

Autenticação

O servidor suporta vários métodos de autenticação com a seguinte precedência (da maior para a menor):

1. Token Bearer por solicitação: Token de conta de serviço fornecido via cabeçalho Authorization: Bearer <token>
2. Parâmetro GET por solicitação: Token de conta de serviço fornecido via parâmetro de consulta ?token=<token>
3. Credenciais baseadas em ambiente: Credenciais configuradas via variáveis de ambiente
   • Token de conta de serviço (HYDROLIX_TOKEN), ou
   • Nome de usuário e senha (HYDROLIX_USER e HYDROLIX_PASSWORD)

Quando vários métodos de autenticação estão configurados, o servidor usará o primeiro método disponível na ordem de precedência acima. A autenticação por solicitação só está disponível ao usar modos de transporte HTTP ou SSE. A forma ?token= existe para clientes que não podem enviar cabeçalhos; defina HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false em implantações onde cada cliente envia o cabeçalho Authorization (consulte Credenciais por solicitação).

Nota: O uso de um token de conta de serviço com função somente leitura é recomendado.

Definição do servidor MCP usando nome de usuário e senha (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>"
  }
}

Definição do servidor MCP usando token de conta de serviço (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>"
  }
}

Definição do servidor MCP usando nome de usuário e senha (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>

Definição do servidor MCP usando token de conta de serviço (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>

Exemplo de Configuração (Claude Desktop)

1. Abra o arquivo de configuração do Claude Desktop localizado em:

   • No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • No Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Adicione uma entrada de servidor mcp-hydrolix ao bloco de configuração mcpServers para usar nome de usuário e senha:

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

Para aproveitar a conta de serviço, use o seguinte bloco de configuração:

{
  "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. Atualize as definições de variáveis de ambiente para apontar para o seu cluster Hydrolix.

4. (Recomendado) Localize a entrada de comando para uvx e substitua-a pelo caminho absoluto para o executável uvx. Isso garante que a versão correta de uvx seja usada ao iniciar o servidor. Você pode encontrar esse caminho usando which uvx ou where.exe uvx.

5. Reinicie o Claude Desktop para aplicar as alterações. Se você estiver usando Windows, certifique-se de que o Claude esteja completamente parado, fechando o cliente usando o ícone da bandeja do sistema.

Exemplo de Configuração (Claude Code)

Para configurar o servidor MCP Hydrolix para Claude Code, execute o seguinte comando:

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

Variáveis de Ambiente

As seguintes variáveis são usadas para configurar a conexão Hydrolix. Essas variáveis podem ser fornecidas via bloco de configuração MCP (como mostrado acima), um arquivo .env ou variáveis de ambiente tradicionais.

Variáveis Obrigatórias

Você DEVE definir uma das seguintes opções para identificar o cluster:

• HYDROLIX_URL (recomendado): A URL pública canônica do seu cluster Hydrolix, por exemplo, https://mycluster.hydrolix.live. Para implantações típicas fora do cluster, esta única variável é suficiente — ela fornece o host, a porta (padrão do esquema 443/80) e as configurações de TLS para o endpoint de consulta HTTP e a sonda REST /version.
• HYDROLIX_HOST (obsoleto): O hostname do seu servidor Hydrolix. Ainda é respeitado para compatibilidade reversa, mas deve ser substituído por HYDROLIX_URL.

Quando HYDROLIX_MCP_SERVER_TRANSPORT é http ou sse, HYDROLIX_URL especificamente é obrigatório (um futuro endpoint de metadados OAuth o anunciaria). HYDROLIX_HOST sozinho não é suficiente para esses transportes.

Variáveis de Autenticação

Pelo menos um método de autenticação deve ser configurado ao usar o transporte stdio:

• HYDROLIX_TOKEN: Token de conta de serviço para autenticação baseada em ambiente
• HYDROLIX_USER e HYDROLIX_PASSWORD: Nome de usuário e senha para autenticação baseada em ambiente (ambos devem ser fornecidos juntos)

Em resumo:

• Para stdio, você DEVE usar HYDROLIX_TOKEN ou HYDROLIX_USER+HYDROLIX_PASS (credenciais ambientais)
• Para http/sse, você PODE usar HYDROLIX_TOKEN ou HYDROLIX_USER+HYDROLIX_PASS (credenciais ambientais), mas pode usar credenciais por solicitação.

Se nenhuma credencial for fornecida via ambiente ou solicitação, a solicitação falhará.

Usando Autenticação por Solicitação com Transporte HTTP

Ao usar transporte HTTP ou SSE, você pode omitir credenciais baseadas em ambiente e, em vez disso, fornecer autenticação por solicitação. Isso é útil para cenários multiusuário ou com clientes que não suportam executar servidores MCP localmente.

Exemplo de configuração mcpServers conectando-se a um servidor HTTP remoto com autenticação por solicitação:

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

Exemplo de configuração mínima .env para executar seu próprio servidor HTTP sem credenciais de ambiente:

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

Embora não faça parte da especificação MCP, muitos clientes MCP permitem adicionar cabeçalhos às solicitações emitidas pelo MCP. Quando isso for possível, recomendamos configurar o cliente MCP para passar um token de conta de serviço via cabeçalho Authorization: Bearer <sa-token-here> em vez de como parâmetro de consulta, para maior segurança.

Nota: As configurações de host e porta de vinculação são usadas apenas quando o transporte está definido como "http" ou "sse".

Variáveis Opcionais

Consulte docs/CONFIG.md para substituições de endpoint, aliases de variáveis obsoletos e o conjunto completo de variáveis de ajuste opcionais (timeouts, substituições de configurações de consulta, truncamento de resultados, ajuste de workers HTTP/SSE, proxy, métricas e escape hatches).

Mantenedores

Tarefas que exigem privilégios operacionais — executar o conjunto completo de testes contra um cluster Hydrolix ativo e fazer um release — estão documentadas separadamente em MAINTAINERS.md.