Hydrolix

Server MCP Hydrolix

Server MCP untuk Hydrolix.

Memulai Cepat

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

Langkah 1 — Prasyarat

Sebelum memulai, pastikan Anda memiliki:

• Kredensial Hydrolix — nama host cluster Anda beserta nama pengguna/kata sandi atau token akun layanan. Jika Anda tidak 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 Anda 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

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

pip install mcp-hydrolix

Langkah 3 — Konfigurasi Claude Desktop

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

2. 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 kolom "args".

[!TIP] Jika file sudah memiliki entri lain, tambahkan blok "mcp-hydrolix" di dalam objek "mcpServers" yang ada daripada 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 diinstal. Temukan jalur lengkap dan gunakan sebagai nilai "command" dalam 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 mengembalikan apa pun, biner tidak ada di PATH Anda. Perbaikan paling bersih 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 keluar sepenuhnya dari Claude sebelum memulai ulang. Di macOS, tekan Cmd+Q atau klik kanan ikon Dock dan pilih Keluar. Di Windows, gunakan ikon baki sistem.

Langkah 5 — Verifikasi bahwa ini berfungsi

1. Buka percakapan baru di Claude Desktop. Cari ikon alat/palu di dekat input teks — ini mengonfirmasi bahwa server MCP terhubung dengan sukses.

2. Coba prompt ini untuk mengonfirmasi semuanya berfungsi:

   Menggunakan alat MCP Hydrolix Anda, daftarkan database yang tersedia.

Claude harus memanggil alat list_databases dan mengembalikan daftar database dari cluster Anda.

---

Lebih suka menggunakan Claude Code?

Jika Anda 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 database yang tersedia.

Lebih suka menggunakan VS Code?

Klik lencana Instal di VS Code di bagian atas README ini untuk instalasi satu klik. Jika Anda lebih suka alur UI, buka Palet Perintah (Cmd+Shift+P / Ctrl+Shift+P), jalankan MCP: Tambah Server, pilih Perintah (stdio), dan gunakan kembali perintah uvx ... dan blok env dari Langkah 3.

Alat

• run_select_query

  • Jalankan kueri SQL di cluster Hydrolix Anda.
  • Masukan: query (string): Kueri SQL yang akan dijalankan.
  • Masukan: max_cells (integer, opsional): Anggaran sel hasil (baris × kolom); saat server menetapkan batas, pemanggil hanya dapat menurunkannya.
  • Masukan: purpose (string, wajib): Alasan kueri dijalankan; dicatat dengan kueri sebagai hdx_query_comment.
  • Klausa FORMAT di akhir dihapus; server memilih format kabel.

• list_databases

  • Daftarkan semua database di cluster Hydrolix Anda.

• list_tables

  • Daftarkan semua tabel dalam database.
  • Masukan: database (string): Nama database.

• get_table_info

  • Dapatkan metadata tabel seperti skema
  • Masukan: database (string): Nama database.
  • Masukan: table (string): Nama tabel.

Penggunaan yang Efektif

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

• Rujuk database Hydrolix Anda dengan nama dan minta penggunaan alat dalam prompt Anda (misalnya, "Menggunakan alat MCP untuk mengakses database Hydrolix saya, tolong ...")
  • Ini mendorong model untuk menggunakan alat MCP yang tersedia dan meminimalkan halusinasi.
• Sertakan rentang waktu dalam prompt Anda (misalnya, "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

Titik Akhir Pemeriksaan Kesehatan

Saat berjalan dengan transport HTTP atau SSE, titik akhir pemeriksaan kesehatan tersedia di /health. Titik akhir ini:

• Mengembalikan 200 OK dengan versi Clickhouse dari 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. Konsultasikan dokumentasi klien Anda untuk instruksi spesifik tentang di mana menemukan atau mendeklarasikan server MCP. Contoh pengaturan menggunakan Claude Desktop didokumentasikan di bawah ini.

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

Autentikasi

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

1. Token Bearer per-permintaan: Token akun layanan yang diberikan melalui header Authorization: Bearer <token>
2. Parameter GET per-permintaan: Token akun layanan yang diberikan melalui parameter kueri ?token=<token>
3. 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. Formulir ?token= ada untuk klien yang tidak dapat mengirim header; setel HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false pada penerapan di mana setiap klien mengirim header Authorization (lihat Kredensial per-permintaan).

Catatan: Menggunakan token akun layanan dengan peran hanya-baca 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)

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

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

3. Perbarui definisi variabel lingkungan agar menunjuk ke cluster Hydrolix Anda.

4. (Disarankan) Temukan entri perintah untuk uvx dan ganti dengan jalur absolut ke executable uvx. Ini memastikan bahwa versi uvx yang benar digunakan saat memulai server. Anda dapat menemukan jalur ini menggunakan which uvx atau where.exe uvx.

5. 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 diberikan melalui blok konfigurasi MCP (seperti yang ditunjukkan di atas), file .env, atau variabel lingkungan tradisional.

Variabel yang Diperlukan

Anda HARUS menetapkan salah satu dari berikut ini untuk mengidentifikasi cluster:

• HYDROLIX_URL (disarankan): URL publik kanonis dari cluster Hydrolix Anda, misalnya https://mycluster.hydrolix.live. Untuk penerapan tipikal di luar cluster, satu variabel ini sudah cukup — variabel ini menyediakan host, port (default skema 443/80), dan pengaturan TLS untuk titik akhir 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 (titik akhir metadata OAuth yang akan datang akan mengiklankannya). HYDROLIX_HOST saja tidak cukup untuk transport ini.

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 diberikan bersama)

Ringkasnya:

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

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

Menggunakan Autentikasi Per-Permintaan dengan Transport HTTP

Saat menggunakan transport HTTP atau SSE, Anda dapat menghilangkan kredensial berbasis lingkungan dan sebagai gantinya memberikan 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 memungkinkan, kami merekomendasikan mengonfigurasi klien MCP untuk 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 bind hanya digunakan saat transport diatur ke "http" atau "sse".

Variabel Opsional

Lihat docs/CONFIG.md untuk penggantian titik akhir, alias variabel usang, dan rangkaian lengkap variabel penyesuaian opsional (batas waktu, penggantian pengaturan SETTINGS kueri, pemotongan hasil, penyesuaian pekerja HTTP/SSE, proksi, metrik, dan jalur pelarian).

Pemelihara

Tugas yang memerlukan hak istimewa operasional — menjalankan rangkaian pengujian end-to-end terhadap klaster Hydrolix yang aktif, serta membuat rilis — didokumentasikan secara terpisah di MAINTAINERS.md.