Hydrolix MCP Server

resmi

Integrasi datalake deret waktu Hydrolix yang menyediakan eksplorasi skema dan kemampuan kueri untuk alur kerja berbasis LLM.

GitHub

Dokumentasi

Server MCP Hydrolix

Server MCP untuk Hydrolix.

Mulai Cepat

Mulai dan berjalan dalam beberapa menit. Bagian ini mencakup Claude Desktop dan Claude Code.

Langkah 1 — Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Kredensial Hydrolix — nama host klaster Anda beserta nama pengguna/kata sandi atau token akun layanan. Jika belum memilikinya, tanyakan kepada administrator Hydrolix Anda.
Claude Desktop — unduh dari claude.ai/download.

Langkah 2 — Instal server MCP

Pilih metode yang sesuai dengan pengaturan Anda:

Opsi A: Menggunakan uv (disarankan)

uv mengelola Python secara otomatis dan mengunduh mcp-hydrolix sesuai permintaan, sehingga tidak diperlukan langkah instalasi terpisah. Jika belum memiliki uv, instal:

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"

Opsi B: Menggunakan pip

Membutuhkan Python 3.13+. Jika perlu menginstal Python, unduh dari python.org.

pip install mcp-hydrolix

Langkah 3 — Konfigurasi Claude Desktop

Buka file konfigurasi 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
Tambahkan entri berikut ke objek "mcpServers" (buat file dengan konten ini jika belum ada):

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

Ganti <your-hydrolix-hostname>, <your-username>, dan <your-password> dengan kredensial Anda yang sebenarnya.

[!CATATAN] Jika Anda menggunakan Opsi B (pip), gunakan "command": "mcp-hydrolix" tanpa bidang "args".

[!TIP] Jika file sudah memiliki entri lain, tambahkan blok "mcp-hydrolix" di dalam objek "mcpServers" yang sudah ada, bukan mengganti seluruh file.

[!CATATAN] Jika Anda mengautentikasi dengan token akun layanan alih-alih nama pengguna/kata sandi, lihat Autentikasi.

Perintah tidak ditemukan?

Claude Desktop diluncurkan tanpa PATH shell Anda, sehingga mungkin tidak menemukan biner meskipun sudah terinstal. Temukan path lengkapnya dan gunakan sebagai nilai "command" di konfigurasi.

Opsi A (uv): temukan uvx:

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

Opsi B (pip): temukan mcp-hydrolix:

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

Jika which/where.exe tidak menghasilkan apa pun, biner tidak ada di PATH Anda. Solusi terbaik adalah beralih ke Opsi A (uv), yang mengelola lingkungan Python dan PATH untuk Anda.

Langkah 4 — Mulai ulang Claude Desktop

Mulai ulang aplikasi untuk menerapkan konfigurasi.

Pengguna macOS / Windows: Pastikan untuk menutup Claude sepenuhnya sebelum memulai ulang. Di macOS, tekan Cmd+Q atau klik kanan ikon Dock dan pilih Quit. Di Windows, gunakan ikon baki sistem.

Langkah 5 — Verifikasi berfungsi

Buka percakapan baru di Claude Desktop. Cari ikon palu/alat di dekat input teks — ini menandakan server MCP berhasil terhubung.
Coba prompt ini untuk memastikan semuanya berfungsi:

Menggunakan alat MCP Hydrolix Anda, daftarkan basis data yang tersedia.

Claude seharusnya memanggil alat list_databases dan mengembalikan daftar basis data dari klaster Anda.

Lebih suka menggunakan Claude Code?

Jika lebih suka baris perintah, pastikan uv terinstal (Opsi A dari Langkah 2), lalu jalankan:

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

Kemudian buka Claude Code dan uji dengan prompt yang sama:

Menggunakan alat MCP Hydrolix Anda, daftarkan basis data yang tersedia.

Lebih suka menggunakan VS Code?

Klik lencana Install in VS Code di bagian atas README ini untuk instalasi sekali klik. Jika lebih suka alur UI, buka Command Palette (Cmd+Shift+P / Ctrl+Shift+P), jalankan MCP: Add Server, pilih Command (stdio), dan gunakan kembali perintah uvx ... dan blok env dari Langkah 3.

Alat

