Cấu hình MCP trong Gemini CLI

Nếu bạn đã quen với việc gắn MCP (Model Context Protocol) server vào Claude Code, tin vui là phần lớn tư duy đó dùng lại được cho Gemini CLI — công cụ dòng lệnh mã nguồn mở của Google cho phép Gemini truy cập terminal, filesystem và các công cụ bên ngoài ngay trong session chat. Nhưng cách Gemini CLI tổ chức file config, cú pháp khai báo server, và cách nó xử lý auth (xác thực) lại có vài khác biệt đủ lớn để bạn dễ dính lỗi nếu chỉ copy-paste config từ Claude Code sang. Bài này đi thẳng vào việc cài Gemini CLI, viết settings.json đúng chuẩn, phân biệt server local (stdio) và remote (HTTP/SSE), rồi đặt cạnh Claude Code để bạn thấy rõ điểm giống — khác, từ đó chọn công cụ phù hợp cho từng tình huống thực tế trong team.

Cài đặt Gemini CLI và chuẩn bị cho tích hợp MCP

Gemini CLI là một agentic coding tool (công cụ lập trình dạng agent) chạy trong terminal, dùng model Gemini để đọc code, chạy lệnh shell, sửa file và — quan trọng với bài này — gọi các MCP server để mở rộng năng lực ra ngoài phạm vi model gốc. Trước khi đụng tới MCP, bạn cần cài xong CLI và xác nhận nó chạy được.

Yêu cầu tối thiểu: Node.js 20 trở lên. Cài global qua npm:

npm install -g @google/gemini-cli

Hoặc chạy trực tiếp không cần cài (phù hợp khi thử nhanh trên máy CI hoặc container):

npx @google/gemini-cli

Sau khi cài, gọi lệnh gemini lần đầu để chạy luồng đăng nhập (login flow) — Gemini CLI sẽ mở browser để bạn xác thực bằng Google account (free tier có quota hào phóng cho cá nhân), hoặc bạn có thể export GEMINI_API_KEY nếu dùng API key từ Google AI Studio / Vertex AI cho mục đích production:

export GEMINI_API_KEY="your-api-key-here"
gemini

Kiểm tra version để chắc chắn CLI đã lên bản có hỗ trợ MCP đầy đủ (tính năng MCP được bổ sung và mở rộng dần qua các bản release, nên đừng dùng bản quá cũ):

gemini --version

Gemini CLI đọc config từ hai cấp: user-level tại ~/.gemini/settings.json (áp dụng cho mọi project) và project-level tại .gemini/settings.json nằm trong thư mục repo (chỉ áp dụng khi bạn chạy gemini trong repo đó). Config project sẽ merge và override config user cho các key trùng nhau — đây là điểm cực kỳ hữu ích khi bạn muốn một MCP server (ví dụ server truy vấn database nội bộ) chỉ tồn tại trong một project cụ thể, không rò ra các project khác.

Mẹo: Tạo sẵn thư mục .gemini/ trong repo và thêm .gemini/settings.json vào .gitignore nếu file chứa token hay path riêng của máy bạn. Chỉ commit một file mẫu .gemini/settings.json.example để đồng bộ cấu trúc MCP cho cả team mà không leak secret.

Cấu hình MCP server trong settings.json của Gemini CLI

Toàn bộ việc khai báo MCP server trong Gemini CLI xoay quanh key mcpServers — một object trong settings.json, mỗi property là tên server bạn tự đặt (dùng để hiển thị trong log và khi agent gọi tool), giá trị là config chi tiết của server đó.

Ví dụ khai báo một server local chạy qua stdio (giao tiếp qua standard input/output, cách phổ biến nhất cho MCP server chạy trên máy bạn):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"],
      "env": {
        "NODE_ENV": "production"
      },
      "timeout": 30000,
      "trust": false
    }
  }
}

Giải thích từng field vì đây là phần dễ sai nhất:

• command / args: lệnh và tham số để spawn tiến trình server — giống hệt tinh thần của Claude Code, MCP server local thực chất là một process con được CLI khởi động và giao tiếp qua stdio.
• env: biến môi trường riêng cho tiến trình server, không lẫn với env của shell chạy gemini.
• timeout: số milliseconds Gemini CLI chờ server phản hồi trước khi coi là timeout — nên tăng lên nếu server của bạn cần thời gian khởi động (ví dụ server load embedding model).
• trust: nếu để true, Gemini CLI sẽ tự động chạy mọi tool call từ server này mà không hỏi xác nhận (auto-approve) — chỉ nên true với server bạn tự viết và kiểm soát hoàn toàn.

