Máy chủ MCP

Zelnum cung cấp máy chủ MCP công khai tại https://mcp.zelnum.com/mcp. Mọi client hỗ trợ MCP — Claude, Cursor, agent trong IDE — đều có thể liệt kê sản phẩm, hỏi giá một lượt kiểm tra, chạy nó và đọc kết quả mà không cần viết mã tích hợp. Một địa chỉ dùng chung cho mọi khách hàng: bạn kết nối bằng API key của chính mình và mọi khoản phí đều trừ vào số dư của bạn.

Điểm kết nối

Thiết lập	Giá trị
URL	`https://mcp.zelnum.com/mcp`
Giao vận	Streamable HTTP
Thông tin xác thực	`Authorization: Bearer YOUR_KEY_HERE`

Thông tin xác thực chính là API key bạn dùng cho các lệnh gọi REST. Hãy tạo, cấp lại và thu hồi nó trong mục API Center của console.

Kết nối client

Ba bước, không cần cài đặt gì.

1. Tạo key. Tạo một API key trong mục API Center của console — chính là key mà các lệnh gọi REST của bạn dùng. Xem Authentication.

2. Thêm máy chủ. Cursor và những client đọc bản đồ mcpServers tiêu chuẩn có thể dùng nguyên mục này:

{
  "mcpServers": {
    "zelnum": {
      "url": "https://mcp.zelnum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

Claude nhận đúng hai giá trị đó trong hộp thoại custom connector — địa chỉ URL, và header Authorization mang key của bạn.

3. Kiểm tra kết nối. Yêu cầu agent cho biết nó có thể kiểm tra những sản phẩm thời gian thực nào. Kết nối hoạt động sẽ trả lời bằng cách gọi list_products — công cụ chỉ đọc và miễn phí, nên lần tự kiểm tra này không tốn đồng nào. Nếu nhận 401 thì nghĩa là key bị thiếu, đã thu hồi, hoặc nền tảng không chấp nhận.

Các công cụ

Công cụ	Chức năng	Tính phí
`list_products`	Danh mục sản phẩm đang hoạt động kèm ID, slug và series. Chỉ đọc.	Không
`get_balance`	Số dư của tài khoản mà kết nối đang xác thực. Chỉ đọc.	Không
`quote_realtime_check`	Giá chính thức cho một lượt kiểm tra. Nguồn giá duy nhất mà agent nên tin.	Miễn phí
`check_realtime`	Chạy một lượt kiểm tra thời gian thực với tối đa mười sản phẩm.	Có
`create_bulk_task`	Gửi một danh sách nội tuyến cho tác vụ hàng loạt bất đồng bộ.	Có
`get_task_status`	Tiến độ và các bộ đếm tính phí của một tác vụ hàng loạt.	Không
`get_task_result`	Siêu dữ liệu kết quả và liên kết tải xuống có xác thực của một tác vụ đã xong.	Không

Bạn có thể nói như thế này

Trên kia là các công cụ; dưới đây là những câu bạn gõ. Mỗi câu đều do một công cụ đã tồn tại phục vụ — không có cách diễn đạt nào được xử lý riêng.

Nói như vậy	Điều gì xảy ra
Hiện tại có thể kiểm tra thời gian thực những sản phẩm nào?	Gọi `list_products` và trả về các ID cần dùng. Miễn phí.
Số dư tài khoản của tôi còn bao nhiêu?	Gọi `get_balance` cho key mà bạn đã kết nối. Miễn phí.
Kiểm tra `+14155550123` trên WhatsApp tốn bao nhiêu?	Gọi `quote_realtime_check` và hiển thị giá. Miễn phí, không trừ tiền.
Được, làm theo mức giá đó.	Gọi `check_realtime` theo các sản phẩm trong báo giá và trừ đúng số tiền đã báo.
Kiểm tra 200 số này trên WhatsApp rồi cho tôi biết khi xong.	Gọi `create_bulk_task`, sau đó hỏi `get_task_status` và báo tiến độ.
Tác vụ đó xong chưa? Gửi cho tôi link tải.	Gọi `get_task_result` và trả về link tải có xác thực.

Hai thói quen nên giữ:

Hỏi giá trước. Mọi công cụ tính phí đều trả về báo giá trước khi trừ tiền, nên câu hỏi tốn bao nhiêu luôn miễn phí. Chỉ bước xác nhận mới thực sự trừ tiền.
Nêu country khi số không ở dạng E.164. +14155550123 đã mang sẵn quốc gia; 0812345678 thì không, và gateway từ chối đoán.

Xác nhận một khoản phí

Công cụ tính phí không bao giờ trừ tiền ngay ở lần gọi đầu. Khi được gọi mà không có confirmed, nó trả về payload xác nhận — sản phẩm, số lượng và chi phí ước tính — cùng một quote_token ký chính xác dữ liệu đầu vào. Xác nhận bằng cách lặp lại đúng lệnh gọi đó với:

confirmed đặt thành true
quote_token từ payload đó
quoted_total, đúng bằng số tiền đã hiển thị cho bạn
cùng số điện thoại hoặc email, cùng sản phẩm và cùng trường country

Agent không bao giờ tự cấp idempotency key: gateway suy ra nó từ báo giá đã ký, nên cùng một báo giá đã được duyệt sẽ giữ nguyên key qua các lần thử lại, kết nối lại và khởi động lại gateway. Một khoản phí khác cần một báo giá mới. Nếu hết thời gian chờ mà kết quả vẫn chưa rõ, hãy lặp lại y nguyên lệnh gọi đó thay vì đổi tham số.

Định dạng số điện thoại và email

Quy tắc định danh phản chiếu đúng hợp đồng REST, nên thứ agent kiểm tra hợp lệ cũng chính là thứ API chấp nhận:

Không truyền country — định danh phải là số E.164 có tiền tố +.
Có truyền country — mã ISO hai chữ cái viết hoa; khi đó định danh có thể là số nội địa hoặc số E.164.
Hệ thống không bao giờ suy ra quốc gia từ một số nội địa mơ hồ như 0812345678 vì nhiều quốc gia cùng khớp. Chỉ bỏ country khi bản thân số đã là E.164 đầy đủ.
Tác vụ hàng loạt trên sản phẩm điện thoại bắt buộc phải truyền country.

Các rào chắn tiền

Có bốn rào chắn nằm giữa agent và số dư của bạn:

Báo giá có chữ ký. Nền tảng đọc giá trực tiếp và trả về một báo giá được mã hóa, gắn chặt tài khoản, dữ liệu đầu vào chính xác, sản phẩm và ảnh chụp giá. Dữ liệu đầu vào bị sửa, báo giá hết hạn hay giá đã dịch chuyển đều bị từ chối trước khi bất kỳ khoản nào bị trừ.
Idempotency tất định. Idempotency key đến từ báo giá đã ký chứ không phải từ mô hình, nên không cách diễn đạt nào của yêu cầu có thể biến một lần duyệt thành hai khoản phí.
Giới hạn theo từng key. Mức trần chi tiêu hằng ngày và mức sàn số dư được áp riêng cho từng API key, và mỗi lần giữ chỗ đều được tuần tự hóa trước khi gọi lên nền tảng, nên các agent chạy song song không thể vượt qua.
Hỏng là từ chối. Nếu không đọc được số dư, hoặc số dư trả về sai định dạng, các lệnh gọi tính phí sẽ bị từ chối thay vì chạy mà không có bảo vệ.

Lỗi và giới hạn

Thông tin xác thực thiếu hoặc sai định dạng bị từ chối bằng HTTP 401 trước khi yêu cầu tới được nền tảng.
Key mà nền tảng không chấp nhận sẽ trả về dưới dạng lỗi công cụ kèm mã trạng thái và nội dung phản hồi từ nền tảng, nên agent báo lại thay vì thử lại một cách mù quáng.
Giới hạn tần suất, mã lỗi và việc tải kết quả hoạt động y hệt như qua REST — gateway không thêm một hợp đồng thứ hai nào để phải học.

Bước tiếp theo

Authentication — tạo key bạn sẽ dùng để kết nối.
Realtime check — endpoint đứng sau check_realtime.
Bulk workflow — đường bất đồng bộ đứng sau create_bulk_task.
Error codes — các mã lỗi mà nền tảng trả về.