Hydrolix

Hydrolix MCP Sunucusu

Hydrolix için bir MCP sunucusu.

Hızlı Başlangıç

Birkaç dakika içinde çalışmaya başlayın. Bu bölüm Claude Desktop ve Claude Code'u kapsar.

Adım 1 — Ön Koşullar

Başlamadan önce aşağıdakilere sahip olduğunuzdan emin olun:

• Hydrolix kimlik bilgileri — küme ana bilgisayar adınız ve kullanıcı adı/şifre veya bir hizmet hesabı belirteci. Bunlara sahip değilseniz, Hydrolix yöneticinize sorun.
• Claude Desktop — claude.ai/download adresinden indirin.

Adım 2 — MCP sunucusunu kurun

Kurulumunuza uygun yöntemi seçin:

Seçenek A: uv kullanma (önerilir)

uv Python'u otomatik olarak yönetir ve mcp-hydrolix'i isteğe bağlı olarak indirir, bu nedenle ayrı bir kurulum adımı gerekmez. uv'ye sahip değilseniz, kurun:

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"

Seçenek B: pip kullanma

Python 3.13+ gerektirir. Python'u kurmanız gerekiyorsa, python.org adresinden indirin.

pip install mcp-hydrolix

Adım 3 — Claude Desktop'u yapılandırın

1. Claude Desktop yapılandırma dosyasını açın:

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

2. "mcpServers" nesnesine aşağıdaki girdiyi ekleyin (dosya yoksa bu içerikle oluşturun):

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

<your-hydrolix-hostname>, <your-username> ve <your-password> değerlerini gerçek kimlik bilgilerinizle değiştirin.

[!NOT] Seçenek B'yi (pip) kullandıysanız, "args" alanı olmadan "command": "mcp-hydrolix" kullanın.

[!İPUCU] Dosyada zaten başka girdiler varsa, tüm dosyayı değiştirmek yerine "mcp-hydrolix" bloğunu mevcut "mcpServers" nesnesinin içine ekleyin.

[!NOT] Kullanıcı adı/şifre yerine bir hizmet hesabı belirteciyle kimlik doğruluyorsanız, Kimlik Doğrulama bölümüne bakın.

Komut bulunamadı mı?

Claude Desktop, kabuğunuzun PATH'ini yüklemeden başlar, bu nedenle ikili dosya kurulu olsa bile onu bulamayabilir. Tam yolu bulun ve yapılandırmada "command" değeri olarak kullanın.

Seçenek A (uv): uvx bulun:

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

Seçenek B (pip): mcp-hydrolix bulun:

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

which/where.exe hiçbir şey döndürmezse, ikili dosya PATH'inizde değildir. En temiz çözüm, Python ortamını ve PATH'i sizin için yöneten Seçenek A'ya (uv) geçmektir.

Adım 4 — Claude Desktop'u yeniden başlatın

Yapılandırmayı uygulamak için uygulamayı yeniden başlatın.

macOS / Windows kullanıcıları: Yeniden başlatmadan önce Claude'u tamamen kapatdığınızdan emin olun. macOS'ta Cmd+Q tuşlarına basın veya Dock simgesine sağ tıklayıp Çık'ı seçin. Windows'ta sistem tepsisi simgesini kullanın.

Adım 5 — Çalıştığını doğrulayın

1. Claude Desktop'ta yeni bir konuşma açın. Metin girişinin yakınında bir araçlar/çekiç simgesi arayın — bu, MCP sunucusunun başarıyla bağlandığını doğrular.

2. Her şeyin çalıştığını doğrulamak için şu istemi deneyin:

   Hydrolix MCP araçlarınızı kullanarak mevcut veritabanlarını listeleyin.

Claude, list_databases aracını çağırmalı ve kümenizden bir veritabanı listesi döndürmelidir.

---

Bunun yerine Claude Code mu kullanıyorsunuz?

