# Hướng dẫn cài đặt

Canonical source: https://maguyva.ai/vi/docs/installation

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Sẵn sàng hoạt động trong chưa đầy 5 phút. Hướng dẫn này bao gồm cách thiết lập cho 23 MCP client, trong đó có Claude Code, Claude Desktop, Cursor, VS Code, Devin Desktop, Codex CLI, GitHub Copilot CLI, Gemini CLI, Cline, Goose, Continue, LM Studio, Kiro CLI, JetBrains, Zed, Trae, OpenCode, BoltAI, LibreChat, Antigravity, Claude Cowork, ChatGPT và Warp, và nhiều hơn nữa.

**Yêu cầu trước**: Bạn cần một khóa API từ [app.maguyva.ai](https://app.maguyva.ai) và một GitHub repository đã kết nối.

## Thiết lập môi trường

Trước tiên, đặt khóa API vào biến môi trường. Bỏ `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; ngược lại truyền rõ ràng.

### macOS/Linux (Bash/Zsh)

```bash
export MAGUYVA_API_KEY="mgv_xxxx"
```

### Windows (PowerShell)

```powershell
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE
```

Thay `mgv_xxxx` bằng khóa API thực tế của bạn từ [app.maguyva.ai](https://app.maguyva.ai).

## Cấu hình client

Chọn MCP client của bạn bên dưới để xem hướng dẫn thiết lập chi tiết.

```json
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

Maguyva sử dụng MCP chuẩn. Bất kỳ client nào hỗ trợ giao thức này đều có thể kết nối — kể cả khi không có hướng dẫn chính thức ở trên. 23 client đã được tài liệu hóa, và còn được bổ sung thường xuyên.

## Kiểm chứng thiết lập của bạn

Sau khi kết nối, hãy thử đặt cho agent của bạn vài câu hỏi:

- "Tôi đã kết nối những repository nào?" — xác minh kết nối đang hoạt động
- "Xác thực được xử lý như thế nào trong codebase này?" — kiểm tra semantic search
- "Tìm tất cả các hàm gọi đến database" — kiểm tra dependency search
- "Class UserService phụ thuộc vào những gì?" — kiểm tra symbol lookup

Bạn sẽ thấy kết quả kèm đường dẫn file và số dòng từ repository đã kết nối. Nếu không, hãy kiểm tra [troubleshooting](https://maguyva.ai/vi/docs/troubleshooting) bên dưới.

## Định dạng Repository

Khi chỉ định repository:

- Kèm branch: `"owner/repo:branch"` (e.g. `"owner/repository:develop"`)
- Branch mặc định: `"owner/repo"`

**Mẹo**: dùng `repository_context(action="info", repository="...")` để kiểm tra việc xác định kho mã. Kho mã được chỉ định để ghi đè chỉ áp dụng cho lần gọi hiện tại.

## Khắc phục sự cố

### Sự cố với khóa API

- Kiểm tra khóa của bạn có bắt đầu bằng tiền tố mgv_ hay không
- Kiểm tra khóa đã được thiết lập đúng trong môi trường của bạn
- Đảm bảo khóa chưa hết hạn

### Không tìm thấy Repository

- Kiểm tra repository đã được kết nối trong app.maguyva.ai
- Kiểm tra định dạng owner/repo có đúng không
- Đảm bảo bạn có quyền truy cập repository

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

- Nếu trình khách dùng cầu nối @maguyva/mcp, hãy kiểm tra rằng npx có trong PATH
- Kiểm tra API token của bạn còn hợp lệ và chưa hết hạn
- Kiểm tra kết nối đến https://maguyva.tools/mcp
- Kiểm tra cú pháp cấu hình MCP của client bạn

## Các bước tiếp theo

- Tài liệu tham chiếu MCP API: Tài liệu API đầy đủ
- Cách hoạt động: Tìm hiểu cách tối ưu hóa context
- Khắc phục sự cố: Khắc phục các sự cố thiết lập và kết nối