·

Postman MCP với OpenCode

Cài đặt Postman MCP trong OpenCode để AI agent có thể chạy và quản lý API collection, test suite ngay trong trình soạn thảo.

OpenCode là một trong những terminal-based AI coding agent mã nguồn mở đang được nhiều team dùng thay thế hoặc song song với Claude Code, và nó hỗ trợ MCP theo đúng chuẩn nên việc gắn Postman MCP vào không khác biệt nhiều về nguyên lý - nhưng có vài điểm cấu hình và hạn chế riêng bạn cần biết trước khi đưa vào quy trình chính thức. Bài này đi qua cách cài đặt, cách quản lý collection/environment/run ngay trong OpenCode, một ví dụ dựng smoke test suite thực tế, và những giới hạn hiện tại của OpenCode khi làm việc với Postman MCP.

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

OpenCode dùng file cấu hình opencode.json (ở thư mục gốc project hoặc ~/.config/opencode/) để khai báo MCP server. Thêm block sau vào mục mcp:

{
  "mcp": {
    "postman": {
      "type": "local",
      "command": ["npx", "-y", "@postman/mcp-server"],
      "environment": {
        "POSTMAN_API_KEY": "PMAK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      "enabled": true
    }
  }
}

Khởi động lại OpenCode, sau đó gõ lệnh nội bộ để kiểm tra server đã sống:

opencode
> /mcp
postman: connected (14 tools available)

Nếu server hiện trạng thái error hoặc disconnected, nguyên nhân phổ biến nhất là npx chưa cache được package @postman/mcp-server lần đầu (do máy chưa có kết nối mạng lúc chạy), hoặc POSTMAN_API_KEY bị thiếu quyền do key đã bị revoke.

Mẹo: Chạy thử npx -y @postman/mcp-server --version trực tiếp ngoài OpenCode trước khi khai báo vào config - việc cách ly bước cài package khỏi bước OpenCode khởi động server giúp bạn xác định lỗi nằm ở network/npm hay ở chính OpenCode nhanh hơn nhiều.

Quản Lý Collection, Environment và Run Ngay Trong OpenCode

Một khi server đã kết nối, bạn có thể ra lệnh trực tiếp bằng ngôn ngữ tự nhiên trong session chat của OpenCode mà không cần mở Postman app:

Liệt kê tất cả collection trong workspace "Payments Team". Với collection
"Refund API", cho tôi xem cấu trúc folder và số lượng request trong mỗi folder.

OpenCode sẽ gọi list-collections, get-collection và trả về dạng cây thư mục dễ đọc trong terminal. Để thao tác trên environment:

Trong environment "staging", thêm biến REFUND_MAX_AMOUNT = 5000000 (kiểu
number, không phải secret). Sau đó chạy toàn bộ folder "Refund - Negative
Cases" trên environment này và cho tôi biết có bao nhiêu request fail.

OpenCode gọi lần lượt update-environment rồi run-collection với tham số folderId để chỉ chạy đúng phần cần test - tránh chạy lại toàn bộ collection mất thời gian khi bạn chỉ cần kiểm tra một nhóm nhỏ.

{
  "tool": "run-collection",
  "arguments": {
    "collectionId": "refund-api-id",
    "environmentId": "staging-env-id",
    "folderId": "refund-negative-cases-folder-id"
  }
}

Mẹo: Luôn chỉ định rõ folderId khi chỉ muốn test một phần - nếu không, một số phiên bản MCP server sẽ mặc định chạy toàn bộ collection, tốn thời gian và dễ đụng vào rate limit của Postman API nếu collection lớn.

Ví Dụ Thực Tế: Dựng Smoke Test Suite Cho Một REST API

Giả sử bạn vừa deploy một service REST API mới lên staging và cần smoke test (bộ test nhanh xác nhận hệ thống không "chết" sau deploy) trong vài phút. Quy trình với OpenCode + Postman MCP:

  1. Prompt khởi tạo:
Tạo collection "Order Service - Smoke Test" trong workspace "AI Sandbox".
Với mỗi endpoint quan trọng sau, tạo 1 request kiểm tra service còn sống:
GET /health, GET /orders?limit=1, POST /orders (dùng payload mẫu tối thiểu),
GET /orders/{id đã tạo ở bước trước}.
  1. Chuỗi request nối tiếp: OpenCode cần AI tự lấy orderId trả về từ response POST /orders và gán vào biến environment để dùng cho request GET tiếp theo - đây là dạng chaining request (chuỗi request phụ thuộc nhau) mà Postman hỗ trợ qua script pm.environment.set(...).
// Test script tự sinh cho request POST /orders, lưu id để dùng ở request sau
pm.test("Order created", () => pm.response.to.have.status(201));

const body = pm.response.json();
pm.environment.set("smoke_order_id", body.orderId);
  1. Request kế tiếp tham chiếu biến vừa lưu:
GET {{base_url}}/orders/{{smoke_order_id}}
  1. Chạy toàn bộ chuỗi và tổng hợp kết quả:
Chạy collection "Order Service - Smoke Test" trên environment "staging",
báo cho tôi biết health check và toàn bộ chuỗi tạo/đọc order có pass không,
nếu fail chỉ rõ request nào và lý do.

Mẹo: Với smoke test cần chạy chuỗi request phụ thuộc nhau, luôn yêu cầu AI đặt tên biến environment có tiền tố rõ ràng (ví dụ smoke_*) để tránh đụng namespace với biến của các test suite khác đang dùng chung environment "staging".

Hạn Chế Hiện Tại Của Postman MCP Trong OpenCode

Trước khi coi OpenCode là công cụ chính cho toàn bộ workflow Postman MCP, cần biết rõ vài giới hạn thực tế:

  • Không có UI xem trực quan: OpenCode là terminal-based, nên khi AI tạo ra một collection lớn, bạn không có preview trực quan như Postman app - phải mở web/app Postman song song để review, hoặc export ra JSON để đọc diff.
  • Streaming tool call dài dễ bị ngắt: với collection có hàng chục request cần tạo liên tiếp, một số phiên bản OpenCode có thể timeout giữa chừng nếu mỗi tool call phải chờ phản hồi tuần tự - nên chia nhỏ theo folder như đã nói ở phần 2.
  • Chưa hỗ trợ tốt Postman Vault qua MCP tool (tùy phiên bản @postman/mcp-server) - một số secret vẫn phải thiết lập tay qua Postman app hoặc CLI postman vault set rồi mới tham chiếu được từ OpenCode.
  • Không có cơ chế "undo" tool call: nếu AI tạo/sửa nhầm request, bạn phải tự sửa lại hoặc revert bằng cách khôi phục từ bản export JSON cũ, MCP hiện chưa có audit log tích hợp riêng để rollback nhanh.

Mẹo: Trước mỗi phiên làm việc quan trọng, export toàn bộ collection ra file JSON và commit vào một nhánh git riêng (postman-snapshots) - đây là cách "undo" thủ công nhưng đáng tin cậy nhất khi MCP chưa có rollback tự động.

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

Một vài kinh nghiệm nhỏ nhưng giúp tiết kiệm rất nhiều thời gian khi dùng bộ đôi này lâu dài:

  • Tách config MCP theo project: đặt opencode.json riêng cho mỗi repo thay vì dùng chung config global - mỗi project thường cần workspace Postman khác nhau, gộp chung dễ gây nhầm lẫn agent thao tác sai workspace.
  • Log lại lịch sử prompt quan trọng: lưu các prompt đã dùng để sinh collection/test vào một file prompts/postman-mcp.md trong repo - lần sau cần sinh lại hoặc mở rộng, bạn tái sử dụng prompt đã được kiểm chứng thay vì viết lại từ đầu mỗi lần.
  • Giới hạn số tool call mỗi phiên: với OpenCode, nên chia nhỏ tác vụ lớn (ví dụ "tạo 50 request") thành nhiều phiên nhỏ hơn (10-15 request/lần) để dễ review và giảm rủi ro timeout đã nói ở phần giới hạn.
  • Đặt alias lệnh thường dùng: tạo shell alias hoặc script wrapper cho các lệnh postman collection run hay dùng, để không phải nhớ lại toàn bộ tham số --environment, --reporters mỗi lần gọi tay ngoài OpenCode.
alias pm-run-staging='postman collection run "$PM_COLLECTION_ID" --environment "$PM_STAGING_ENV_ID" --reporters cli,json'

Mẹo: Định kỳ mỗi tuần, yêu cầu AI tự rà lại toàn bộ collection để tìm request "orphan" (không còn tag/folder rõ ràng do lịch sử sửa nhiều lần) và đề xuất dọn dẹp - collection do AI liên tục chỉnh sửa dễ tích tụ rác nếu không có ai chủ động dọn.

Tiếp Postman MCP với Gemini CLI