Postman MCP với Gemini CLI

Gemini CLI là lựa chọn nhiều team backend dùng khi muốn tận dụng context window (cửa sổ ngữ cảnh) rất lớn của Gemini để nạp toàn bộ OpenAPI spec cùng hàng trăm request mẫu trong một lần mà không cần chia nhỏ. Kết hợp với Postman MCP, đây là công cụ mạnh cho contract testing (kiểm thử hợp đồng API - đảm bảo API thực tế đúng với spec đã cam kết). Bài này hướng dẫn cài đặt, sinh contract test từ tài liệu API, một ví dụ phát hiện breaking change trước khi release, và so sánh chất lượng output giữa Gemini CLI với Claude Code khi cùng làm một tác vụ Postman MCP.

Cài Đặt và Kết Nối Postman MCP Với Gemini CLI

Gemini CLI khai báo MCP server trong file ~/.gemini/settings.json hoặc .gemini/settings.json ở project:

{
  "mcpServers": {
    "postman": {
      "command": "npx",
      "args": ["-y", "@postman/mcp-server"],
      "env": {
        "POSTMAN_API_KEY": "$POSTMAN_API_KEY"
      },
      "trust": false
    }
  }
}

Trường trust: false là mặc định an toàn - Gemini CLI sẽ hỏi xác nhận trước mỗi lần agent gọi một tool mới của Postman MCP lần đầu tiên trong session, tương tự cơ chế permission của Claude Code. Kiểm tra kết nối bằng:

gemini
> /mcp list
postman - Ready (14 tools)

Nếu server báo Disconnected, kiểm tra lại biến $POSTMAN_API_KEY đã được export trong shell trước khi gọi gemini, vì Gemini CLI không tự đọc file .env như một số tool khác trừ khi bạn cấu hình thêm.

Mẹo: Giữ trust: false cho server Postman MCP trong giai đoạn đầu làm quen - việc phải xác nhận từng loại tool call (đặc biệt các tool có tính "ghi" như create-collection, run-collection) giúp bạn quan sát chính xác AI đang làm gì trước khi tin tưởng bật auto-approve.

Sinh Contract Test Từ Tài Liệu API Trong Gemini CLI

Nhờ context window lớn, Gemini CLI xử lý tốt việc nạp toàn bộ OpenAPI spec dài (thậm chí vài nghìn dòng YAML) cùng lúc để sinh contract test đầy đủ mà không cần bạn chia nhỏ theo tag như một số tool khác. Prompt mẫu:

Đọc toàn bộ file docs/openapi-v3.yaml. Với từng endpoint, tạo request trong
collection Postman "Contract Tests - Payment API" và viết assertion đảm bảo:
- response status đúng với danh sách status code khai báo trong spec
- response body đúng schema (required fields, type, enum values) theo
  components/schemas tương ứng
- Không tạo assertion cho field không có trong spec.

Gemini CLI sẽ gọi create-collection rồi lặp qua các endpoint, với mỗi request sinh assertion dùng pm.response.to.have.jsonSchema() - cách làm chuẩn cho contract test vì nó validate toàn bộ cấu trúc response một lần, thay vì viết từng pm.expect() riêng lẻ cho mỗi field.

const schema = {
  type: "object",
  required: ["paymentId", "status", "amount"],
  properties: {
    paymentId: { type: "string" },
    status: { type: "string", enum: ["PENDING", "SUCCESS", "FAILED"] },
    amount: { type: "number", minimum: 0 }
  }
};

pm.test("Response matches Payment schema from OpenAPI spec", () => {
    pm.response.to.have.jsonSchema(schema);
});

Mẹo: Yêu cầu AI luôn sinh biến schema từ đúng components/schemas trong spec (copy nguyên cấu trúc required/enum) thay vì tự diễn giải lại - cách này giữ cho contract test là "nguồn sự thật duy nhất" bám sát spec, tránh lệch dần theo thời gian.

Ví Dụ Thực Tế: Phát Hiện Breaking Change Trước Khi Release

