Hydrolix

Máy chủ MCP Hydrolix

Một máy chủ MCP dành cho Hydrolix.

Bắt đầu nhanh

Bắt đầu hoạt động chỉ trong vài phút. Phần này bao gồm Claude Desktop và Claude Code.

Bước 1 — Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo bạn có:

• Thông tin xác thực Hydrolix — tên máy chủ cụm của bạn cùng với tên người dùng/mật khẩu hoặc mã thông báo tài khoản dịch vụ. Nếu bạn không có những thông tin này, hãy hỏi quản trị viên Hydrolix của bạn.
• Claude Desktop — tải xuống từ claude.ai/download.

Bước 2 — Cài đặt máy chủ MCP

Chọn phương pháp phù hợp với thiết lập của bạn:

Tùy chọn A: Sử dụng uv (khuyến nghị)

uv tự động quản lý Python và tải mcp-hydrolix theo yêu cầu, vì vậy không cần bước cài đặt riêng. Nếu bạn chưa có uv, hãy cài đặt nó:

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"

Tùy chọn B: Sử dụng pip

Yêu cầu Python 3.13+. Nếu bạn cần cài đặt Python, hãy tải xuống từ python.org.

pip install mcp-hydrolix

Bước 3 — Cấu hình Claude Desktop

1. Mở tệp cấu hình 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. Thêm mục sau vào đối tượng "mcpServers" (tạo tệp với nội dung này nếu nó chưa tồn tại):

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

Thay thế <your-hydrolix-hostname>, <your-username> và <your-password> bằng thông tin xác thực thực tế của bạn.

[!NOTE] Nếu bạn sử dụng Tùy chọn B (pip), hãy sử dụng "command": "mcp-hydrolix" mà không có trường "args".

[!TIP] Nếu tệp đã có các mục khác, hãy thêm khối "mcp-hydrolix" bên trong đối tượng "mcpServers" hiện có thay vì thay thế toàn bộ tệp.

[!NOTE] Nếu bạn xác thực bằng mã thông báo tài khoản dịch vụ thay vì tên người dùng/mật khẩu, hãy xem Xác thực.

Không tìm thấy lệnh?

Claude Desktop khởi chạy mà không có PATH của shell, vì vậy nó có thể không định vị được tệp nhị phân ngay cả khi đã được cài đặt. Hãy tìm đường dẫn đầy đủ và sử dụng nó làm giá trị "command" trong cấu hình.

Tùy chọn A (uv): tìm uvx:

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

Tùy chọn B (pip): tìm mcp-hydrolix:

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

Nếu which/where.exe không trả về gì, tệp nhị phân không nằm trong PATH của bạn. Giải pháp sạch nhất là chuyển sang Tùy chọn A (uv), tùy chọn này quản lý môi trường Python và PATH cho bạn.

Bước 4 — Khởi động lại Claude Desktop

Khởi động lại ứng dụng để áp dụng cấu hình.

Người dùng macOS / Windows: Hãy đảm bảo thoát hoàn toàn Claude trước khi khởi động lại. Trên macOS, nhấn Cmd+Q hoặc nhấp chuột phải vào biểu tượng Dock và chọn Thoát. Trên Windows, sử dụng biểu tượng khay hệ thống.

Bước 5 — Xác minh hoạt động

1. Mở cuộc trò chuyện mới trong Claude Desktop. Tìm biểu tượng công cụ/búa gần ô nhập văn bản — điều này xác nhận máy chủ MCP đã kết nối thành công.

2. Thử lời nhắc này để xác nhận mọi thứ hoạt động:

   Sử dụng các công cụ MCP Hydrolix của bạn, hãy liệt kê các cơ sở dữ liệu có sẵn.

Claude sẽ gọi công cụ list_databases và trả về danh sách các cơ sở dữ liệu từ cụm của bạn.

---

Sử dụng Claude Code thay thế?

Nếu bạn thích dòng lệnh, hãy đảm bảo uv được cài đặt (Tùy chọn A từ Bước 2), sau đó chạy:

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

