Khắc phục sự cố

Hầu hết các lỗi cài đặt rơi vào bốn nhóm: API key không đến được server, cầu nối mcp-remote không khởi động được, repository không thể xác định, hoặc client không thể kết nối được. Hãy đi qua phần tương ứng với triệu chứng của bạn.

Sự cố API key#

Mọi request đều xác thực bằng API key của bạn, được gửi dưới dạng header Authorization: Bearer. Nếu các lời gọi công cụ bị từ chối:

• Kiểm tra key của bạn có bắt đầu bằng tiền tố mgv_ không.
• Kiểm tra bạn đã thay placeholder mgv_xxxx trong các ví dụ cấu hình bằng key thật của bạn từ app.maguyva.ai chưa.
• Nếu cấu hình của bạn đọc key từ MAGUYVA_API_KEY, hãy xác nhận biến đó đã được thiết lập trong môi trường mà client của bạn thực sự khởi chạy từ đó. Các export shell thêm vào ~/.zshrc hoặc ~/.bashrc chỉ có hiệu lực sau khi reload shell — và các ứng dụng GUI có thể không kế thừa chúng chút nào. Nếu không chắc, hãy đặt key vào khối env trong cấu hình.
• Đảm bảo key chưa hết hạn hoặc bị thu hồi.

Sự cố cầu nối mcp-remote#

Hầu hết các cấu hình client đã có tài liệu đều khởi chạy một tiến trình cầu nối cục bộ để chuyển tiếp lưu lượng MCP qua stdio đến server từ xa:

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

Nếu server không bao giờ xuất hiện trong client của bạn, hoặc xuất hiện rồi ngắt kết nối ngay lập tức:

• Kiểm tra npx có sẵn trong PATH của bạn không — cầu nối cần một bản cài đặt Node.js hoạt động được. Chạy npx -y mcp-remote --help trong terminal để xác nhận nó có thể khởi động.
• Kiểm tra cú pháp cấu hình MCP của client — một file JSON sai định dạng sẽ thất bại âm thầm ở một số client.
• Nhiều client không cần cầu nối chút nào. Claude Code dùng plugin Maguyva (/plugin install maguyva@maguyva), còn Cursor, VS Code, Windsurf, và Zed kết nối tới server từ xa một cách gốc bằng header Bearer (Zed thông qua context_servers). Cầu nối chỉ dành cho các client không hỗ trợ header từ xa gốc, chẳng hạn như các connector chỉ dùng OAuth của Claude Desktop.

Không tìm thấy repository#

• Xác nhận repository đã được kết nối và lập chỉ mục trong app.maguyva.ai.
• Kiểm tra định dạng: "owner/repo" nhắm vào nhánh mặc định, "owner/repo:branch" nhắm vào một nhánh cụ thể (ví dụ "owner/repository:develop").
• Đảm bảo tài khoản của bạn có quyền truy cập repository.
• Dùng repository_context(action="info", repository="...") để kiểm tra cách repository được phân giải; chỉ bỏ tham số repository khi MCP client của bạn cung cấp mặc định theo từng yêu cầu hoặc khi khóa có thể truy cập đúng một repository.

Sự cố kết nối MCP#

• Kiểm tra kết nối tới https://maguyva.tools/mcp từ máy của bạn — proxy công ty và firewall thường là thủ phạm.
• Kiểm tra API token của bạn còn hợp lệ và chưa hết hạn.
• Kiểm tra lại cấu hình client so với Hướng dẫn cài đặt dành cho client của bạn — vị trí và định dạng file cấu hình khác nhau tùy client.

Xác minh bản sửa lỗi#

Sau bất kỳ thay đổi nào, hãy hỏi agent của bạn "Tôi đang kết nối những repository nào?" — điều đó xác minh kết nối từ đầu đến cuối. Sau đó hãy đặt một câu hỏi thật về repo của bạn; bạn sẽ thấy các câu trả lời kèm đường dẫn file và số dòng từ repository đã kết nối.