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 makine adınız ve bir kullanıcı adı/parola veya bir hizmet hesabı belirteci. Bunlara sahip değilseniz, Hydrolix yöneticinize danışın.
• 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'niz yoksa, 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'ı 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 girişi ekleyin (dosya henüz 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> yerine gerçek kimlik bilgilerinizi yazın.

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

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

[!NOTE] Kullanıcı adı/parola yerine bir hizmet hesabı belirteci ile kimlik doğrulaması yapıyorsanız, Kimlik Doğrulama bölümüne bakın.

Komut bulunamadı?

Claude Desktop, kabuğunuzun PATH'i olmadan başlatılır, bu nedenle ikili dosya yüklü olsa bile onu bulamayabilir. Tam yolu bulun ve yapılandırmada "command" değeri olarak kullanın.

Seçenek A (uv): uvx yolunu bulun:

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

Seçenek B (pip): mcp-hydrolix yolunu 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'ı 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'dan tamamen çıktığı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 yanında bir araçlar/çekiç simgesi arayın — bu, MCP sunucusunun başarıyla bağlandığını onaylar.

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'deki 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ıklamayla kurulum için bu README'nin üst kısmındaki VS Code'da Kur rozetine tıklayın. Kullanıcı arayüzü akışını tercih ederseniz, Komut Paletini açın (Cmd+Shift+P / Ctrl+Shift+P), MCP: Sunucu Ekle'yi çalıştırın, Komut (stdio) öğesini seçin ve Adım 3'teki uvx ... komutunu ve env bloğunu yeniden kullanın.

Araçlar

• run_select_query

  • Hydrolix kümenizde SQL sorguları yürütün.
  • Girdi: sql (dize): Yürütülecek SQL sorgusu.

• 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

Yapay zeka mimarilerindeki geniş çeşitlilik nedeniyle, tüm modeller yukarıdaki araçları proaktif olarak kullanmayacak ve çok azı, modele sağlanan özenle oluşturulmuş araç açıklamalarıyla bile, rehberlik olmadan bunları etkili bir şekilde kullanacaktı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ı talep edin (örn., "Hydrolix veritabanıma erişmek için MCP araçlarını kullanarak, lütfen ...")
  • Bu, modeli mevcut MCP araçlarını kullanmaya teşvik eder ve halüsinasyonları en aza indirir.
• İstemlerinize zaman aralıklarını dahil edin (örn., "5 Aralık 2023 ile 18 Ocak 2024 arasında, ...") ve özellikle çıktının zaman damgasına göre sıralanmasını isteyin.
  • Bu, modeli birincil anahtar optimizasyonlarından yararlanan daha verimli sorgular yazmaya yönlendirir

Sağlık Kontrolü Uç Noktası

HTTP veya SSE aktarımı ile ç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şlığının Clickhouse sürümüyle birlikte 200 OK döndürür
• Sunucu Hydrolix sorgu başlığına bağlanamazsa 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 girişi kullanılarak yapılandırılır. MCP sunucularını nerede bulacağınız veya bildireceğinizle ilgili özel talimatlar için istemcinizin belgelerine bakı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ı yalıtılmış bir ortamda yönetecek olan uv proje yöneticisi aracılığıyladır.

Kimlik Doğrulama

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

1. İstek başına Taşıyıcı belirteç: 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 parola (HYDROLIX_USER ve HYDROLIX_PASSWORD)

Birden çok kimlik doğrulama yöntemi yapılandırıldığında, sunucu yukarıdaki öncelik sırasına göre ilk kullanılabilir yöntemi kullanacaktır. İstek başına kimlik doğrulama yalnızca HTTP veya SSE aktarım modları kullanılırken kullanılabilir.

Not: Salt okunur role sahip bir hizmet hesabı belirteci kullanılması önerilir.

Kullanıcı adı ve parola 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 parola 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. Aşağıdaki 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 parola kullanmak için mcpServers yapılandırma bloğuna bir mcp-hydrolix sunucu girişi 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ından yararlanmak 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ümenize işaret edecek şekilde güncelleyin.

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

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

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

Hydrolix MCP sunucusunu Claude Code için 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

Aşağıdaki değişkenler Hydrolix bağlantısını yapılandırmak için 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.

Gerekli Değişkenler

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

• HYDROLIX_URL (önerilir): Hydrolix kümenizin standart genel URL'si, örn. 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 araştırması için ana bilgisayar, bağlantı noktası (şema varsayılanı 443/80) ve TLS ayarlarını sağlar.
• HYDROLIX_HOST (kullanımdan kaldırıldı): Hydrolix sunucunuzun ana makine adı. Geriye dönük uyumluluk için hala kabul edilir ancak HYDROLIX_URL ile değiştirilmelidir.

HYDROLIX_MCP_SERVER_TRANSPORT, http veya sse olduğunda, HYDROLIX_URL özellikle gereklidir (yakında çıkacak bir OAuth meta veri uç noktası bunu ilan edecektir). Bu aktarımlar için HYDROLIX_HOST tek başına yeterli değildir.

Kimlik Doğrulama Değişkenleri

Stdio aktarımı kullanılı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 parola (her ikisi birlikte sağlanmalıdır)

Özetle:

• Stdio için, HYDROLIX_TOKEN veya HYDROLIX_USER+HYDROLIX_PASS (ortam kimlik bilgileri) kullanmanız ZORUNLUDUR
• Http/sse için, HYDROLIX_TOKEN veya HYDROLIX_USER+HYDROLIX_PASS (ortam kimlik bilgileri) kullanabilirsiniz, ancak bunun yerine istek başına kimlik bilgileri de kullanabilirsiniz.

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

HTTP Aktarımı ile İstek Başına Kimlik Doğrulama Kullanma

HTTP veya SSE aktarımı 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ğrulama ile 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 bir hizmet hesabı belirtecini sorgu parametresi yerine Authorization: Bearer <sa-token-here> başlığı aracılığıyla iletecek şekilde yapılandırmanızı öneririz.

Not: Bağlanma ana bilgisayarı ve bağlantı noktası ayarları yalnızca aktarım "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 tam seti (zaman aşımları, sorgu AYARLARI geçersiz kılmaları, sonuç kesme, 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 paketi çalıştırmak ve bir sürüm yayınlamak — MAINTAINERS.md dosyasında ayrıca belgelenmiştir.