Sau đó mở Claude Code và kiểm tra với cùng lời nhắc:

Sử dụng các công cụ MCP Hydrolix của bạn, hãy liệt kê các cơ sở dữ liệu có sẵn.

Sử dụng VS Code thay thế?

Nhấp vào huy hiệu Cài đặt trong VS Code ở đầu README này để cài đặt một cú nhấp chuột. Nếu bạn thích quy trình UI, hãy mở Bảng lệnh (Cmd+Shift+P / Ctrl+Shift+P), chạy MCP: Thêm máy chủ, chọn Lệnh (stdio) và sử dụng lại lệnh uvx ... và khối env từ Bước 3.

Công cụ

• run_select_query

  • Thực thi truy vấn SQL trên cụm Hydrolix của bạn.
  • Đầu vào: query (chuỗi): Truy vấn SQL cần thực thi.
  • Đầu vào: max_cells (số nguyên, tùy chọn): Ngân sách ô kết quả (hàng × cột); khi máy chủ đặt giới hạn, người gọi chỉ có thể hạ thấp nó.
  • Đầu vào: purpose (chuỗi, bắt buộc): Lý do truy vấn đang chạy; được ghi lại cùng với truy vấn dưới dạng hdx_query_comment.
  • Mệnh đề FORMAT ở cuối được loại bỏ; máy chủ chọn định dạng wire.

• list_databases

  • Liệt kê tất cả các cơ sở dữ liệu trên cụm Hydrolix của bạn.

• list_tables

  • Liệt kê tất cả các bảng trong một cơ sở dữ liệu.
  • Đầu vào: database (chuỗi): Tên của cơ sở dữ liệu.

• get_table_info

  • Lấy siêu dữ liệu bảng như schema
  • Đầu vào: database (chuỗi): Tên của cơ sở dữ liệu.
  • Đầu vào: table (chuỗi): Tên của bảng.

Sử dụng hiệu quả

Do sự đa dạng rộng rãi trong kiến trúc LLM, không phải tất cả các mô hình sẽ chủ động sử dụng các công cụ trên và rất ít mô hình sẽ sử dụng chúng hiệu quả nếu không có hướng dẫn, ngay cả với các mô tả công cụ được xây dựng cẩn thận được cung cấp cho mô hình. Để có kết quả tốt nhất từ mô hình của bạn khi sử dụng máy chủ MCP Hydrolix, chúng tôi khuyến nghị:

• Tham chiếu cơ sở dữ liệu Hydrolix của bạn theo tên và yêu cầu sử dụng công cụ trong lời nhắc của bạn (ví dụ: "Sử dụng công cụ MCP để truy cập cơ sở dữ liệu Hydrolix của tôi, vui lòng ...")
  • Điều này khuyến khích mô hình sử dụng các công cụ MCP có sẵn và giảm thiểu ảo giác.
• Bao gồm phạm vi thời gian trong lời nhắc của bạn (ví dụ: "Từ ngày 5 tháng 12 năm 2023 đến ngày 18 tháng 1 năm 2024, ...") và yêu cầu cụ thể rằng đầu ra được sắp xếp theo dấu thời gian.
  • Điều này nhắc mô hình viết các truy vấn hiệu quả hơn tận dụng tối ưu hóa khóa chính

Điểm cuối kiểm tra sức khỏe

Khi chạy với transport HTTP hoặc SSE, một điểm cuối kiểm tra sức khỏe có sẵn tại /health. Điểm cuối này:

• Trả về 200 OK với phiên bản Clickhouse của query-head Hydrolix nếu máy chủ khỏe mạnh và có thể kết nối với Hydrolix
• Trả về 503 Service Unavailable nếu máy chủ không thể kết nối với query-head Hydrolix

Ví dụ:

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

Cấu hình