Komut satırını tercih ediyorsanız, uv'nin kurulu olduğundan emin olun (Adım 2 içindeki Seçenek A), ardından şunu çalıştırın:

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

Ardından Claude Code'u açın ve aynı istemle test edin:

Hydrolix MCP araçlarınızı kullanarak mevcut veritabanlarını listeleyin.

Bunun yerine VS Code mu kullanıyorsunuz?

Tek tıkla kurulum için bu README'nin üst kısmındaki VS Code'da Kur rozetine tıklayın. UI akışını tercih ediyorsanız, Komut Paleti'ni (Cmd+Shift+P / Ctrl+Shift+P) açın, MCP: Sunucu Ekle'yi çalıştırın, Komut (stdio) seçeneğini seçin ve Adım 3 içindeki uvx ... komutunu ve env bloğunu yeniden kullanın.

Araçlar

• run_select_query

  • Hydrolix kümenizde SQL sorguları çalıştırın.
  • Girdi: query (dize): Çalıştırılacak SQL sorgusu.
  • Girdi: max_cells (tamsayı, isteğe bağlı): Sonuç hücresi bütçesi (satırlar × sütunlar); sunucu bir sınır belirlediğinde, çağıran yalnızca düşürebilir.
  • Girdi: purpose (dize, zorunlu): Sorgunun neden çalıştırıldığı; sorguyla birlikte hdx_query_comment olarak kaydedilir.
  • Sondaki FORMAT yan tümcesi kaldırılır; sunucu kablosuz formatı seçer.

• list_databases

  • Hydrolix kümenizdeki tüm veritabanlarını listeleyin.

• list_tables

  • Bir veritabanındaki tüm tabloları listeleyin.
  • Girdi: database (dize): Veritabanının adı.

• get_table_info

  • Şema gibi tablo meta verilerini alın
  • Girdi: database (dize): Veritabanının adı.
  • Girdi: table (dize): Tablonun adı.

Etkili Kullanım

LLM mimarilerindeki geniş çeşitlilik nedeniyle, tüm modeller yukarıdaki araçları proaktif olarak kullanmaz ve modele sağlanan özenle hazırlanmış araç açıklamalarına rağmen çok azı bunları rehberlik olmadan etkili bir şekilde kullanır. Hydrolix MCP sunucusunu kullanırken modelinizden en iyi sonuçları almak için aşağıdakileri öneririz:

• İstemlerinizde Hydrolix veritabanınıza adıyla atıfta bulunun ve araç kullanımını isteyin (ör. "Hydrolix veritabanıma erişmek için MCP araçlarını kullanarak, lütfen ...")
  • Bu, modelin mevcut MCP araçlarını kullanmasını teşvik eder ve halüsinasyonları en aza indirir.
• İstemlerinize zaman aralıkları ekleyin (ör. "5 Aralık 2023 ile 18 Ocak 2024 arasında, ...") ve çıktının zaman damgasına göre sıralanmasını özellikle isteyin.
  • Bu, modelin birincil anahtar optimizasyonlarından yararlanan daha verimli sorgular yazmasını sağlar.

Sağlık Kontrolü Uç Noktası

HTTP veya SSE taşımasıyla çalışırken, /health adresinde bir sağlık kontrolü uç noktası mevcuttur. Bu uç nokta:

• Sunucu sağlıklıysa ve Hydrolix'e bağlanabiliyorsa, Hydrolix sorgu başının Clickhouse sürümüyle 200 OK döndürür
• Sunucu Hydrolix sorgu başına bağlanamıyorsa 503 Service Unavailable döndürür

Örnek:

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

Yapılandırma

Hydrolix MCP sunucusu, standart bir MCP sunucu girdisi kullanılarak yapılandırılır. MCP sunucularını nerede bulacağınız veya bildireceğiniz konusunda özel talimatlar için istemcinizin belgelerine danışın. Claude Desktop kullanan örnek bir kurulum aşağıda belgelenmiştir.

