Lỗi MCP chia thành các nhóm truyền tải, xác thực, scope/gói, hạn mức và lệnh gọi công cụ. Đối chiếu mã lỗi dưới đây trước khi thay đổi mã client.
Cần làm gì khi dịch vụ không khả dụng?
Phản hồi 503 cho biết dịch vụ chưa khả dụng. Xác nhận URL công khai, tạm dừng gọi và thử lại sau với thời gian chờ tăng dần và số lần giới hạn. Nếu vẫn lỗi, liên hệ hỗ trợ kèm thời điểm và mã yêu cầu đã loại bỏ dữ liệu nhạy cảm.
Vì sao kiểm tra host hoặc origin thất bại?
- Dùng đúng
https://app.dureach.com/mcpvới ứng dụng MCP hỗ trợ streamable HTTP. - Hoàn tất đồng ý OAuth cho không gian làm việc dự định; lưu thông tin xác thực trong kho được bảo vệ của ứng dụng hoặc trình quản lý bí mật phía máy chủ.
- Nếu máy chủ hoặc nguồn bị từ chối, kiểm tra URL kết nối và liên hệ hỗ trợ. Không xóa hoặc giả mạo tiêu đề bảo mật để vượt qua việc từ chối.
- Giữ
request_idtrong phản hồi để chẩn đoán; không đưa mã thông báo hay hàng dữ liệu vào nhật ký dùng chung.
Vì sao xác thực thất bại?
| Triệu chứng | Ý nghĩa | Cách khắc phục |
|---|---|---|
401, không có chi tiết request_id | Token thiếu, hết hạn, bị thu hồi hoặc sai audience. | Hoàn tất lại quy trình đồng ý OAuth; xác nhận audience là tài nguyên /mcp (/.well-known/oauth-protected-resource/mcp); gửi Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN. |
Khóa REST API được chấp nhận ở nơi khác, bị từ chối trên /mcp | Khóa API không có hiệu lực cho MCP. | Dùng bearer token OAuth. Khóa API chỉ có hiệu lực cho các tuyến đường REST đã được tài liệu hóa. |
workspace_context_required (403) | X-Workspace-ID không khớp với workspace của token. | Gửi ID workspace của token hoặc bỏ header. Token không bao giờ có hiệu lực chéo giữa các workspace. |
Vì sao công cụ bị thiếu hoặc bị từ chối?
| Triệu chứng | Ý nghĩa | Cách khắc phục |
|---|---|---|
Công cụ không xuất hiện trong tools/list | Không khả dụng cho kết nối này. | Kiểm tra quyền đã cấp và quyền truy cập không gian làm việc với quản trị viên. |
Unknown tool (INVALID_PARAMS) | Tên thiếu tiền tố dureach. hoặc không thuộc 14 công cụ. | Gửi tên đầy đủ (ví dụ, dureach.trade.search). Bí danh companies.list được phân giải thành companies.search; các tên khác bị từ chối. |
scope_required | Token thiếu scope của công cụ. | Xem xét và chỉ cấp quyền công cụ cần. Không mở rộng truy cập chỉ để hết lỗi. |
plan_capability_required (403) | Workspace thiếu năng lực nền tảng agent. | Yêu cầu quản trị viên bật năng lực hoặc đổi gói. |
invalid_arguments | Giá trị ngoài phạm vi, truy vấn ngắn, trường không xác định hoặc SQL quá lớn. | Đối chiếu với bảng công cụ; truy vấn cần từ 3 ký tự trở lên, trang và giới hạn phải nằm trong phạm vi, SQL phải nằm trong 16 KiB và tuân thủ ngữ pháp chỉ đọc. |
company_not_found | ID của companies.read không xác định. | Xác nhận UUID đến từ companies.search trong cùng workspace. |
policy_not_found / policy_not_authorized | Lượt gửi R3 chỉ định chính sách không xác định, bị thu hồi, hết hạn hoặc không khớp. | Truyền policy_id của chính sách đang ACTIVE đã được chủ sở hữu xem xét và gắn với OAuth client này, chạy thử trước với dry_run: true, sau đó thử lại với cùng khóa idempotency. |
policy_budget_exceeded / policy_daily_cap_exceeded | Hạn mức gửi của chính sách đã dùng hết. | Chờ sang cửa sổ ngày tiếp theo hoặc đề nghị chủ sở hữu xem xét hạn mức; không chia lượt gửi sang chính sách mới để lách hạn mức. |
recipient_suppressed / recipient_already_attempted | Người nhận đã từ chối, email bị trả lại, không phải lead đang hoạt động, hoặc đã được thử gửi theo chính sách này. | Loại bỏ người nhận và xem xét trạng thái chặn; không bao giờ thử lại cùng người nhận theo chính sách mới. |
result_too_large | Kết quả trên đường truyền vượt 1 MiB. | Thu hẹp cột/bộ lọc hoặc giảm limit. |
quota_exceeded (429) | Ngân sách theo phút, giờ hoặc ngày đã dùng hết. | Tuân thủ Retry-After; chi tiết gồm limit_type, reset_at, retry_after. Xem Phê duyệt, chính sách và hạn mức MCP. |
| Thân yêu cầu bị từ chối hoặc bị cắt ngắn | Yêu cầu vượt 256.000 byte. | Rút ngắn SQL hoặc tham số; chia nhỏ lệnh gọi. |
Nên gửi gì cho bộ phận hỗ trợ?
Bao gồm request_id (hoặc x-request-id), dấu thời gian, tên công cụ, page/limit hoặc cấu trúc SQL (không kèm định danh khách hàng khi có thể), trạng thái HTTP và mã lỗi. Không bao giờ kèm bearer token, bản ghi liên hệ đầy đủ hoặc payload webhook.