Máy chủ MCP Hydrolix được cấu hình bằng mục nhập máy chủ MCP tiêu chuẩn. Tham khảo tài liệu của máy khách của bạn để biết hướng dẫn cụ thể về nơi tìm hoặc khai báo máy chủ MCP. Một ví dụ thiết lập sử dụng Claude Desktop được ghi lại bên dưới.

Cách được khuyến nghị để khởi chạy máy chủ MCP Hydrolix là thông qua trình quản lý dự án uv, trình quản lý này sẽ quản lý việc cài đặt tất cả các phụ thuộc khác trong một môi trường cô lập.

Xác thực

Máy chủ hỗ trợ nhiều phương pháp xác thực với thứ tự ưu tiên sau (từ cao nhất đến thấp nhất):

1. Mã thông báo Bearer theo yêu cầu: Mã thông báo tài khoản dịch vụ được cung cấp qua tiêu đề Authorization: Bearer <token>
2. Tham số GET theo yêu cầu: Mã thông báo tài khoản dịch vụ được cung cấp qua tham số truy vấn ?token=<token>
3. Thông tin xác thực dựa trên môi trường: Thông tin xác thực được cấu hình qua biến môi trường
   • Mã thông báo tài khoản dịch vụ (HYDROLIX_TOKEN), hoặc
   • Tên người dùng và mật khẩu (HYDROLIX_USER và HYDROLIX_PASSWORD)

Khi nhiều phương pháp xác thực được cấu hình, máy chủ sẽ sử dụng phương pháp khả dụng đầu tiên theo thứ tự ưu tiên trên. Xác thực theo yêu cầu chỉ khả dụng khi sử dụng chế độ transport HTTP hoặc SSE. Dạng ?token= tồn tại cho các máy khách không thể gửi tiêu đề; đặt HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false trên các triển khai nơi mọi máy khách gửi tiêu đề Authorization (xem Thông tin xác thực theo yêu cầu).

Lưu ý: Sử dụng mã thông báo tài khoản dịch vụ với vai trò chỉ đọc được khuyến nghị.

Định nghĩa máy chủ MCP sử dụng tên người dùng và mật khẩu (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>"
  }
}

Định nghĩa máy chủ MCP sử dụng mã thông báo tài khoản dịch vụ (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>"
  }
}