Hydrolix MCP sunucusunu başlatmanın önerilen yolu, diğer tüm bağımlılıkların kurulumunu izole bir ortamda yönetecek olan uv proje yöneticisi aracılığıyladır.

Kimlik Doğrulama

Sunucu, aşağıdaki öncelik sırasıyla (en yüksekten en düşüğe) birden çok kimlik doğrulama yöntemini destekler:

1. İstek başına Bearer belirteci: Authorization: Bearer <token> başlığı aracılığıyla sağlanan hizmet hesabı belirteci
2. İstek başına GET parametresi: ?token=<token> sorgu parametresi aracılığıyla sağlanan hizmet hesabı belirteci
3. Ortam tabanlı kimlik bilgileri: Ortam değişkenleri aracılığıyla yapılandırılan kimlik bilgileri
   • Hizmet hesabı belirteci (HYDROLIX_TOKEN) veya
   • Kullanıcı adı ve şifre (HYDROLIX_USER ve HYDROLIX_PASSWORD)

Birden çok kimlik doğrulama yöntemi yapılandırıldığında, sunucu yukarıdaki öncelik sırasındaki ilk kullanılabilir yöntemi kullanır. İstek başına kimlik doğrulama yalnızca HTTP veya SSE taşıma modlarını kullanırken kullanılabilir. ?token= biçimi, başlık gönderemeyen istemciler için mevcuttur; her istemcinin Authorization başlığını gönderdiği dağıtımlarda HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false değerini ayarlayın (bkz. İstek başına kimlik bilgileri).

Not: Salt okunur rollü bir hizmet hesabı belirteci kullanılması önerilir.

Kullanıcı adı ve şifre kullanan MCP Sunucu tanımı (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>"
  }
}

Hizmet hesabı belirteci kullanan MCP Sunucu tanımı (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>"
  }
}

