Làm thế nào để xử lý vấn đề trong mụ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

Làm thế nào để xử lý vấn đề trong mục «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

Làm thế nào để xử lý vấn đề trong mục «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

Làm thế nào để kiểm chứng thiết lập MCP của Maguyva đang hoạt động?

Sau khi kết nối, hãy đặt cho agent của bạn các prompt sử dụng những chế độ truy xuất khác nhau: "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.

Làm thế nào để chỉ định một repository trong các request MCP của Maguyva?

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. Ngược lại, dùng "owner/repo" cho nhánh mặc định (ví dụ "owner/repository"), hoặc "owner/repo:branch" cho một nhánh cụ thể (ví dụ "owner/repository:develop").

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

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 / GitHub Copilot và Devin Desktop (Windsurf), 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 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)

# Add to your shell profile for persistence:
echo 'export MAGUYVA_API_KEY="mgv_xxxx"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # reload

Windows (PowerShell)

# Make it persist in your profile:
'$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.

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.

Lưu ý về khả năng tương thích: Maguyva dùng chuẩn MCP thông thường. Bất kỳ client nào hỗ trợ MCP đều có thể kết nối tới cùng một server, ngay cả khi chúng tôi chưa viết hướng dẫn cài đặt chính thức cho nó.

Claude Code

Cài đặt plugin Maguyva từ Claude Code marketplace:

Thêm marketplace của Maguyva, rồi cài đặt plugin (chạy từng lệnh bên trong Claude Code):

/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

/plugin install mở phần chi tiết của plugin, nơi bạn chọn phạm vi cài đặt: chỉ bạn (user), mọi người làm việc trong repository này (project), hoặc chỉ bạn trong repository này (local). Các lệnh trong phiên này không có cờ --scope.

Plugin xác thực thông qua biến môi trường MAGUYVA_API_KEY. Thiết lập nó trong shell của bạn:

export MAGUYVA_API_KEY=mgv_xxxx

Khuyến nghị dùng direnv theo từng dự án (.envrc) — các key được giới hạn theo repository, nên một giá trị riêng cho từng dự án sẽ khớp với quyền truy cập của từng dự án. Một export shell toàn cục cũng hoạt động nếu một key bao phủ toàn bộ công việc của bạn.

Với một team, bạn cũng có thể chạy dạng shell của cả hai lệnh từ thư mục gốc của repository, bên ngoài Claude Code:

claude plugin marketplace add maguyva/agent-plugins --scope project
claude plugin install maguyva@maguyva --scope project

Phạm vi project ghi plugin vào .claude/settings.json của repository, tệp mà bạn commit. Việc này bật plugin cho đồng đội nhưng không tải nó về, nên mỗi đồng đội cần chạy lệnh cài đặt một lần.

Thủ công (.mcp.json) — nâng cao

claude mcp add

claude mcp add --transport http maguyva https://maguyva.tools/mcp --header 'Authorization: Bearer ${MAGUYVA_API_KEY}'

.mcp.json

