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.

Passo 1 — Pré-requisitos

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

• Credenciais Hydrolix — o hostname do seu cluster mais um nome de usuário/senha ou um token de conta de serviço. Se não os tiver, peça ao seu administrador Hydrolix.
• Claude Desktop — baixe em claude.ai/download.

Passo 2 — Instalar 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, então nenhuma etapa de instalação separada é necessária. Se você não tem 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 precisar instalar o Python, baixe-o em python.org.

pip install mcp-hydrolix

Passo 3 — Configurar 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, veja 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 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 solução mais simples é mudar para a Opção A (uv), que gerencia o ambiente Python e o PATH para você.

Passo 4 — Reiniciar o Claude Desktop

Reinicie o aplicativo para aplicar a configuração.

Usuários de macOS / Windows: Certifique-se de fechar completamente o 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.

Passo 5 — Verificar se está funcionando

1. Abra uma nova conversa no Claude Desktop. Procure um ícone de ferramentas/martelo perto da entrada 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 do 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ê prefere a linha de comando, certifique-se de que o uv está instalado (Opção A do Passo 2), então 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 do 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 da 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 do Passo 3.

Ferramentas

• run_select_query

  • Execute consultas SQL no seu cluster Hydrolix.
  • Entrada: sql (string): A consulta SQL a ser executada.

• 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 eficazmente 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 de ferramentas em seus prompts (ex.: "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 (ex.: "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 as 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 Clickhouse do query-head do 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 do 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 instruções específicas sobre onde encontrar ou declarar servidores MCP. Um exemplo de configuração usando o 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 requisição: Token de conta de serviço fornecido via cabeçalho Authorization: Bearer <token>
2. Parâmetro GET por requisiçã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 são configurados, o servidor usará o primeiro método disponível na ordem de precedência acima. A autenticação por requisição só está disponível ao usar os modos de transporte HTTP ou SSE.

Nota: Recomenda-se usar um token de conta de serviço com uma função somente leitura.

Definição de 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 de 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 de 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 de 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 usar conta de serviço, utilize 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 das 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 do uvx seja usada ao iniciar o servidor. Você pode encontrar este caminho usando which uvx ou where.exe uvx.

5. Reinicie o Claude Desktop para aplicar as alterações. Se estiver usando Windows, certifique-se de que o Claude seja completamente interrompido fechando o cliente através do ícone da bandeja do sistema.

Exemplo de Configuração (Claude Code)

Para configurar o servidor MCP Hydrolix para o 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 através do 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 para identificar o cluster:

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

Quando HYDROLIX_MCP_SERVER_TRANSPORT é http ou sse, HYDROLIX_URL especificamente é obrigatório (um endpoint de metadados OAuth futuro 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 de ambiente)
• Para http/sse, você PODE usar HYDROLIX_TOKEN ou HYDROLIX_USER+HYDROLIX_PASS (credenciais de ambiente), mas pode, em vez disso, usar credenciais por requisição.

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

Usando Autenticação por Requisiçã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 requisição. Isso é útil para cenários multiusuário ou com clientes que não suportam a execução de servidores MCP localmente.

Exemplo de configuração mcpServers conectando-se a um servidor HTTP remoto com autenticação por requisiçã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 requisiçõ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 um parâmetro de consulta para maior segurança.

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

Variáveis Opcionais

Veja docs/CONFIG.md para substituições de endpoint, aliases de variáveis obsoletas e o conjunto completo de variáveis de ajuste opcionais (timeouts, substituições de SETTINGS de consulta, truncamento de resultados, ajuste de worker HTTP/SSE, proxy, métricas e válvulas de escape).

Mantenedores

Tarefas que precisam de privilégios operacionais — executar a suíte ponta a ponta contra um cluster Hydrolix ativo e lançar uma versão — são documentadas separadamente em MAINTAINERS.md.