Hydrolix

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 dengan:

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

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 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-apa, biner tidak ada di PATH Anda. Perbaikan paling mudah 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

1. Buka percakapan baru di Claude Desktop. Cari ikon alat/palu di dekat input teks — ini menandakan server MCP berhasil terhubung.

2. Coba prompt ini untuk mengonfirmasi 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. 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 dalam lingkungan terisolasi.

Autentikasi

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

1. Token Bearer per-permintaan: Token akun layanan yang disediakan melalui header Authorization: Bearer <token>
2. Parameter GET per-permintaan: Token akun layanan yang disediakan 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.

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)

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 untuk menunjuk ke klaster Hydrolix Anda.

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

5. Mulai ulang Claude Desktop untuk menerapkan perubahan. Jika 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 kanonis 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 spesifik diperlukan (endpoint metadata OAuth mendatang 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 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.

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 .env minimal 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 sarankan 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 bind hanya digunakan saat transport diatur ke "http" atau "sse".

Variabel Opsional

Lihat docs/CONFIG.md untuk penggantian endpoint, alias variabel usang, dan set lengkap variabel penyetelan opsional (timeout, penggantian SETTINGS kueri, pemotongan hasil, penyetelan pekerja HTTP/SSE, proxy, metrik, dan escape hatches).

Pengelola

Tugas yang memerlukan hak istimewa operasional — menjalankan rangkaian end-to-end terhadap klaster Hydrolix langsung, dan memotong rilis — didokumentasikan secara terpisah di MAINTAINERS.md.