Định nghĩa máy chủ MCP sử dụng tên người dùng và mật khẩu (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>

Định nghĩa máy chủ MCP sử dụng mã thông báo tài khoản dịch vụ (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>

Ví dụ cấu hình (Claude Desktop)

1. Mở tệp cấu hình Claude Desktop nằm tại:

   • Trên macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Trên Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Thêm mục nhập máy chủ mcp-hydrolix vào khối cấu hình mcpServers để sử dụng tên người dùng và mật khẩu:

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

Để tận dụng tài khoản dịch vụ, hãy sử dụng khối cấu hình sau:

{
  "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. Cập nhật các định nghĩa biến môi trường để trỏ đến cụm Hydrolix của bạn.

4. (Khuyến nghị) Định vị mục nhập lệnh cho uvx và thay thế nó bằng đường dẫn tuyệt đối đến tệp thực thi uvx. Điều này đảm bảo rằng phiên bản chính xác của uvx được sử dụng khi khởi động máy chủ. Bạn có thể tìm đường dẫn này bằng which uvx hoặc where.exe uvx.

5. Khởi động lại Claude Desktop để áp dụng các thay đổi. Nếu bạn đang sử dụng Windows, hãy đảm bảo Claude được dừng hoàn toàn bằng cách đóng máy khách bằng biểu tượng khay hệ thống.

Ví dụ cấu hình (Claude Code)

Để cấu hình máy chủ MCP Hydrolix cho Claude Code, hãy chạy lệnh sau:

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

Biến môi trường

Các biến sau được sử dụng để cấu hình kết nối Hydrolix. Các biến này có thể được cung cấp qua khối cấu hình MCP (như hiển thị ở trên), tệp .env hoặc các biến môi trường truyền thống.

Biến bắt buộc

Bạn PHẢI đặt một trong các biến sau để xác định cụm:

• HYDROLIX_URL (khuyến nghị): URL công khai chuẩn của cụm Hydrolix của bạn, ví dụ https://mycluster.hydrolix.live. Đối với các triển khai ngoài cụm điển hình, biến đơn này là đủ — nó cung cấp máy chủ, cổng (mặc định theo scheme 443/80) và cài đặt TLS cho cả điểm cuối truy vấn HTTP và kiểm tra REST /version.
• HYDROLIX_HOST (không dùng nữa): Tên máy chủ của máy chủ Hydrolix của bạn. Vẫn được tôn trọng cho khả năng tương thích ngược nhưng nên được thay thế bằng HYDROLIX_URL.

Khi HYDROLIX_MCP_SERVER_TRANSPORT là http hoặc sse, HYDROLIX_URL cụ thể là bắt buộc (một điểm cuối siêu dữ liệu OAuth sắp tới sẽ quảng cáo nó). Riêng HYDROLIX_HOST là không đủ cho các transport này.

Biến xác thực

Ít nhất một phương pháp xác thực phải được cấu hình khi sử dụng transport stdio:

• HYDROLIX_TOKEN: Mã thông báo tài khoản dịch vụ cho xác thực dựa trên môi trường
• HYDROLIX_USER và HYDROLIX_PASSWORD: Tên người dùng và mật khẩu cho xác thực dựa trên môi trường (cả hai phải được cung cấp cùng nhau)

Tóm lại:

• Đối với stdio, bạn PHẢI sử dụng HYDROLIX_TOKEN hoặc HYDROLIX_USER+HYDROLIX_PASS (thông tin xác thực môi trường)
• Đối với http/sse, bạn CÓ THỂ sử dụng HYDROLIX_TOKEN hoặc HYDROLIX_USER+HYDROLIX_PASS (thông tin xác thực môi trường), nhưng bạn có thể sử dụng thông tin xác thực theo yêu cầu thay thế.

Nếu không có thông tin xác thực nào được cung cấp qua môi trường hoặc yêu cầu, yêu cầu sẽ thất bại.

Sử dụng xác thực theo yêu cầu với transport HTTP

Khi sử dụng transport HTTP hoặc SSE, bạn có thể bỏ qua thông tin xác thực dựa trên môi trường và thay vào đó cung cấp xác thực theo yêu cầu. Điều này hữu ích cho các tình huống nhiều người dùng hoặc với các máy khách không hỗ trợ chạy máy chủ MCP cục bộ.

Ví dụ cấu hình mcpServers kết nối đến máy chủ HTTP từ xa với xác thực theo yêu cầu:

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

Ví dụ cấu hình .env tối thiểu để chạy máy chủ HTTP của riêng bạn mà không có thông tin xác thực môi trường:

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

Mặc dù không phải là một phần của đặc tả MCP, nhiều máy khách MCP cho phép thêm tiêu đề vào các yêu cầu do MCP phát hành. Khi có thể, chúng tôi khuyến nghị cấu hình máy khách MCP để truyền mã thông báo tài khoản dịch vụ qua tiêu đề Authorization: Bearer <sa-token-here> thay vì dưới dạng tham số truy vấn để bảo mật tốt hơn.

Lưu ý: Cài đặt máy chủ bind và cổng chỉ được sử dụng khi transport được đặt thành "http" hoặc "sse".

Biến tùy chọn

Xem docs/CONFIG.md để biết các ghi đè điểm cuối, bí danh biến không dùng nữa và toàn bộ tập hợp các biến điều chỉnh tùy chọn (thời gian chờ, ghi đè cài đặt truy vấn, cắt ngắn kết quả, điều chỉnh worker HTTP/SSE, proxy, số liệu và escape hatches).

Người duy trì

Các tác vụ cần đặc quyền vận hành — chạy bộ kiểm thử toàn diện trên một cụm Hydrolix trực tiếp, và phát hành một bản phát hành — được ghi chép riêng trong MAINTAINERS.md.