GitLab MCP server: nối Claude Code, Cursor với issue, MR và pipeline

Bạn đang dùng Claude Code, Cursor hay Copilot để viết code, nhưng mọi thứ quanh code lại nằm trên GitLab: issue, merge request, pipeline đỏ, log job. Mỗi lần cần ngữ cảnh, bạn phải mở trình duyệt, copy log rồi dán vào chat. GitLab MCP server nối thẳng trợ lý AI với GitLab qua chuẩn Model Context Protocol (MCP). AI tự đọc issue, xem diff MR, đọc log job lỗi, tạo branch, commit và mở MR, với đúng quyền của tài khoản bạn.

Xác thực: GitLab có MCP server thật không?

Có. Đây là tính năng chính thức, có tài liệu trên docs.gitlab.com. Các mốc trong lịch sử phiên bản:

MCP server có ở các gói Free, Premium, Ultimate và dùng được trên GitLab.com, Self-Managed lẫn Dedicated.

Lợi ích chính

• Bớt chuyển qua lại giữa các cửa sổ: hỏi "pipeline MR 42 vì sao fail?" ngay trong IDE; AI tự lấy log job và chỉ ra dòng lỗi.
• Một chuẩn cho nhiều client: một endpoint dùng được cho Claude Code, Cursor, VS Code Copilot, Gemini CLI, Codex, Zed, Kiro…
• Theo phân quyền có sẵn: AI chỉ thấy và làm được những gì tài khoản của bạn được phép. Mỗi lần gọi tool, GitLab đều kiểm tra quyền.
• Tự động hoá trọn vòng: đọc issue → tạo branch → commit → mở MR → theo dõi pipeline, làm hết trong một cuộc hội thoại.

Có những tool gì?

Các tool được chia theo toolset. Toolset mặc định đã đủ cho phần lớn công việc hằng ngày:

Cài đặt từng bước

1. Bật quyền truy cập MCP

Quản trị viên phải cho phép truy cập MCP server. Trên GitLab.com, cài đặt này nằm ở group cấp cao nhất; trên Self-Managed/Dedicated, nằm ở cấp instance. Endpoint có dạng https://<gitlab-host>/api/v4/mcp; với GitLab.com thì host là gitlab.com.

2. Kết nối client

Nên dùng transport HTTP vì không cần cài thêm gì. Claude Code:

claude mcp add -s user --transport http GitLab https://gitlab.com/api/v4/mcp
# trong Claude Code gõ /mcp để đăng nhập OAuth qua trình duyệt

Cursor, Kiro và các client nhận cấu hình JSON:

{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://gitlab.com/api/v4/mcp"
    }
  }
}

Codex: chạy codex mcp add GitLab --url https://gitlab.com/api/v4/mcp, bật rmcp_client trong ~/.codex/config.toml, rồi chạy codex mcp login GitLab. Với client chỉ hỗ trợ stdio (Claude Desktop, Zed), dùng cầu nối npx -y mcp-remote <URL>; cách này cần Node.js 20 trở lên.

3. Xác thực

• Server chấp nhận token OAuth có scope mcp (tự đăng ký client hoặc dùng OAuth app tạo sẵn), hoặc personal access token loại fine-grained có quyền Execute trên tài nguyên MCP.
• Personal access token kiểu cũ, project token và group token đều bị từ chối với lỗi 403 insufficient_scope.
• Nếu admin tắt tự đăng ký client (DCR), hoặc cả công ty dùng chung một IP (giới hạn 10 lần đăng ký/giờ/IP), hãy tạo sẵn một OAuth app có scope mcp và bỏ chọn "Confidential".

4. Giới hạn tool bằng header (khuyên dùng)

"headers": {
  "X-Gitlab-Enabled-Mcp-Server-Toolsets": "merge_requests,ci",
  "X-Gitlab-Mcp-Server-Tool-Name-Prefix": "gl_"
}

Ít tool hơn nghĩa là tốn ít context hơn và AI ít chọn nhầm tool. Tiền tố tên tool giúp tránh trùng tên khi bạn kết nối nhiều instance GitLab cùng lúc. Dùng giá trị all nếu muốn bật mọi toolset.

Prompt mẫu dùng ngay

• "Những MR nào đang chờ tôi review?" (dùng list_todos)
• "Pipeline mới nhất của MR !42 fail ở job nào? Đọc log và đề xuất cách sửa."
• "Đọc issue #1234, tạo branch, sửa lỗi, commit và mở MR liên kết với issue."
• "Tóm tắt các thread chưa resolve trong MR !57 và soạn câu trả lời."
• "Merge MR !42 khi check pass và xoá branch nguồn."

Rủi ro và lưu ý

• Prompt injection: nội dung issue, comment hay file có thể chứa lệnh độc hại nhắm vào AI. GitLab ghi rõ trách nhiệm phòng tránh thuộc về người dùng, nên chỉ dùng MCP trên những đối tượng GitLab bạn tin cậy.
• Quyền ghi: có những tool merge MR, commit hoặc huỷ pipeline. Hãy để client hỏi xác nhận trước mỗi tool ghi, đừng bật tự động duyệt.
• Rate limit trên GitLab.com: tính theo từng người dùng. Gói Free được 60 lượt/phút và 3.600 lượt/giờ; Premium/Ultimate được 600 lượt/phút và 5.000 lượt/giờ. Vượt giới hạn sẽ nhận lỗi 429.
• Thấy một tool trong danh sách không có nghĩa là bạn có quyền dùng nó; quyền vẫn được kiểm tra ở từng lần gọi.

Áp dụng thế nào?

• Dev: Thêm GitLab MCP vào Claude Code hoặc Cursor ở scope user. Dùng nó để đọc log pipeline lỗi và soạn MR, nhưng tự duyệt mọi thao tác ghi.
• Tech Lead: Chuẩn hoá cấu hình (toolset được bật, tiền tố, OAuth app dùng chung) và đưa vào tài liệu onboarding. Bắt đầu chỉ với các toolset đọc, rồi mới mở dần quyền ghi.
• PM: Hỏi trợ lý AI "tuần này có MR nào bị kẹt review?" hoặc "các issue của milestone X đang ở trạng thái nào?" mà không cần nhờ dev trích xuất số liệu.