Khái niệm cơ bản
Hướng dẫn nhanh MCP
Bắt đầu nhanh với MCP server cho logistics: kết nối Claude, Cursor hoặc client MCP bất kỳ với Navo24 để mô hình tự theo dõi container, so sánh chuyến.
Model Context Protocol cho phép trợ lý gọi công cụ trực tiếp. Navo24 có một MCP server cho logistics ở mỗi sản phẩm, nên mô hình có thể theo dõi container, so sánh chuyến tàu hoặc lập kế hoạch xếp hàng mà bạn không cần viết mã kết nối.
Các server
| Sản phẩm | Server | Endpoint | Giao thức truyền |
|---|---|---|---|
| TrackingMCP | container-tracking | https://mcp.trackingmcp.com/mcp | Streamable HTTP |
| SchedulesMCP | ocean-schedules | https://mcp.schedulesmcp.com/mcp | Streamable HTTP |
| LoadingMCP | container-loading | https://mcp.loadingmcp.com/mcp | Streamable HTTP |
| AirCargoMCP | air-cargo | https://mcp.aircargomcp.com/mcp | Streamable HTTP |
| FreightRatesMCP | freight-rates | https://mcp.freightratesmcp.com/mcp | Streamable HTTP |
Trên AirCargoMCP, resolve_awb_prefix trả lời mà không cần khóa; track_awb và air_rate_quote cần khóa thuộc nhóm tmcp_ của bạn.
Claude Desktop và Cursor
Thêm server vào cấu hình client. Với server Streamable HTTP, truyền endpoint và khóa của bạn qua header bearer.
{
"mcpServers": {
"container-tracking": {
"url": "https://mcp.trackingmcp.com/mcp",
"headers": { "Authorization": "Bearer tmcp_YOUR_API_KEY" }
}
}
}Client chỉ chạy được lệnh cục bộ vẫn có thể kết nối tới bất kỳ server nào ở trên qua mcp-remote. Ví dụ với hàng không:
{
"mcpServers": {
"air-cargo": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.aircargomcp.com/mcp",
"--header", "Authorization: Bearer tmcp_YOUR_API_KEY"]
}
}
}Khởi động lại client và các công cụ sẽ xuất hiện. Nhờ nó theo dõi một container, nó sẽ tự gọi get_container_detail.
Mô hình có thể gọi những gì
Mỗi server cung cấp cùng khả năng như REST API, dưới dạng công cụ. Tracking có add_container, get_container_detail, get_shipment_summary và nhiều hơn. Schedules có find_best_sailings, carrier_reliability và port_congestion. Danh sách công cụ đầy đủ nằm trên trang tham chiếu của từng sản phẩm.
Cùng khóa, cùng dữ liệu
Một lệnh gọi công cụ MCP và một lệnh gọi REST đến cùng backend với cùng khóa. Dùng MCP khi mô hình điều khiển công việc, và REST khi mã của bạn làm việc đó.
Navo Tokens
Với tài khoản có Navo Tokens, một số dư trả trước dùng chung cho các sản phẩm Navo, các lệnh gọi MCP được trả từ số dư đó. Các trường JSON mô tả số dư vẫn giữ tên bắt đầu bằng credits_.
Một số dư mở mọi dịch vụ Navo qua MCP: TrackingMCP, AirCargoMCP, FreightRatesMCP, SchedulesMCP và LoadingMCP. Bạn không cần quyền truy cập MCP riêng cho từng sản phẩm. Vẫn có hai trường hợp khiến lệnh gọi bị từ chối: sản phẩm mà quản lý tài khoản đã đóng cho tài khoản của bạn, và khóa có phạm vi không bao gồm sản phẩm đó (xem phần Quyền truy cập theo sản phẩm bên dưới).
Mức sử dụng MCP và API được tính riêng. Một lệnh gọi MCP không bao giờ trừ vào hạn mức lệnh gọi hàng tháng của khóa API, và một lệnh gọi REST bằng khóa API không bao giờ tiêu Navo Tokens.
| Lệnh gọi | Tokens |
|---|---|
| Theo dõi một container, vận đơn hoặc booking mới | 250 |
| Làm mới hoặc đọc một lô hàng đang theo dõi | 10 cho mỗi mã tham chiếu |
| Theo dõi một vận đơn hàng không mới | 200 |
| Làm mới một vận đơn hàng không | 10 |
| Giá cước cho một cặp cảng | 100, hoặc 10 nếu tra lại cùng cặp cảng trong vòng 24 giờ |
| Lịch tàu cho một cặp cảng | 80, hoặc 10 nếu tra lại cùng cặp cảng trong vòng 24 giờ |
| Một kế hoạch xếp hàng 3D mới | 50, hoặc 10 cho mỗi lần tính lại |
| Tình trạng ùn tắc cảng | 10 |
| Độ tin cậy lịch tàu, các chuyến của một hãng tàu | 10 |
| Cảnh báo và webhook | miễn phí |
Công cụ nhận nhiều mã tham chiếu sẽ tính phí một lần cho mỗi mã tham chiếu duy nhất bạn đã gửi. Một booking hoặc một vận đơn chỉ tính phí một lần cho tất cả container của nó. Kết quả rỗng thì miễn phí, và lệnh gọi bị từ chối không bị tính phí. Các gói và giá có trên trang bảng giá.
Khi số dư không đủ để thanh toán
Lệnh gọi bị từ chối, không bị tính phí và không có dữ liệu nào được trả về. Mã lỗi tùy theo sản phẩm:
| Sản phẩm | Từ chối |
|---|---|
| TrackingMCP | 402 INSUFFICIENT_CREDITS |
| AirCargoMCP | 402 với mã insufficient_balance (hoặc trial_expired, wallet_inactive, no_wallet) |
| FreightRatesMCP | 402 với mã insufficient_credits (hoặc trial_expired, wallet_inactive, no_wallet) |
| SchedulesMCP | 429 QUOTA_EXCEEDED trước khi đọc bất kỳ dữ liệu nào, hoặc 402 INSUFFICIENT_CREDITS khi số dư không còn đủ để thanh toán lúc câu trả lời đã sẵn sàng |
| LoadingMCP | 402 INSUFFICIENT_CREDITS, bị từ chối trước khi tính kế hoạch |
Trên mọi sản phẩm, ngoài code và message, đối tượng error còn mang cùng bốn trường tùy chọn:
| Trường | Kiểu | Nội dung |
|---|---|---|
credits_required | integer hoặc null | Số tokens lệnh gọi này cần; null khi chưa biết giá. |
credits_balance | integer hoặc null | Số tokens hiện có trong số dư của bạn; null khi tài khoản chưa có số dư. |
top_up_url | string hoặc null | Trang Billing trong cài đặt tài khoản, nơi bạn mua thêm tokens; null khi không thể cung cấp liên kết. |
packages | mảng { plan, credits, usd } | Các gói bạn có thể mua: Starter 7,000 tokens giá $69, Growth 40,000 tokens giá $349, Scale 200,000 tokens giá $1,399. |
{
"ok": false,
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough Navo Tokens: this needs 10, your balance is 4. Buy more tokens: https://app.trackingmcp.com/settings?tab=billing&buy=credits (Starter 7,000 tokens for $69, Growth 40,000 tokens for $349, Scale 200,000 tokens for $1,399).",
"severity": "warning",
"credits_required": 10,
"credits_balance": 4,
"top_up_url": "https://app.trackingmcp.com/settings?tab=billing&buy=credits",
"packages": [
{ "plan": "starter", "credits": 7000, "usd": 69 },
{ "plan": "growth", "credits": 40000, "usd": 349 },
{ "plan": "scale", "credits": 200000, "usd": 1399 }
]
}
}Các trường này được bổ sung thêm và là tùy chọn: hãy tiếp tục rẽ nhánh theo code, và đọc chúng khi có mặt. Mọi Navo MCP server đều chuyển chúng thành cùng một câu mà bạn có thể hiển thị nguyên văn cho người dùng: “Not enough Navo Tokens: this needs 10, your balance is 4. Buy more tokens: <link> (Starter 7,000 tokens for $69, Growth 40,000 tokens for $349, Scale 200,000 tokens for $1,399).” Trang tham chiếu của từng sản phẩm có chi tiết trong mục Navo Tokens.
Quyền truy cập theo sản phẩm
Navo Tokens không cần quyền truy cập MCP theo từng sản phẩm. Sản phẩm mà quản lý tài khoản đã đóng cho tài khoản của bạn vẫn bị đóng khi dùng Navo Tokens, ví dụ “Ship Schedules is not enabled for MCP on this account. Ask your account manager.” trên SchedulesMCP. Khóa có phạm vi không bao gồm một sản phẩm sẽ bị từ chối với 403, ví dụ “Ship Schedules is not enabled for this API key.” trên SchedulesMCP và “Freight Rates is not enabled for this API key. Contact your account manager to open it.” trên FreightRatesMCP.