Kịch bản phổ biến: team backend đổi field amount từ kiểu number (VND, số nguyên) sang string (định dạng "150000.00") để thống nhất với hệ thống thanh toán mới, nhưng quên thông báo cho team frontend/mobile. Nếu contract test đã được dựng sẵn từ bước trước, việc phát hiện breaking change (thay đổi phá vỡ hợp đồng API) chỉ cần một lệnh chạy trước khi release:

Chạy collection "Contract Tests - Payment API" trên environment "pre-release".
Nếu có test fail liên quan đến schema, so sánh response thực tế với schema
cũ trong spec và cho biết đây có phải breaking change không.

Kết quả điển hình agent trả về:

FAIL: "Response matches Payment schema" (GET /payments/{id})
Response thực tế: amount = "150000.00" (string)
Schema kỳ vọng: amount phải là type "number"
=> Đây là breaking change: client hiện tại đang parse amount như number
   sẽ nhận NaN hoặc lỗi runtime nếu không cập nhật logic parse.
Đề xuất: version hóa endpoint (v2) hoặc thêm field mới "amountFormatted"
song song với "amount" cũ để không phá vỡ client hiện tại.

Đây chính là giá trị thực tế của contract testing tự động hóa: phát hiện breaking change ở giai đoạn CI trước khi release, thay vì để mobile app team báo lỗi crash sau khi đã lên production.

Mẹo: Chạy contract test này như một bước gate bắt buộc trong CI trước merge vào nhánh release, không chỉ chạy tay khi "nhớ ra" - breaking change kiểu đổi type field thường bị bỏ sót nhất vì code review thường chỉ nhìn business logic, ít khi soi kỹ schema response.

So Sánh Output Postman MCP Giữa Gemini CLI và Claude Code

Sau nhiều lần dùng song song cả hai công cụ cho cùng một tác vụ Postman MCP, một vài khác biệt đáng lưu ý cho việc chọn công cụ phù hợp:

Kết luận thực tế: nếu bạn cần nạp một spec khổng lồ để sinh contract test toàn diện trong một lượt, Gemini CLI có lợi thế về context window. Nếu bạn cần độ chính xác cao cho từng assertion phức tạp và muốn AI chủ động hỏi lại khi yêu cầu chưa rõ, Claude Code thường cho kết quả ít phải sửa lại hơn.

Mẹo: Với dự án lớn, không cần chọn một trong hai - dùng Gemini CLI cho pass đầu (sinh toàn bộ khung collection từ spec khổng lồ), rồi dùng Claude Code để refine từng assertion phức tạp ở các endpoint quan trọng nhất (payment, auth).

Tips Thực Chiến Khi Dùng Postman MCP Với Gemini CLI

Vài lưu ý giúp bạn khai thác tốt Gemini CLI cho Postman MCP mà không tốn thời gian mò lỗi:

• Tận dụng context lớn nhưng vẫn chia nhỏ output: dù Gemini CLI nạp được spec khổng lồ, hãy vẫn yêu cầu nó thực thi tool call theo từng nhóm (10-15 request/lượt) - context lớn giúp AI "hiểu" toàn cục tốt hơn, nhưng không đồng nghĩa nó nên tạo hàng trăm request cùng lúc trong một lượt gọi tool.
• Kiểm tra lại phiên bản @postman/mcp-server: một số bản cũ có schema tool hơi khác, dẫn đến Gemini CLI gọi sai tham số dù logic đúng - luôn npx -y @postman/mcp-server@latest khi bắt đầu dự án mới.
• So sánh chéo định kỳ: với các collection contract test quan trọng, mỗi quý nên chạy lại prompt sinh test bằng cả Gemini CLI và một agent khác, diff kết quả để phát hiện assertion nào một bên bỏ sót.
• Ghi log quyết định trust: vì cấu hình trust: false sẽ hỏi xác nhận nhiều lần, hãy ghi chú lại các tool nào bạn đã quen và an toàn để bật trust: true riêng cho tool đó, tránh phải xác nhận lặp lại việc đã kiểm chứng nhiều lần trước.

npx -y @postman/mcp-server@latest --version

Mẹo: Lưu lại toàn bộ log tool call của một phiên sinh contract test quan trọng (copy ra file .md) - đây là tài liệu review rất hữu ích khi có thành viên mới trong team cần hiểu vì sao một assertion cụ thể được viết như vậy.