run_select_query
- Jalankan kueri SQL di klaster Hydrolix Anda.
- Input: sql (string): Kueri SQL yang akan dijalankan.
list_databases
- Daftarkan semua basis data di klaster Hydrolix Anda.
list_tables
- Daftarkan semua tabel dalam basis data.
- Input: database (string): Nama basis data.
get_table_info
- Dapatkan metadata tabel seperti skema
- Input: database (string): Nama basis data.
- Input: table (string): Nama tabel.

Penggunaan Efektif

Karena beragamnya arsitektur LLM, tidak semua model akan secara proaktif menggunakan alat di atas, dan sedikit yang akan menggunakannya secara efektif tanpa panduan, bahkan dengan deskripsi alat yang disusun dengan cermat yang diberikan kepada model. Untuk mendapatkan hasil terbaik dari model Anda saat menggunakan server MCP Hydrolix, kami sarankan hal berikut:

Rujuk basis data Hydrolix Anda berdasarkan nama dan minta penggunaan alat dalam prompt Anda (mis., "Menggunakan alat MCP untuk mengakses basis data Hydrolix saya, mohon ...")
- Ini mendorong model untuk menggunakan alat MCP yang tersedia dan meminimalkan halusinasi.
Sertakan rentang waktu dalam prompt Anda (mis., "Antara 5 Desember 2023 dan 18 Januari 2024, ...") dan secara khusus minta agar output diurutkan berdasarkan stempel waktu.
- Ini mendorong model untuk menulis kueri yang lebih efisien yang memanfaatkan optimasi kunci utama

Endpoint Pemeriksaan Kesehatan

Saat berjalan dengan transport HTTP atau SSE, endpoint pemeriksaan kesehatan tersedia di /health. Endpoint ini:

Mengembalikan 200 OK dengan versi Clickhouse query-head Hydrolix jika server sehat dan dapat terhubung ke Hydrolix
Mengembalikan 503 Service Unavailable jika server tidak dapat terhubung ke query-head Hydrolix

Contoh:

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

Konfigurasi

Server MCP Hydrolix dikonfigurasi menggunakan entri server MCP standar. Lihat dokumentasi klien Anda untuk instruksi spesifik tentang di mana menemukan atau mendeklarasikan server MCP. Contoh pengaturan menggunakan Claude Desktop didokumentasikan di bawah.

Cara yang disarankan untuk meluncurkan server MCP Hydrolix adalah melalui manajer proyek uv, yang akan mengelola instalasi semua dependensi lain dalam lingkungan terisolasi.

Autentikasi

Server mendukung beberapa metode autentikasi dengan prioritas berikut (tertinggi ke terendah):

Token Bearer per-permintaan: Token akun layanan yang disediakan melalui header Authorization: Bearer <token>
Parameter GET per-permintaan: Token akun layanan yang disediakan melalui parameter kueri ?token=<token>
Kredensial berbasis lingkungan: Kredensial yang dikonfigurasi melalui variabel lingkungan
- Token akun layanan (HYDROLIX_TOKEN), atau
- Nama pengguna dan kata sandi (HYDROLIX_USER dan HYDROLIX_PASSWORD)

Ketika beberapa metode autentikasi dikonfigurasi, server akan menggunakan metode pertama yang tersedia dalam urutan prioritas di atas. Autentikasi per-permintaan hanya tersedia saat menggunakan mode transport HTTP atau SSE.

Catatan: Menggunakan token akun layanan dengan peran readonly disarankan.

Definisi Server MCP menggunakan nama pengguna dan kata sandi (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>"
  }
}

Definisi Server MCP menggunakan token akun layanan (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>"
  }
}