Kullanıcı adı ve şifre kullanan MCP Sunucu tanımı (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>

Hizmet hesabı belirteci kullanan MCP Sunucu tanımı (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>

Yapılandırma Örneği (Claude Desktop)

1. Şu konumda bulunan Claude Desktop yapılandırma dosyasını açın:

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

2. Kullanıcı adı ve şifre kullanmak için mcpServers yapılandırma bloğuna bir mcp-hydrolix sunucu girdisi ekleyin:

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

Hizmet hesabı kullanmak için aşağıdaki yapılandırma bloğunu kullanın:

{
  "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. Ortam değişkeni tanımlarını Hydrolix kümenizi gösterecek şekilde güncelleyin.

4. (Önerilir) uvx için komut girdisini bulun ve uvx yürütülebilir dosyasının mutlak yoluyla değiştirin. Bu, sunucuyu başlatırken uvx sürümünün doğru kullanılmasını sağlar. Bu yolu which uvx veya where.exe uvx kullanarak bulabilirsiniz.

5. Değişiklikleri uygulamak için Claude Desktop'u yeniden başlatın. Windows kullanıyorsanız, istemciyi sistem tepsisi simgesini kullanarak kapatarak Claude'un tamamen durdurulduğundan emin olun.

Yapılandırma Örneği (Claude Code)

Claude Code için Hydrolix MCP sunucusunu yapılandırmak üzere aşağıdaki komutu çalıştırın:

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

Ortam Değişkenleri

Hydrolix bağlantısını yapılandırmak için aşağıdaki değişkenler kullanılır. Bu değişkenler MCP yapılandırma bloğu (yukarıda gösterildiği gibi), bir .env dosyası veya geleneksel ortam değişkenleri aracılığıyla sağlanabilir.

Zorunlu Değişkenler

Kümeyi tanımlamak için aşağıdakilerden BİRİNİ ayarlamanız GEREKİR:

• HYDROLIX_URL (önerilir): Hydrolix kümenizin kurallı genel URL'si, ör. https://mycluster.hydrolix.live. Tipik küme dışı dağıtımlar için bu tek değişken yeterlidir — hem HTTP sorgu uç noktası hem de REST /version yoklaması için ana bilgisayarı, bağlantı noktasını (şema varsayılanı 443/80) ve TLS ayarlarını sağlar.
• HYDROLIX_HOST (kullanımdan kaldırıldı): Hydrolix sunucunuzun ana bilgisayar adı. Geriye dönük uyumluluk için hâlâ desteklenir, ancak HYDROLIX_URL ile değiştirilmelidir.

HYDROLIX_MCP_SERVER_TRANSPORT değeri http veya sse olduğunda, HYDROLIX_URL özellikle zorunludur (yaklaşan bir OAuth meta veri uç noktası bunu duyurur). HYDROLIX_HOST tek başına bu taşımalar için yeterli değildir.

Kimlik Doğrulama Değişkenleri

stdio taşımasını kullanırken en az bir kimlik doğrulama yöntemi yapılandırılmalıdır:

• HYDROLIX_TOKEN: Ortam tabanlı kimlik doğrulama için hizmet hesabı belirteci
• HYDROLIX_USER ve HYDROLIX_PASSWORD: Ortam tabanlı kimlik doğrulama için kullanıcı adı ve şifre (her ikisi de birlikte sağlanmalıdır)

Özetle:

• stdio için HYDROLIX_TOKEN veya HYDROLIX_USER+HYDROLIX_PASS (ortam kimlik bilgileri) KULLANMALISINIZ
• http/sse için HYDROLIX_TOKEN veya HYDROLIX_USER+HYDROLIX_PASS (ortam kimlik bilgileri) KULLANABİLİRSİNİZ, ancak bunun yerine istek başına kimlik bilgilerini kullanabilirsiniz.

Ortam veya istek aracılığıyla hiçbir kimlik bilgisi sağlanmazsa, istek başarısız olur.

HTTP Taşımasıyla İstek Başına Kimlik Doğrulama Kullanma

HTTP veya SSE taşıması kullanırken, ortam tabanlı kimlik bilgilerini atlayabilir ve bunun yerine istek başına kimlik doğrulama sağlayabilirsiniz. Bu, çok kullanıcılı senaryolar veya MCP sunucularını yerel olarak çalıştırmayı desteklemeyen istemciler için kullanışlıdır.

İstek başına kimlik doğrulamayla uzak bir HTTP sunucusuna bağlanan örnek mcpServers yapılandırması:

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

Ortam kimlik bilgileri olmadan kendi HTTP sunucunuzu çalıştırmak için örnek minimal .env yapılandırması:

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

MCP spesifikasyonunun bir parçası olmasa da, birçok MCP istemcisi MCP tarafından verilen isteklere başlık eklemeye izin verir. Bu mümkün olduğunda, daha fazla güvenlik için MCP istemcisini, sorgu parametresi yerine Authorization: Bearer <sa-token-here> başlığı aracılığıyla bir hizmet hesabı belirteci iletecek şekilde yapılandırmanızı öneririz.

Not: Bağlama ana bilgisayarı ve bağlantı noktası ayarları yalnızca taşıma "http" veya "sse" olarak ayarlandığında kullanılır.

İsteğe Bağlı Değişkenler

Uç nokta geçersiz kılmaları, kullanımdan kaldırılmış değişken takma adları ve isteğe bağlı ayar değişkenlerinin tamamı (zaman aşımları, sorgu SETTINGS geçersiz kılmaları, sonuç kırpma, HTTP/SSE çalışan ayarı, proxy, metrikler ve kaçış kapakları) için docs/CONFIG.md dosyasına bakın.

Bakımcılar

Operasyonel ayrıcalıklar gerektiren görevler — canlı bir Hydrolix kümesine karşı uçtan uca test paketini çalıştırmak ve bir sürüm çıkarmak — ayrıca MAINTAINERS.md içinde belgelenmiştir.