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: khóa API không đến được server, cầu nối @maguyva/mcp 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.

Mọi request đều xác thực bằng khóa API của bạn, được gửi dưới dạng header Authorization: Bearer hoặc, nếu client không đặt được header đó, dưới dạng header X-API-Key. 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 ghi key trực tiếp vào cấu hình: trong header Authorization của cấu hình kết nối từ xa trực tiếp (Bearer rồi đến key của bạn), hoặc trong khối env của cấu hình dùng cầu nối @maguyva/mcp.
• Đảm bảo key chưa hết hạn hoặc bị thu hồi.

Nếu trình khách dùng cầu nối @maguyva/mcp, nó khởi chạy một tiến trình cục bộ kết nối đến máy chủ từ xa của Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

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 @maguyva/mcp --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, Devin Desktop, và Zed kết nối tới server từ xa trực tiếp bằng header Bearer (Zed thông qua context_servers). Cầu nối dành cho các client không thể gửi header đó từ cấu hình của mình, chẳng hạn Claude Desktop, vốn có claude_desktop_config.json chỉ khởi chạy server cục bộ. Connector tùy chỉnh của Claude Desktop có thể gửi request header authorization, nhưng request header đang ở giai đoạn beta cho một số tổ chức giới hạn.

• 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.

• 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.

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.