Nối API vào LLM
Một máy chủ MCP duy nhất mở toàn bộ 455 endpoint tra cứu cho trợ lý của bạn — Claude, ChatGPT, Cursor hay bất kỳ client nào nói chuẩn Model Context Protocol. Không phải viết lớp trung gian, không phải dán tài liệu vào prompt, và quan trọng nhất: không phải trả tiền ngữ cảnh cho 455 định nghĩa tool mà model gần như không bao giờ dùng tới.
Model nhận đúng 4 tool. Nó tìm endpoint khi cần, đọc đặc tả của riêng endpoint đó, rồi mới gọi. Chi phí ngữ cảnh cố định 2.562 byte, bất kể danh mục có bao nhiêu API.
Ngân sách ngữ cảnh
| Cửa sổ ngữ cảnh | Với 4 meta-tool | Nếu phơi từng endpoint |
|---|---|---|
| 200.000 token | 0,43% · 854 token | 36,7% · 73.315 token |
| 1.000.000 token | 0,09% · 854 token | 7,3% · 73.315 token |
Byte đo bằng cách mã hoá JSON đúng mảng định nghĩa tool mà máy chủ trả về ở tools/list, và mã hoá cùng cách cho từng endpoint trong danh mục nếu chúng được phơi thành tool riêng. Không phải ước lượng mượn ở đâu — danh mục đổi thì con số trên trang này đổi theo.
Token quy đổi 3 byte ≈ 1 token. Mô tả của chúng tôi là tiếng Việt có dấu, mỗi ký tự có dấu chiếm 2–3 byte UTF-8 và bị cắt vụn hơn ASCII, nên tỷ lệ này cố ý ước lượng cao chi phí của chính chúng tôi. Bộ tách token của mỗi hãng một khác, vì vậy con số đáng tin nhất trên trang là tỷ lệ 1,16% giữa hai cách nạp — nó là byte chia byte nên không phụ thuộc bộ tách token nào.
Khai báo MCP server
Máy chủ nói Streamable HTTP và phục vụ đồng thời hai thời kỳ giao thức: bản không phiên 2026-07-28 và bản bắt tay initialize từ 2025-11-25 trở về trước. Bạn không cần biết client của mình thuộc thời kỳ nào — máy chủ tự nhận ra qua cách client mở đầu.
claude mcp add --transport http hitechcloud https://doc-api-tools.hitechcloud.vn/mcp \ --header "X-API-Key: $HITECHCLOUD_API_KEY"
{
"mcpServers": {
"hitechcloud": {
"type": "http",
"url": "https://doc-api-tools.hitechcloud.vn/mcp",
"headers": { "X-API-Key": "${HITECHCLOUD_API_KEY}" }
}
}
}
{
"mcpServers": {
"hitechcloud": {
"command": "npx",
"args": ["-y", "@hitechcloud/cli", "mcp", "--bo", "api-tools"],
"env": { "HITECHCLOUD_API_KEY": "${HITECHCLOUD_API_KEY}" }
}
}
}
[mcp_servers.hitechcloud] url = "https://doc-api-tools.hitechcloud.vn/mcp" bearer_token_env_var = "HITECHCLOUD_API_KEY" startup_timeout_sec = 20 tool_timeout_sec = 120
{
"model": "gpt-5",
"tools": [
{
"type": "mcp",
"server_label": "hitechcloud",
"server_url": "https://doc-api-tools.hitechcloud.vn/mcp",
"authorization": "<khoá API của bạn>",
"allowed_tools": ["tim_endpoint", "mo_ta_endpoint", "goi_endpoint", "liet_ke_nhom"],
"require_approval": {
"never": { "tool_names": ["tim_endpoint", "mo_ta_endpoint", "liet_ke_nhom"] }
}
}
],
"input": "Tra cứu mã số thuế 0316954486 và cho biết doanh nghiệp còn hoạt động không."
}
# Responses API (định nghĩa phẳng, có "strict") curl -s -X POST "https://doc-api-tools.hitechcloud.vn/mcp/tools" -d "api_key=$HITECHCLOUD_API_KEY" # Chat Completions (định nghĩa lồng trong khoá "function") curl -s -X POST "https://doc-api-tools.hitechcloud.vn/mcp/tools?chuan=chat" -d "api_key=$HITECHCLOUD_API_KEY"
{
"mcpServers": {
"hitechcloud": {
"url": "https://doc-api-tools.hitechcloud.vn/mcp",
"headers": { "X-API-Key": "${HITECHCLOUD_API_KEY}" }
}
}
}
Xác thực delegated
Khoá đi trong header của mỗi lượt POST tới MCP endpoint, do client gắn vào — không đi qua model, không nằm trong lịch sử hội thoại. Máy chủ nhận cả X-API-Key lẫn Authorization: Bearer với cùng một khoá, vì mỗi client chỉ biết gắn một trong hai kiểu.
- Viết tên biến môi trường trong tệp cấu hình — "${HITECHCLOUD_API_KEY}" — rồi đặt giá trị thật ở môi trường của máy, không ở kho mã.
- Bật giới hạn IP cho khoá dùng trên máy chủ. Khoá tĩnh không tự hết hạn, danh sách IP là thứ duy nhất chặn được khoá lỡ rò rỉ đang chạy từ nơi khác.
- Tạo khoá riêng cho từng agent và chỉ bật đúng nhóm dịch vụ nó cần. Thu hồi một khoá lúc đó không làm gãy phần còn lại.
- Với token ngắn hạn hoặc SSO nội bộ, dùng headersHelper của Claude Code và chỉ đặt ở phạm vi user — nó thực thi lệnh shell tuỳ ý, đặt trong tệp dùng chung là mọi người kéo kho mã về đều chạy lệnh của bạn.
- Dán khoá thật vào .mcp.json hay .cursor/mcp.json. Hai tệp này nằm ở gốc dự án và bị commit theo mặc định; khoá đã lên kho mã thì xoá dòng đó đi cũng không thu hồi được, chỉ còn cách huỷ khoá.
- Truyền khoá như một tham số của tool. Tham số đi vào ngữ cảnh model, được ghi trong nhật ký hội thoại và có thể bị moi ra bằng prompt injection.
- Nhét khoá vào query string của URL. Nó nằm lại trong nhật ký máy chủ, lịch sử trình duyệt và mọi đường dẫn lỡ chia sẻ.
- Chuyển tiếp token của một dịch vụ khác sang đây và mong nó chạy. Máy chủ chỉ chấp nhận khoá cấp cho chính nó — nhận token của nơi khác chính là lỗ hổng confused deputy mà đặc tả cấm.
4 meta-tool
Đây là toàn bộ những gì model nhìn thấy. Trình tự bắt buộc: tim_endpoint → mo_ta_endpoint → goi_endpoint. Tập tool không đổi theo người gọi — đặc tả cấm điều đó; phân quyền áp ở kết quả tìm kiếm và ở lúc gọi thật, để model nhận một lỗi rõ ràng thay vì kết luận "hệ thống không làm được việc này".
| Tool | Việc nó làm | Tham số |
|---|---|---|
| tim_endpoint Tìm endpoint | Tìm endpoint trong danh mục 455 endpoint theo từ khoá hoặc nhóm dịch vụ. Trả về danh sách gọn: id, phương thức, đường dẫn và tóm tắt một dòng. Gọi tool này TRƯỚC khi dùng mo_ta_endpoint hoặc goi_endpoint. |
tu_khoa
string
bắt buộc
nhom
string
gioi_han
integer
|
| mo_ta_endpoint Mô tả endpoint | Trả đặc tả đầy đủ của MỘT endpoint: phương thức, đường dẫn, từng tham số (vị trí, kiểu, bắt buộc hay không), mã lỗi có thể gặp và ví dụ gọi. Gọi trước goi_endpoint để biết chính xác tên tham số. |
id
string
bắt buộc
|
| goi_endpoint Gọi endpoint | Thực thi một endpoint trong danh mục và trả về kết quả thật. Chỉ gọi sau khi đã đọc đặc tả bằng mo_ta_endpoint. Tham số đường dẫn, tham số truy vấn và trường thân yêu cầu đều đặt chung trong "tham_so"; máy chủ tự xếp từng giá trị về đúng chỗ theo đặc tả của endpoint. |
id
string
bắt buộc
tham_so
object
|
| liet_ke_nhom Liệt kê nhóm dịch vụ | Liệt kê các nhóm dịch vụ kèm số endpoint mỗi nhóm. Dùng để định hướng khi chưa biết nên tìm từ khoá nào. | không có |
Dùng qua CLI
Cùng 4 meta-tool, nhưng chạy trên máy bạn qua stdio thay vì gọi HTTP. Dành cho client chỉ nói stdio, cho máy nằm sau tường lửa không mở được ra ngoài, và cho lúc bạn muốn nhìn thấy từng lời gọi trước khi nó rời máy.
# Lưu khoá một lần, quyền 0600, ngoài thư mục dự án npx -y @hitechcloud/cli auth login --bo api-tools # Chạy như một MCP server qua stdio npx -y @hitechcloud/cli mcp --bo api-tools # Hoặc dùng thẳng ngoài dòng lệnh, không cần model npx -y @hitechcloud/cli tim "mã số thuế" npx -y @hitechcloud/cli mo-ta <id endpoint> npx -y @hitechcloud/cli goi <id endpoint> --tham-so mst=0316954486 --json
Khoá lưu ở thư mục cấu hình của hệ điều hành, không nằm trong dự án, nên không có đường nào lọt vào kho mã. Mã thoát tách riêng cho lỗi xác thực, lỗi mạng và vượt hạn mức, để script CI phân biệt được "phải báo người" với "cứ thử lại" mà không phải đọc thông điệp lỗi.