Với server chạy qua HTTP thay vì spawn process, dùng httpUrl (cho streamable HTTP transport) hoặc url (cho SSE — Server-Sent Events, transport cũ hơn nhưng vẫn được nhiều MCP server hỗ trợ):

{
  "mcpServers": {
    "internal-jira": {
      "httpUrl": "https://mcp.internal.company.com/jira/mcp",
      "headers": {
        "Authorization": "Bearer ${JIRA_MCP_TOKEN}"
      }
    }
  }
}

Gemini CLI hỗ trợ interpolate biến môi trường ngay trong settings.json bằng cú pháp ${VAR_NAME} — nghĩa là bạn không cần hard-code token vào file, chỉ cần export JIRA_MCP_TOKEN trước khi chạy gemini. Đây là cách xử lý auth (xác thực) chuẩn cho cả token tĩnh, còn với OAuth thì Gemini CLI có luồng riêng: nếu server MCP hỗ trợ OAuth discovery, CLI sẽ tự mở browser để bạn cấp quyền và lưu token vào credential store cục bộ, tự refresh khi cần — bạn không phải tự tay quản lý access token.

Hai field khác đáng biết: includeTools và excludeTools cho phép giới hạn danh sách tool cụ thể mà agent được thấy từ một server (rất hữu ích khi server có 30 tool nhưng bạn chỉ muốn agent dùng 3 tool an toàn), và bạn kiểm tra trạng thái kết nối bằng lệnh trong chính session:

/mcp

Lệnh này liệt kê từng server đã khai báo, trạng thái (connected / disconnected / error) và danh sách tool mà server đó expose ra cho model.

Mẹo: Khi thêm server mới, luôn chạy /mcp ngay trong session để xác nhận server connect thành công trước khi thử prompt phức tạp — tránh mất thời gian debug nhầm giữa lỗi config và lỗi logic của agent.

Dùng Gemini CLI với MCP server local và remote

Về bản chất, "local" và "remote" ở đây không phải phân loại chính thức của MCP spec, mà là cách bạn nên tư duy khi chọn transport cho từng use case.

MCP server local (stdio) phù hợp khi: bạn cần server truy cập filesystem, chạy lệnh shell, hoặc thao tác trực tiếp trên máy dev — ví dụ server đọc file log, server chạy test suite, server truy vấn SQLite local. Ưu điểm là latency thấp (không qua network), không cần lo bảo mật truyền tải vì mọi thứ chạy trong process con trên máy bạn. Nhược điểm: mỗi dev phải tự cài dependency của server đó, và server chỉ sống trong đúng session gemini đang mở — tắt CLI là server cũng bị kill theo (Gemini CLI quản lý lifecycle của server local hoàn toàn tự động, spawn khi cần và terminate khi session kết thúc).

Ví dụ prompt thực tế dùng server filesystem local:

Đọc toàn bộ file trong thư mục src/api, liệt kê những endpoint chưa có test tương ứng trong thư mục tests/, rồi viết stub test cho từng endpoint đó.

MCP server remote (HTTP/SSE) phù hợp khi: server là dịch vụ chung của cả team hoặc công ty — ví dụ MCP server wrap API nội bộ (Jira, Confluence, hệ thống CI/CD), server cần chạy 24/7 để phục vụ nhiều người, hoặc server cần credential tập trung mà bạn không muốn distribute xuống từng máy dev. Ưu điểm: một lần deploy, cả team dùng chung, dễ audit log tập trung, dễ rotate secret ở một chỗ. Nhược điểm: có network latency, và bạn phải tự vận hành uptime của server đó — nếu server remote sập, mọi dev dùng server này đều mất tool tương ứng.

Ví dụ config một server remote dùng streamable HTTP kèm auth header, và prompt sử dụng nó:

{
  "mcpServers": {
    "ci-status": {
      "httpUrl": "https://mcp.internal.company.com/ci/mcp",
      "headers": {
        "Authorization": "Bearer ${CI_MCP_TOKEN}"
      },
      "timeout": 15000
    }
  }
}

