Lỗi MCP 401 và 503: cách phân biệt token với ingress
Lỗi MCP 401 báo token không hợp lệ, còn 503 báo ingress chưa sẵn sàng cho kết nối Web. Quy trình kiểm tra Local trước, Web sau để tìm đúng lớp lỗi.
Khi kết nối MCP thất bại, 401 và 503 chỉ hai nguyên nhân khác nhau. Trong AkiMCP 2.1, 401 được dùng rõ cho token sai; 503 được dùng khi một kết nối Web cần ingress nhưng ingress chưa sẵn sàng. Đọc đúng mã giúp tránh sửa mạng khi lỗi nằm ở thông tin xác thực — hoặc đổi token khi lớp ingress mới là phần chưa chạy.
MCP trả 401: kiểm tra token
401 Unauthorized nghĩa là request đã tới Gatekeeper nhưng token không được chấp nhận. Hãy sao chép lại token từ panel, kiểm tra không có khoảng trắng thừa và chắc rằng connector đang dùng đúng giá trị hiện tại.
Không chuyển sang sửa ingress trước khi 401 biến mất. Mã này cho thấy đường mạng đã đưa request tới lớp xác thực.
MCP trả 503: kiểm tra ingress
503 Service Unavailable trong luồng Web nghĩa là ingress cần thiết chưa sẵn sàng. Lõi local vẫn có thể hoạt động trên 127.0.0.1; hãy kiểm tra connector có thuộc nhóm Web không, rồi mới kiểm tra trạng thái ingress và địa chỉ công khai.
Quy trình chẩn đoán ngắn nhất
- ◆Thử connector Local trên cùng máy để xác nhận Gatekeeper và token.
- ◆Nếu nhận 401, sửa token trước; chưa cần đụng tới ingress.
- ◆Nếu Local chạy nhưng Web nhận 503, kiểm tra ingress và endpoint Web.
- ◆Chỉ kiểm tra tool hoặc quyền shell sau khi kết nối và xác thực đã thành công.
Cách tách lỗi này đi cùng kiến trúc local-first của 2.1: Local không bị chặn chỉ vì ingress vắng mặt, còn Web báo đúng lớp chưa sẵn sàng. Đọc MCP local-first là gì để chọn đúng nhóm connector.