Definisi Server MCP menggunakan nama pengguna dan kata sandi (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>

Definisi Server MCP menggunakan token akun layanan (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>

Contoh Konfigurasi (Claude Desktop)

Buka file konfigurasi Claude Desktop yang terletak di:
- Di macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Di Windows: %APPDATA%/Claude/claude_desktop_config.json
Tambahkan entri server mcp-hydrolix ke blok konfigurasi mcpServers untuk menggunakan nama pengguna dan kata sandi:

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

Untuk memanfaatkan akun layanan, gunakan blok konfigurasi berikut:

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

Perbarui definisi variabel lingkungan untuk menunjuk ke klaster Hydrolix Anda.
(Disarankan) Temukan entri perintah untuk uvx dan ganti dengan path absolut ke eksekutabel uvx. Ini memastikan bahwa versi uvx yang benar digunakan saat memulai server. Anda dapat menemukan path ini menggunakan which uvx atau where.exe uvx.
Mulai ulang Claude Desktop untuk menerapkan perubahan. Jika Anda menggunakan Windows, pastikan Claude dihentikan sepenuhnya dengan menutup klien menggunakan ikon baki sistem.

Contoh Konfigurasi (Claude Code)

Untuk mengonfigurasi server MCP Hydrolix untuk Claude Code, jalankan perintah berikut:

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

Variabel Lingkungan

Variabel berikut digunakan untuk mengonfigurasi koneksi Hydrolix. Variabel ini dapat disediakan melalui blok konfigurasi MCP (seperti yang ditunjukkan di atas), file .env, atau variabel lingkungan tradisional.

Variabel Wajib

Anda HARUS menetapkan salah satu dari berikut untuk mengidentifikasi klaster:

HYDROLIX_URL (disarankan): URL publik kanonik klaster Hydrolix Anda, mis. https://mycluster.hydrolix.live. Untuk penerapan di luar klaster pada umumnya, variabel tunggal ini sudah cukup — variabel ini menyediakan host, port (default skema 443/80), dan pengaturan TLS untuk endpoint kueri HTTP dan probe REST /version.
HYDROLIX_HOST (usang): Nama host server Hydrolix Anda. Masih dihormati untuk kompatibilitas mundur tetapi harus diganti dengan HYDROLIX_URL.

Ketika HYDROLIX_MCP_SERVER_TRANSPORT adalah http atau sse, HYDROLIX_URL secara khusus diperlukan (endpoint metadata OAuth mengiklankannya). HYDROLIX_HOST saja tidak cukup untuk transport ini.

Override Endpoint

Ini mengganti nilai yang berasal dari HYDROLIX_URL. Berguna untuk penerapan dalam klaster di mana endpoint kueri HTTP dan API versi berada di nama host atau port internal yang berbeda. Prioritas override: var baru eksplisit > alias usang > berasal dari HYDROLIX_URL > default keras.

HYDROLIX_HTTP_QUERY_HOST / HYDROLIX_HTTP_QUERY_PORT / HYDROLIX_HTTP_QUERY_SECURE: mengganti endpoint kueri HTTP ClickHouse.
HYDROLIX_VERSION_API_HOST / HYDROLIX_VERSION_API_PORT / HYDROLIX_VERSION_API_SECURE: mengganti endpoint probe REST /version. HYDROLIX_VERSION_API_SECURE mewarisi dari nilai aman kueri HTTP yang diselesaikan secara default.

Variabel Usang

Berikut ini masih dihormati selama masa transisi tetapi akan dihapus di rilis mendatang. Migrasikan sesuai kenyamanan Anda:

Usang	Pengganti
`HYDROLIX_HOST`	`HYDROLIX_URL` (disukai) atau `HYDROLIX_HTTP_QUERY_HOST`
`HYDROLIX_PORT`	`HYDROLIX_HTTP_QUERY_PORT`
`HYDROLIX_SECURE`	`HYDROLIX_HTTP_QUERY_SECURE`
`HYDROLIX_API_HOST`	`HYDROLIX_VERSION_API_HOST`
`HYDROLIX_API_PORT`	`HYDROLIX_VERSION_API_PORT`

Operator eksternal yang menggunakan salah satu dari ini akan melihat peringatan startup satu kali yang menyarankan migrasi ke HYDROLIX_URL. Penerapan dalam klaster (dikelola o6r) tidak akan melihat peringatan ini; migrasi mereka ditangani oleh platform.

Variabel Autentikasi

Setidaknya satu metode autentikasi harus dikonfigurasi saat menggunakan transport stdio:

HYDROLIX_TOKEN: Token akun layanan untuk autentikasi berbasis lingkungan
HYDROLIX_USER dan HYDROLIX_PASSWORD: Nama pengguna dan kata sandi untuk autentikasi berbasis lingkungan (keduanya harus disediakan bersama)

Singkatnya:

Untuk stdio, Anda HARUS menggunakan HYDROLIX_TOKEN atau HYDROLIX_USER+HYDROLIX_PASS (kredensial lingkungan)
Untuk http/sse, Anda BOLEH menggunakan HYDROLIX_TOKEN atau HYDROLIX_USER+HYDROLIX_PASS (kredensial lingkungan), tetapi Anda juga dapat menggunakan kredensial per-permintaan.

Jika tidak ada kredensial yang disediakan melalui lingkungan atau permintaan, permintaan akan gagal.

Variabel Opsional

HYDROLIX_VERIFY: Mengaktifkan/menonaktifkan verifikasi sertifikat SSL
- Default: "true"
- Atur ke "false" untuk menonaktifkan verifikasi sertifikat (tidak disarankan untuk produksi)
HYDROLIX_DATABASE: Database default yang digunakan
- Default: Tidak ada (menggunakan default server)
- Atur ini untuk otomatis terhubung ke database tertentu
HYDROLIX_MCP_SERVER_TRANSPORT: Mengatur metode transport untuk server MCP.
- Default: "stdio"
- Opsi valid: "stdio", "http", "sse". Ini berguna untuk pengembangan lokal dengan alat seperti MCP Inspector.
HYDROLIX_MCP_BIND_HOST: Host untuk mengikat server MCP saat menggunakan transport HTTP atau SSE
- Default: "127.0.0.1"
- Atur ke "0.0.0.0" untuk mengikat ke semua antarmuka jaringan (berguna untuk Docker atau akses jarak jauh)
- Hanya digunakan saat transport adalah "http" atau "sse"
HYDROLIX_MCP_BIND_PORT: Port untuk mengikat server MCP saat menggunakan transport HTTP atau SSE
- Default: "8000"
- Hanya digunakan saat transport adalah "http" atau "sse"
HYDROLIX_MAX_RAW_TIMERANGE: Rentang waktu maksimum dalam detik yang diizinkan untuk kueri terhadap tabel non-ringkasan
- Default: 21600 (6 jam)
- Kueri yang menargetkan tabel ringkasan tidak terpengaruh oleh batas ini

Untuk MCP Inspector atau akses jarak jauh dengan transport HTTP:

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_USER=default
HYDROLIX_PASSWORD=myPassword
HYDROLIX_MCP_SERVER_TRANSPORT=http
HYDROLIX_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
HYDROLIX_MCP_BIND_PORT=4200  # Custom port (default: 8000)

Saat menggunakan transport HTTP, server akan berjalan pada port yang dikonfigurasi (default 8000). Misalnya, dengan konfigurasi di atas:

Endpoint MCP: http://localhost:4200/mcp
Pemeriksaan kesehatan: http://localhost:4200/health

Menggunakan Autentikasi Per-Permintaan dengan Transport HTTP

Saat menggunakan transport HTTP atau SSE, Anda dapat menghilangkan kredensial berbasis lingkungan dan sebagai gantinya menyediakan autentikasi per-permintaan. Ini berguna untuk skenario multi-pengguna atau dengan klien yang tidak mendukung menjalankan server MCP secara lokal.

Contoh konfigurasi mcpServers yang terhubung ke server HTTP jarak jauh dengan autentikasi per-permintaan:

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

Contoh konfigurasi minimal .env untuk menjalankan server HTTP Anda sendiri tanpa kredensial lingkungan:

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

Meskipun bukan bagian dari spesifikasi MCP, banyak klien MCP mengizinkan penambahan header ke permintaan yang dikeluarkan MCP. Jika ini memungkinkan, kami merekomendasikan untuk mengonfigurasi klien MCP agar meneruskan token akun layanan melalui header Authorization: Bearer <sa-token-here> alih-alih sebagai parameter kueri untuk keamanan yang lebih baik.

Catatan: Pengaturan host dan port pengikatan hanya digunakan saat transport diatur ke "http" atau "sse".

Pengujian end-to-end

Suite terpisah di bawah tests/e2e/ menerapkan pohon kerja lokal ke kluster Hydrolix Kubernetes langsung dan menguji asap alat MCP terhadap pod yang berjalan. Ini dikecualikan dari pengujian default dan dari hook pra-push; menjalankannya memerlukan opt-in eksplisit melalui penanda pytest end_to_end plus kredensial. Lihat tests/e2e/README.md untuk runbook.