Kiểm tra trạng thái pipeline CI mới nhất của branch feature/payment-v2, nếu build fail thì lấy log của step fail và tóm tắt nguyên nhân.

Một điểm cần lưu ý về tool discovery (khám phá công cụ): với cả hai loại transport, Gemini CLI đều gọi tools/list ngay khi kết nối thành công để lấy schema của toàn bộ tool server expose ra, rồi đưa schema đó vào context của model — quá trình này diễn ra tự động, bạn không cần khai báo tay tên tool nào cả, trừ khi muốn lọc bớt bằng includeTools/excludeTools như đã nói ở phần trước.

Mẹo: Với server remote dùng chung cho cả team, đừng nhúng token trực tiếp vào .gemini/settings.json rồi commit — dùng biến môi trường qua ${VAR_NAME} và phân phối secret qua vault (1Password, Vault, hoặc secret manager của cloud provider) để tránh lộ credential khi file config vô tình lên Git.

Đối chiếu Gemini CLI và Claude Code trong cấu hình MCP

Cả hai công cụ đều theo đúng MCP spec, nên về giao thức chúng tương thích — một MCP server viết đúng chuẩn có thể chạy với cả Gemini CLI và Claude Code. Sự khác biệt nằm ở lớp cấu hình và trải nghiệm vận hành xung quanh.

Điểm khác biệt thực dụng nhất khi làm việc trong team: Claude Code khuyến khích commit .mcp.json vào repo để cả team tự động có cùng bộ MCP server khi mở project (đây là thiết kế chủ đích — "project-scoped" server), còn Gemini CLI đặt file cấu hình chính ở .gemini/settings.json với cùng tinh thần chia sẻ theo project, nhưng cộng đồng và tài liệu của Google nhấn nhiều hơn vào việc dùng biến môi trường cho phần nhạy cảm để file config vẫn an toàn khi commit. Cả hai đều cho phép bạn tách server "chỉ dành cho tôi" (user/global scope) khỏi server "cả team cùng dùng" (project scope) — chọn cách nào phụ thuộc vào việc bạn đang chuẩn hoá quy trình cho cả team hay chỉ tối ưu cho cá nhân.

Về mức độ trưởng thành của cơ chế permission: Claude Code có hệ thống permission chi tiết hơn ở cấp hành động (đọc file, chạy lệnh, gọi tool nào cần hỏi, tool nào auto-approve), trong khi Gemini CLI hiện gói việc này gọn trong field trust ở cấp từng server — đơn giản hơn nhưng cũng kém linh hoạt hơn nếu bạn cần permission chi tiết đến từng tool riêng lẻ trong một server.

Mẹo: Nếu team bạn dùng cả hai công cụ (một số dev thích Gemini CLI, số khác quen Claude Code), hãy viết một MCP server dùng chung theo chuẩn transport HTTP — vì transport này không phụ thuộc client, bạn chỉ cần maintain một bản config JSON cho mỗi công cụ, phần logic server giữ nguyên một chỗ.

Mẹo

• Mẹo: Luôn bắt đầu bằng một MCP server tối giản (ví dụ server filesystem chính thức của MCP) để xác nhận toàn bộ pipeline — cài, config, connect, tool discovery — hoạt động đúng, trước khi thêm server phức tạp có auth riêng.
• Mẹo: Đặt tên server trong mcpServers theo quy ước rõ nghĩa (ví dụ github-readonly, internal-ci) thay vì tên chung như server1 — tên này sẽ hiện trong log và trong kết quả /mcp, giúp bạn debug nhanh hơn khi có nhiều server cùng chạy.
• Mẹo: Với server có nhiều tool nhưng bạn chỉ cần vài tool cụ thể, dùng includeTools để giảm số lượng tool đưa vào context của model — context window (cửa sổ ngữ cảnh) eo hẹp hơn bạn nghĩ khi có 5-6 MCP server cùng lúc, mỗi server "gánh" thêm vài KB schema vào system prompt.
• Mẹo: Trước khi giao MCP server remote cho cả team dùng, tự tay chạy /mcp để xác nhận thời gian phản hồi (latency) hợp lý — timeout mặc định có thể cần tăng lên nếu server đặt ở region xa, tránh tình huống agent liên tục báo lỗi timeout dù server vẫn hoạt động bình thường.