What Is GitLab MCP? AI Agents Meet GitLab

Nếu team bạn đang chạy self-hosted GitLab hoặc dùng GitLab.com làm nơi lưu code, sớm muộn bạn cũng sẽ muốn AI coding agent (Claude Code, Cursor, Gemini CLI, OpenCode...) tự làm việc trực tiếp với merge request, issue, pipeline mà không cần bạn copy-paste log lỗi qua lại. Đó chính là lý do GitLab MCP tồn tại. Bài này sẽ giải thích GitLab MCP là gì, những tool nào nó cung cấp, cách xác thực an toàn, và khác biệt so với GitHub MCP — để bạn có nền tảng vững trước khi đi vào cấu hình cụ thể cho từng công cụ ở các bài sau.

Các Tool Cốt Lõi Của GitLab MCP: Project, Merge Request, Issue và CI/CD

MCP (Model Context Protocol) là chuẩn giao tiếp cho phép LLM gọi tool (tool calling) tới hệ thống bên ngoài theo một schema thống nhất. GitLab MCP server đóng vai trò cầu nối: nó wrap GitLab REST API (và một phần GraphQL API) thành các tool có tên, input schema, output schema rõ ràng để agent gọi được mà không cần bạn viết code tích hợp.

Về bản chất, một GitLab MCP server (ví dụ package phổ biến @zereight/mcp-gitlab, hoặc GitLab's official MCP server đang được phát triển) thường expose các nhóm tool sau:

Project & Repository: search_repositories, get_project, list_projects, get_file_contents, create_or_update_file, push_files, list_branches, create_branch.
Merge Request: list_merge_requests, get_merge_request, get_merge_request_diffs, create_merge_request, update_merge_request, merge_merge_request, create_merge_request_note (comment lên MR), create_merge_request_thread (review thread trên diff line cụ thể).
Issue: list_issues, get_issue, create_issue, update_issue, create_issue_note.
CI/CD Pipeline: list_pipelines, get_pipeline, list_pipeline_jobs, get_pipeline_job_logs, retry_pipeline, cancel_pipeline.

Điểm mấu chốt khi làm việc với những tool này: mỗi tool đều nhận project_id (có thể là số ID hoặc dạng namespace/project-path đã URL-encode). Vì vậy, khi viết prompt cho agent, càng chỉ rõ project path càng giảm rủi ro agent gọi sai tool hoặc gọi nhầm project trong group lớn có hàng trăm repo.

Một điều dân senior hay bỏ qua: get_merge_request_diffs trả về diff dạng unified diff text, và với MR lớn (vài nghìn dòng) sẽ ăn rất nhiều context window (cửa sổ ngữ cảnh) của LLM. Agent tốt sẽ tự paginate hoặc filter theo file, nhưng không phải server nào cũng làm tốt việc này — bạn cần biết để chủ động giới hạn phạm vi trong prompt.

Mẹo: Khi mới làm quen, hãy yêu cầu agent chạy thử list_projects trước để xác nhận token của bạn thấy đúng project cần thao tác — tránh trường hợp agent "tưởng" đúng project nhưng thực ra đang gọi vào một repo demo nào đó trong group.

Xác Thực GitLab MCP: Cấu Hình Personal Access Token và Các Scope Cần Thiết

GitLab MCP server hầu hết xác thực bằng Personal Access Token (PAT) — khác với GitHub App/OAuth flow phổ biến hơn ở GitHub MCP. Để tạo PAT:

Vào GitLab > User Settings > Access Tokens (hoặc https://gitlab.example.com/-/user_settings/personal_access_tokens nếu self-hosted).
Đặt tên token rõ ràng, ví dụ mcp-agent-claude-code-2026, để về sau audit log dễ truy vết token nào đang được agent nào dùng.
Chọn scope. Với use case đọc/viết MR, issue, pipeline, scope tối thiểu cần là:
api — full access tới REST API (bắt buộc cho hầu hết write operation như tạo MR, comment).
read_repository — clone/đọc nội dung repo qua Git.
write_repository — push branch, tạo commit qua Git (nếu agent cần tự tạo branch/commit).
Set thời hạn hết hạn (expiration date) — GitLab bắt buộc từ bản mới, và đây là thực hành tốt: không bao giờ tạo token vô hạn cho một AI agent.

Sau khi có token, cấu hình biến môi trường cho MCP server:

export GITLAB_PERSONAL_ACCESS_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export GITLAB_API_URL="https://gitlab.com/api/v4"

Nếu bạn dùng self-hosted GitLab, đổi GITLAB_API_URL thành https://gitlab.your-company.com/api/v4. Đây là điểm khác biệt lớn với GitHub MCP — phần lớn công ty Việt Nam vẫn chạy GitLab self-hosted on-premise, nên bạn thường sẽ phải xử lý thêm chuyện certificate (self-signed cert), proxy nội bộ, và firewall rule cho phép MCP server (chạy trên máy dev) gọi ra được GitLab server nội bộ.

Mẹo: Đừng bao giờ set scope api ở mức group/instance token khi bạn chỉ cần dùng cho 1-2 project. Ưu tiên Project Access Token (tạo trong Settings > Access Tokens của từng project) để giới hạn phạm vi — nếu token bị leak, thiệt hại chỉ khu trú trong 1 project thay vì cả group.

GitLab MCP So Với GitHub MCP: Khác Biệt Quan Trọng Trong Workflow AI Agent

Nhiều bạn đã quen GitHub MCP rồi mới chuyển qua dùng GitLab MCP sẽ gặp vài khác biệt cần lưu ý:

Terminology khác nhau: GitHub gọi là "Pull Request" (PR), GitLab gọi "Merge Request" (MR) — về chức năng tương đương nhưng field name trong API khác (ví dụ GitLab dùng source_branch/target_branch thay vì head/base). Khi viết prompt, đôi lúc agent bị "nhiễm" thói quen dùng từ PR từ training data GitHub-heavy, dẫn tới hiểu nhầm nhẹ — bạn nên chủ động dùng đúng từ "merge request" trong prompt để tránh lệch ngữ cảnh.
CI/CD tích hợp sẵn: GitLab có .gitlab-ci.yml và pipeline là first-class citizen ngay trong repo, khác với GitHub Actions là workflow riêng. GitLab MCP vì vậy có tool pipeline khá mạnh (get_pipeline_job_logs lấy trực tiếp log job) — đây là điểm GitLab MCP thường "ăn điểm" hơn khi agent cần tự debug pipeline fail.
Groups & Subgroups: GitLab có khái niệm Group/Subgroup lồng nhau (ví dụ company/backend/payment-service), khác với GitHub Organization phẳng hơn. Khi gọi list_projects, bạn cần biết filter theo group_id hoặc namespace path, nếu không danh sách trả về có thể quá lớn với công ty có hàng trăm repo.
Self-hosted phổ biến hơn: Rất nhiều enterprise VN/APAC dùng self-hosted GitLab vì lý do compliance/data residency. Điều này nghĩa là bạn phải quan tâm tới network reachability, VPN, cert nội bộ khi cấu hình MCP — chuyện mà GitHub MCP (chủ yếu cloud-hosted) ít gặp hơn.
Approval rule & merge checks: GitLab có concept "Merge Request Approval Rules" khá chi tiết (required approvers theo rule, code owner approval) — agent cần biết đọc field detailed_merge_status để biết MR có đang bị block bởi approval rule hay pipeline fail hay conflict.

Mẹo: Nếu team bạn có cả GitHub và GitLab repo, đừng đăng ký cả hai MCP server với tool name generic như "create_pr" — hãy giữ nguyên tên tool gốc (create_merge_request vs tool GitHub tương ứng) để agent không bị nhầm lẫn khi chọn tool.

Bảo Mật và Phân Quyền Khi Cấu Hình GitLab MCP

Đưa một AI agent access thẳng vào GitLab bằng token có quyền api là một quyết định cần cân nhắc kỹ, vì agent có thể tự ý tạo MR, comment, hoặc merge code nếu bạn cho phép. Vài nguyên tắc least-privilege (nguyên tắc đặc quyền tối thiểu) nên áp dụng:

Tách token theo mục đích: Token cho agent "chỉ đọc" (review, monitor pipeline) nên khác token cho agent "được viết" (tạo MR, comment). Dùng scope read_api (chỉ đọc) thay vì api khi có thể.
Không merge tự động mặc định: Hầu hết setup nên để agent tạo MR + comment, nhưng không cho quyền write_repository kèm auto-merge trừ khi bạn có branch protection rule + required approval từ người thật chặn lại trước.
Bật branch protection: Cấu hình main/develop là protected branch, yêu cầu ít nhất 1 approval từ người review thật, để dù agent có tạo merge request tự động thì vẫn không thể tự merge thẳng vào nhánh chính.
Token rotation: Set expiration 30-90 ngày cho PAT dùng bởi agent, và có quy trình rotate định kỳ — đừng để token "sống mãi" trong file .env cũ không ai nhớ tới.
Không commit token vào MCP config file: Luôn dùng biến môi trường hoặc secret manager (1Password CLI, Vault, hoặc .env bị gitignore) — không hardcode token trực tiếp trong .mcp.json hay settings.json rồi commit lên repo.
Audit log: GitLab Premium/Ultimate có Audit Events log lại ai/token nào gọi API — nếu công ty có license, nên theo dõi log này để phát hiện agent hành xử bất thường (ví dụ gọi API quá nhiều lần trong thời gian ngắn — dấu hiệu prompt injection hoặc loop lỗi).

Mẹo: Với môi trường production nhạy cảm, hãy tạo riêng một "service account" GitLab user cho AI agent (không dùng chính account cá nhân của bạn) — vừa dễ audit, vừa dễ revoke quyền khi cần mà không ảnh hưởng tài khoản cá nhân.

Mẹo Thực Chiến Khi Dùng GitLab MCP

Tổng hợp lại vài kinh nghiệm thực chiến khi làm việc với GitLab MCP trong ngày thường:

Luôn test connectivity bằng một prompt đơn giản như "List 5 most recently updated projects I have access to" trước khi giao task phức tạp — nếu bước này fail, vấn đề nằm ở token/network, không phải ở logic prompt.
Với self-hosted GitLab dùng cert tự ký, nếu MCP server báo lỗi SSL, thử set NODE_TLS_REJECT_UNAUTHORIZED=0 chỉ trong môi trường dev cá nhân, tuyệt đối không dùng cách này trên máy CI hoặc production.
Khi agent cần thao tác nhiều project trong cùng group, hãy cung cấp trước danh sách project_id hoặc path đầy đủ trong system prompt/instruction file (ví dụ CLAUDE.md) để agent không phải dò tìm bằng search_repositories mỗi lần, vừa nhanh vừa tiết kiệm context window.
Theo dõi rate limit của GitLab API (mặc định GitLab.com free tier giới hạn khá chặt) — nếu agent gọi tool liên tục trong loop debug pipeline, có thể dính 429 Too Many Requests.

Mẹo: Ghi lại một file "GitLab MCP cheatsheet" ngắn trong repo (project path, group structure, tên các label chuẩn dùng cho MR) để agent — và cả đồng nghiệp mới — dùng làm ngữ cảnh nền, giảm hẳn số lần agent đoán sai.