·

Postman MCP với Claude Code CLI and VS Code

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

Claude Code là môi trường lý tưởng để trải nghiệm Postman MCP vì nó cho phép agent vừa đọc source code endpoint, vừa gọi trực tiếp tool của Postman trong cùng một phiên làm việc - không cần copy-paste giữa terminal và trình duyệt. Bài này hướng dẫn cài đặt Postman MCP cho cả Claude Code CLI và extension Claude Code trong VS Code, sau đó đi qua toàn bộ vòng đời: sinh collection từ OpenAPI spec, viết assertion từ yêu cầu bằng ngôn ngữ tự nhiên, và chạy/đọc kết quả ngay trong terminal.

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

Claude Code hỗ trợ khai báo MCP server qua lệnh claude mcp add hoặc chỉnh trực tiếp file cấu hình. Cách nhanh nhất là dùng CLI:

claude mcp add postman \
  --command "npx" \
  --args "-y" "@postman/mcp-server" \
  --env POSTMAN_API_KEY=PMAK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sau khi thêm, kiểm tra server đã kết nối bằng:

claude mcp list

Nếu bạn dùng VS Code với extension Claude Code, cấu hình MCP nằm trong Settings (JSON) của workspace, thường ở .vscode/settings.json hoặc qua panel "MCP Servers" của extension:

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

Dùng ${env:POSTMAN_API_KEY} để VS Code đọc biến môi trường hệ thống thay vì hard-code key trong file settings dễ bị đồng bộ nhầm qua Settings Sync.

Mẹo: Sau khi add server, gõ thử /mcp trong Claude Code CLI để xem danh sách tool Postman MCP đã expose - nếu danh sách rỗng, 90% là do POSTMAN_API_KEY sai hoặc chưa được export đúng shell session đang chạy Claude Code.

Sinh Collection Từ OpenAPI Spec Bằng AI

Với spec OpenAPI có sẵn trong repo (ví dụ docs/openapi.yaml), bạn có thể yêu cầu Claude Code đọc file, hiểu cấu trúc endpoint, rồi gọi tool create-collection của Postman MCP để dựng toàn bộ collection tương ứng - đúng tên folder theo tag, đúng path parameter, đúng request body mẫu theo schema.

Prompt mẫu:

Đọc file docs/openapi.yaml. Tạo một collection Postman tên "Orders API v2" trong
workspace "AI Sandbox". Mỗi tag trong spec tương ứng một folder. Mỗi endpoint
tạo một request với body mẫu dựa theo example trong spec, không tự bịa field
ngoài spec.

Claude Code sẽ thực hiện tuần tự: đọc file bằng tool đọc file cục bộ, phân tích cấu trúc paths/components/schemas, sau đó gọi lần lượt các tool MCP create-collection → create-folder → create-request. Bạn sẽ thấy log từng lệnh gọi tool ngay trong terminal, giúp bạn theo dõi chứ không phải "hộp đen".

// Một lời gọi tool điển hình được log ra
{
  "tool": "create-request",
  "arguments": {
    "collectionId": "8b21...",
    "folderId": "orders-folder",
    "name": "GET /orders/{orderId}",
    "method": "GET",
    "url": "{{base_url}}/orders/:orderId",
    "pathVariables": [{ "key": "orderId", "value": "ORD-1001" }]
  }
}

Mẹo: Nếu spec quá lớn (hàng trăm endpoint), yêu cầu AI xử lý theo từng tag một lần thay vì "tạo hết trong một lượt" - vừa dễ review diff, vừa tránh timeout khi gọi liên tiếp quá nhiều tool call.

Viết Assertion và Test Script Từ Yêu Cầu Bằng Ngôn Ngữ Tự Nhiên

Điểm mạnh của Claude Code là bạn có thể diễn đạt yêu cầu nghiệp vụ bằng câu tiếng Việt/tiếng Anh thông thường, AI sẽ tự dịch sang test script Postman đúng cú pháp pm.test(). Ví dụ:

Với request POST /orders, thêm assertion:
- status phải là 201
- response trả về orderId dạng UUID
- field "total" phải bằng tổng (quantity * price) của từng item trong request body
- thời gian phản hồi dưới 1000ms

Kết quả AI sinh ra:

pm.test("Status is 201", () => pm.response.to.have.status(201));

pm.test("orderId is a valid UUID", () => {
    const body = pm.response.json();
    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
    pm.expect(body.orderId).to.match(uuidRegex);
});

pm.test("total matches sum of line items", () => {
    const req = JSON.parse(pm.request.body.raw);
    const body = pm.response.json();
    const expectedTotal = req.items.reduce((sum, i) => sum + i.quantity * i.price, 0);
    pm.expect(body.total).to.eql(expectedTotal);
});

pm.test("Response time under 1000ms", () => {
    pm.expect(pm.response.responseTime).to.be.below(1000);
});

Điều đáng chú ý: assertion thứ ba đòi hỏi AI phải parse lại chính request body vừa gửi để so sánh - đây là loại logic mà việc tự viết tay thường bị bỏ qua vì tốn công, nhưng AI viết khá nhanh khi được yêu cầu rõ ràng.

Mẹo: Luôn yêu cầu AI giải thích ngắn gọn logic của assertion phức tạp (như công thức tính total) ngay trong comment code - vừa giúp review nhanh hơn, vừa giúp người sau maintain không phải đọc lại từ đầu.

Chạy Collection và Đọc Kết Quả Lỗi Trong Terminal

Sau khi có collection và assertion, bạn có thể yêu cầu Claude Code gọi tool run-collection của Postman MCP, hoặc chạy trực tiếp bằng Postman CLI/Newman nếu muốn tích hợp log dạng terminal quen thuộc hơn:

postman collection run "8b21-collection-id" \
  --environment "staging-env-id" \
  --reporters cli,json \
  --reporter-json-export ./reports/run-result.json

Khi có request fail, Claude Code có thể đọc trực tiếp file run-result.json để phân tích nguyên nhân thay vì bạn phải tự mò log:

Đọc file reports/run-result.json, liệt kê các test fail, với mỗi fail giải
thích nguyên nhân có thể (do assertion sai, do response thay đổi field, hay
do lỗi môi trường/network), và đề xuất fix cho assertion nếu assertion đó
sai logic.

Một ví dụ output thực tế agent trả về:

FAIL: "total matches sum of line items" (POST /orders)
Nguyên nhân: response trả total = 150.00 (đã áp dụng discount 10%),
nhưng assertion tính total chưa trừ discount.
Đề xuất: sửa expectedTotal = rawTotal * (1 - discountRate) nếu request
có field discountRate.

Mẹo: Thêm bước --reporters cli,json là chìa khóa để AI "đọc lại" kết quả run một cách chính xác - nếu chỉ nhìn output CLI dạng bảng, AI dễ đọc sai số liệu hơn so với parse trực tiếp file JSON có cấu trúc.

Tiếp Postman MCP với OpenCode