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, /mcp trả 401 khi request thiếu hoặc sai token; các endpoint OAuth của luồng Web trả 503 khi chưa gắn ingress. Đọc đúng mã giúp tránh sửa mạng khi lỗi nằm ở xác thực, và tránh đổi token khi 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 xuất hiện khi client Web gọi discovery, /authorize, /register hoặc /token mà chưa gắn ingress; nó nằm ở phía bạn, không phải lỗi mạng ngẫu nhiên. Lõi local vẫn chạy bình thườ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 ingress và địa chỉ công khai. Ingress mới gắn (qua panel hoặc cờ --tunnel, biến PUBLIC_ORIGIN) chỉ có hiệu lực sau khi khởi động lại.
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.