Chuyển tới nội dung

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 24 MCP client, trong đó có Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot và 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 API key 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/claude-code-plugin
/plugin install maguyva@maguyva

Cài đặt cho tài khoản người dùng của bạn. Với một team, thêm --scope project vào cả hai lệnh để commit plugin vào .claude/settings.json của repository, để đồng đội tự động có được nó.

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.

Thủ công (.mcp.json) — nâng cao
.mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "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 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",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Claude Desktop chỉ hỗ trợ server từ xa dưới dạng "connector" OAuth thông qua Settings, chứ không phải một mục xác thực bằng header trong claude_desktop_config.json, nên cách này dùng cầu nối mcp-remote (cần Node.js / npx).

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 ${MAGUYVA_API_KEY}"
      }
    }
  }
}

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

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

VS Code / GitHub Copilot

Thêm vào .vscode/mcp.json trong dự án của bạn (hoặc cài đặt người dùng):

.vscode/mcp.json
{
  "servers": {
    "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.

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

Windsurf

macOS: ~/.codeium/windsurf/mcp_config.json
Windows: %UserProfile%\.codeium\windsurf\mcp_config.json
Linux: ~/.codeium/windsurf/mcp_config.json

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

mcp_config.json
{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "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.

Tài liệu MCP của 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"

[mcp_servers.maguyva.http_headers]
Authorization = "Bearer ${MAGUYVA_API_KEY}"

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

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

GitHub Copilot CLI

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

.copilot/mcp-config.json
{
  "servers": {
    "maguyva": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "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 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}"
      }
    }
  }
}

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

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": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

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

Client này chưa hỗ trợ MCP server từ xa với header xác thực tùy chỉnh, nên nó kết nối qua cầu nối mcp-remote (cần Node.js / npx). 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 Cline →

Roo Code

macOS: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

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

mcp_settings.json
{
  "mcpServers": {
    "maguyva": {
      "type": "streamable-http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

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

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

Goose

macOS: ~/.config/goose/config.yaml
Windows: %AppData%\goose\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
    cmd: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    enabled: true
    envs:
      MAGUYVA_API_KEY: mgv_xxxx
    type: stdio

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

Client này chưa hỗ trợ MCP server từ xa với header xác thực tùy chỉnh, nên nó kết nối qua cầu nối mcp-remote (cần Node.js / npx). 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 Goose →

LM Studio

LM Studio hỗ trợ MCP server thông qua cấu hình Agent của nó. Thêm một MCP server mới trong Settings → Agent → MCP Servers bằng định dạng JSON mcpServers tiêu chuẩn. LM Studio kết nối tới MCP server qua stdio. Xem tài liệu →

Continue

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

Thêm vào cấu hình Continue của bạn (~/.continue/config.json):

config.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Client này chưa hỗ trợ MCP server từ xa với header xác thực tùy chỉnh, nên nó kết nối qua cầu nối mcp-remote (cần Node.js / npx). 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 Continue →

Amazon Q Developer

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

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

mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Client này chưa hỗ trợ MCP server từ xa với header xác thực tùy chỉnh, nên nó kết nối qua cầu nối mcp-remote (cần Node.js / npx). 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 Amazon Q Developer →

PyCharm

Thêm vào .ai/mcp/mcp.json ở thư mục gốc dự án, hoặc dán vào Settings > Tools > AI Assistant > MCP:

.ai/mcp/mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Client này chưa hỗ trợ MCP server từ xa với header xác thực tùy chỉnh, nên nó kết nối qua cầu nối mcp-remote (cần Node.js / npx). 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 ${MAGUYVA_API_KEY}"
      }
    }
  }
}

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

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

Trae

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

.trae/mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Client này chưa hỗ trợ MCP server từ xa với header xác thực tùy chỉnh, nên nó kết nối qua cầu nối mcp-remote (cần Node.js / npx). 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 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 ${MAGUYVA_API_KEY}"
      }
    }
  }
}

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

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

BoltAI

macOS: ~/Library/Application Support/BoltAI/mcp_config.json

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

mcp_config.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Client này chưa hỗ trợ MCP server từ xa với header xác thực tùy chỉnh, nên nó kết nối qua cầu nối mcp-remote (cần Node.js / npx). 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 BoltAI →

LibreChat

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

librechat.yaml
mcpServers:
  maguyva:
    command: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    env:
      MAGUYVA_API_KEY: mgv_xxxx

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

Client này chưa hỗ trợ MCP server từ xa với header xác thực tùy chỉnh, nên nó kết nối qua cầu nối mcp-remote (cần Node.js / npx). 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 LibreChat →

Antigravity

macOS: ~/.gemini/antigravity/mcp_config.json
Windows: %UserProfile%\.gemini\antigravity\mcp_config.json
Linux: ~/.gemini/antigravity/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 ${MAGUYVA_API_KEY}"
      }
    }
  }
}

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

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

Claude Cowork

Claude Cowork dùng cùng định dạng MCP như các client khác của Anthropic:

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "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 Claude Cowork →

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

Warp hỗ trợ MCP server trong Agent Mode. Cấu hình được quản lý qua giao diện Warp (Settings → Agent Mode → MCP Servers) và đồng bộ qua Warp Drive. Dán JSON mcpServers tiêu chuẩn khi thêm một server. Xem tài liệu →

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. 24 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 cách repository được phân giải. Server v3 không giữ trạng thái, nên mọi ghi đè repository chỉ áp dụng cho một lần gọ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#

  • Kiểm tra npx có sẵn trong PATH của bạn hay không
  • 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#