{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Maguyva bổ sung gì cho Claude Code →

Tài liệu MCP của Claude Code →

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Thêm vào file cấu hình Claude Desktop của bạn:

claude_desktop_config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

claude_desktop_config.json chỉ khởi động máy chủ cục bộ, nên thiết lập này dùng cầu nối @maguyva/mcp (cần Node.js / npx). Claude Desktop cũng có thể kết nối Maguyva dưới dạng connector tùy chỉnh (Customize → Connectors) với request header authorization, nhưng request header đang ở giai đoạn beta cho một số tổ chức giới hạn.

Maguyva bổ sung gì cho Claude Desktop →

Tài liệu MCP của Claude Desktop →

Cursor

macOS: ~/.cursor/mcp.json
Windows: %UserProfile%\.cursor\mcp.json
Linux: ~/.cursor/mcp.json

Thêm vào .cursor/mcp.json ở thư mục gốc dự án:

.cursor/mcp.json

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

Cấu hình này đọc key của bạn từ biến môi trường MAGUYVA_API_KEY. Hãy đặt biến này thành khóa API của bạn từ app.maguyva.ai trong môi trường mà client của bạn khởi chạy.

Maguyva bổ sung gì cho Cursor →

Tài liệu MCP của Cursor →

VS Code / GitHub Copilot

Thêm vào .vscode/mcp.json trong dự án, hoặc vào mcp.json của profile (chạy MCP: Open User Configuration):

.vscode/mcp.json

{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

Đây là định dạng VS Code (khóa servers). VS Code lấy tham chiếu MAGUYVA_API_KEY từ môi trường lúc nó khởi động. Luồng Add Server giờ ưu tiên .mcp.json di động (khóa mcpServers) mà GitHub Copilot CLI cũng đọc; tệp đó không hỗ trợ biến nhập hay tệp môi trường của VS Code.

Maguyva bổ sung gì cho VS Code / GitHub Copilot →

Tài liệu MCP của VS Code / GitHub Copilot →

Devin Desktop (Windsurf)

macOS: ~/.config/devin/mcp_config.json
Windows: %APPDATA%\devin\mcp_config.json
Linux: ~/.config/devin/mcp_config.json

Windsurf giờ là Devin Desktop. Thêm vào tệp cấu hình MCP của nó:

mcp_config.json

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

Devin Local, agent mặc định, đọc tệp này từ phiên bản 3.6; các phiên bản trước lưu máy chủ trong tệp cấu hình chính và chuyển chúng sang đây khi khởi động. Agent Cascade cũ, vốn không được dùng để bắt đầu các cuộc hội thoại mới, cũng đọc chính tệp này. Devin Desktop lấy tham chiếu MAGUYVA_API_KEY từ môi trường lúc nó khởi động.

Maguyva bổ sung gì cho Devin Desktop (Windsurf) →

Tài liệu MCP của Devin Desktop (Windsurf) →

Codex

macOS: ~/.codex/config.toml
Windows: %UserProfile%\.codex\config.toml
Linux: ~/.codex/config.toml

Thêm vào cấu hình Codex CLI của bạn (~/.codex/config.toml):

.codex/config.toml

[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"

Maguyva bổ sung gì cho Codex →

Tài liệu MCP của Codex →

GitHub Copilot CLI

Thêm vào ~/.copilot/mcp-config.json:

~/.copilot/mcp-config.json

{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

copilot mcp add

copilot mcp add --transport http --header "Authorization: Bearer mgv_xxxx" maguyva https://maguyva.tools/mcp

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Maguyva bổ sung gì cho GitHub Copilot CLI →

Tài liệu MCP của GitHub Copilot CLI →

Gemini CLI

macOS: ~/.gemini/settings.json
Windows: %UserProfile%\.gemini\settings.json
Linux: ~/.gemini/settings.json

Thêm vào cài đặt Gemini CLI của bạn (~/.gemini/settings.json):

settings.json

{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Maguyva bổ sung gì cho Gemini CLI →

Tài liệu MCP của Gemini CLI →

Cline

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Thêm vào cài đặt MCP của Cline:

cline_mcp_settings.json

{
  "mcpServers": {
    "maguyva": {
      "type": "streamableHttp",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Maguyva bổ sung gì cho Cline →

Tài liệu MCP của Cline →

Goose

macOS: ~/.config/goose/config.yaml
Windows: %APPDATA%\Block\goose\config\config.yaml
Linux: ~/.config/goose/config.yaml

Thêm vào cấu hình Goose của bạn:

config.yaml

extensions:
  maguyva:
    name: maguyva
    type: streamable_http
    uri: https://maguyva.tools/mcp
    enabled: true
    headers:
      Authorization: Bearer mgv_xxxx
    timeout: 300

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Maguyva bổ sung gì cho Goose →

Tài liệu MCP của Goose →

LM Studio

Trong LM Studio, mở tab Program ở thanh bên phải, chọn Install → Edit mcp.json rồi thêm:

mcp.json

{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Tài liệu MCP của LM Studio →

Continue

Lưu thành .continue/mcpServers/maguyva.yaml trong workspace (hoặc thêm mục mcpServers vào ~/.continue/config.yaml), rồi đặt MAGUYVA_API_KEY trong ~/.continue/.env:

.continue/mcpServers/maguyva.yaml

name: Maguyva
version: 0.0.1
schema: v1
mcpServers:
  - name: maguyva
    type: streamable-http
    url: https://maguyva.tools/mcp
    requestOptions:
      headers:
        Authorization: Bearer ${{ secrets.MAGUYVA_API_KEY }}

Continue chỉ dùng máy chủ MCP ở chế độ agent. Nó tìm secret trong ~/.continue/.env, rồi trong .continue/.env và .env của workspace, cuối cùng trong môi trường tiến trình.

Maguyva bổ sung gì cho Continue →

Tài liệu MCP của Continue →

Kiro CLI (Amazon Q Developer CLI)

macOS: ~/.kiro/settings/mcp.json
Windows: %USERPROFILE%\.kiro\settings\mcp.json
Linux: ~/.kiro/settings/mcp.json

Thêm vào cấu hình MCP của Kiro CLI (~/.kiro/settings/mcp.json, hoặc .kiro/settings/mcp.json trong một dự án):

mcp.json

{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Kiro CLI đã thay thế Amazon Q Developer CLI. Khi cài đặt, nó sao chép các server của bạn một lần từ ~/.aws/amazonq/mcp.json sang ~/.kiro/settings/mcp.json, và .kiro/settings/mcp.json của dự án được ưu tiên hơn file của người dùng.

Tài liệu MCP của Kiro CLI (Amazon Q Developer CLI) →

PyCharm

Dán vào Settings | Tools | AI Assistant | Model Context Protocol (MCP) → Add, dưới dạng cấu hình JSON:

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Thiết lập này sử dụng cầu nối @maguyva/mcp (cần Node.js / npx). Hướng dẫn này chưa xác minh cấu hình kết nối từ xa bằng tính năng tích hợp sẵn của client này; điều đó không có nghĩa là client không có khả năng kết nối từ xa tích hợp sẵn. Maguyva chạy hoàn toàn từ xa — chỉ có cầu nối chạy cục bộ.

Tài liệu MCP của PyCharm →

Zed

macOS: ~/.config/zed/settings.json
Windows: %AppData%\Zed\settings.json
Linux: ~/.config/zed/settings.json

Thêm vào cài đặt Zed của bạn (~/.config/zed/settings.json):

settings.json

{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Maguyva bổ sung gì cho Zed →

Tài liệu MCP của Zed →

Trae

Bật Enable Project MCP trong Settings → MCP, rồi thêm vào .trae/mcp.json ở thư mục gốc dự án:

.trae/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Tài liệu MCP của Trae →

OpenCode

Thêm vào opencode.json ở thư mục gốc dự án:

opencode.json

{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}

Maguyva bổ sung gì cho OpenCode →

Tài liệu MCP của OpenCode →

BoltAI

macOS: ~/.boltai/mcp.json

Thêm vào cấu hình MCP của BoltAI:

mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Tài liệu MCP của BoltAI →

LibreChat

Thêm vào librechat.yaml và đặt MAGUYVA_API_KEY trong môi trường của máy chủ LibreChat:

librechat.yaml

mcpServers:
  maguyva:
    type: streamable-http
    url: https://maguyva.tools/mcp
    headers:
      Authorization: Bearer ${MAGUYVA_API_KEY}
    requiresOAuth: false

Tài liệu MCP của LibreChat →

Antigravity

macOS: ~/.gemini/config/mcp_config.json
Windows: %UserProfile%\.gemini\config\mcp_config.json
Linux: ~/.gemini/config/mcp_config.json

Thêm vào cấu hình MCP của Antigravity:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Maguyva bổ sung gì cho Antigravity →

Tài liệu MCP của Antigravity →

Claude Cowork

Claude Cowork không nạp máy chủ từ claude_desktop_config.json; nó kết nối tới máy chủ từ xa dưới dạng connector tùy chỉnh. Trong Customize → Connectors, thêm một connector tùy chỉnh với URL https://maguyva.tools/mcp, chọn No sign-in, rồi thêm request header authorization có giá trị là Bearer theo sau là khóa API của bạn. Request header đang ở giai đoạn beta cho một số tổ chức giới hạn; nếu hộp thoại không có mục Request headers, Cowork chưa thể xác thực với Maguyva. Xem tài liệu →

ChatGPT

ChatGPT hỗ trợ MCP server từ xa trên các gói Business, Enterprise, và Edu thông qua Settings → Apps → Create. Cần có một endpoint HTTPS từ xa — ChatGPT không hỗ trợ server stdio cục bộ. Xem hướng dẫn MCP của OpenAI để cài đặt. Xem tài liệu →

Warp

Thêm vào ~/.warp/.mcp.json (hoặc .warp/.mcp.json trong một dự án), hoặc dán vào Settings → Agents → MCP servers → + Add:

~/.warp/.mcp.json

{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Thay mgv_xxxx bằng khóa API của bạn từ app.maguyva.ai.

Maguyva bổ sung gì cho Warp →

Tài liệu MCP của Warp →

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 section 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

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

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

macOS/Linux (Bash/Zsh)

Windows (PowerShell)

Cấu hình client

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

Định dạng Repository

Khắc phục sự cố

Sự cố với khóa API

Không tìm thấy Repository

Sự cố kết nối MCP

Các bước tiếp theo

Đọc tiếp