Điểm khác biệt lớn nhất khi dùng Postman MCP qua Cursor so với các CLI agent khác là AI có thể nhìn thấy đồng thời cả source code controller/route và collection Postman trong cùng một cửa sổ - không cần chuyển qua chuyển lại giữa editor và terminal. Điều này biến Cursor thành công cụ mạnh để giữ test API luôn đồng bộ với code thực tế, và để debug test fail bằng cách đối chiếu trực tiếp với implementation. Bài này hướng dẫn kết nối Postman MCP vào Cursor Agent Mode, cách giữ collection đồng bộ với code, workflow debug test fail, và các giới hạn cần biết.
Kết Nối Postman MCP Với Cursor Agent Mode
Cursor hỗ trợ MCP qua file .cursor/mcp.json ở project hoặc ~/.cursor/mcp.json ở global. Thêm cấu hình:
{
"mcpServers": {
"postman": {
"command": "npx",
"args": ["-y", "@postman/mcp-server"],
"env": {
"POSTMAN_API_KEY": "PMAK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}
Mở Cursor Settings → MCP, bạn sẽ thấy server "postman" với trạng thái xanh (connected) và danh sách tool bên dưới - đây cũng là nơi bạn tắt/bật từng tool riêng lẻ nếu muốn giới hạn quyền của agent (ví dụ chỉ cho phép tool đọc, tắt hết tool ghi/xóa trong giai đoạn đầu làm quen).
Để dùng, mở Agent Mode (Cmd/Ctrl + I hoặc chọn "Agent" trong panel chat), gõ yêu cầu như bình thường - Cursor tự quyết định khi nào cần gọi tool Postman MCP dựa trên ngữ cảnh câu hỏi.
@codebase Đọc controller OrderController.java, tạo/cập nhật collection
Postman "Order API" tương ứng với các endpoint hiện có trong controller này.
Mẹo: Trong Cursor Settings → MCP, tắt hẳn các tool có khả năng phá hoại như
delete-collection,delete-environmenttrong giai đoạn đầu - Cursor Agent Mode có thể tự quyết định gọi tool mà không luôn hỏi lại bạn từng bước như một số CLI agent khác.
Giữ Collection Đồng Bộ Với Code Controller và Route
Vấn đề kinh điển của test API viết tay: sau vài tháng, code đã đổi route/param nhưng collection Postman vẫn giữ nguyên endpoint cũ, dẫn đến test fail sai lý do (không phải do bug mà do test lỗi thời). Với Cursor nhìn thấy cả code và Postman MCP cùng lúc, bạn có thể yêu cầu đối chiếu định kỳ:
So sánh danh sách route trong file routes/orders.routes.ts với danh sách
request trong collection Postman "Order API". Liệt kê:
1. Route nào có trong code nhưng chưa có request tương ứng trong collection
2. Request nào trong collection tham chiếu route không còn tồn tại trong code
3. Route nào đổi tham số (path param, query param) nhưng request cũ chưa cập nhật
Agent gọi get-collection để lấy toàn bộ request hiện có, đối chiếu với AST của file route đọc trực tiếp từ code, rồi trả về báo cáo dạng danh sách - từ đó bạn quyết định để AI tự sửa hay tự sửa tay từng trường hợp.
Kết quả đối chiếu:
1. Thiếu request cho: DELETE /orders/{orderId}/cancel (route mới, chưa có test)
2. Request lỗi thời: "GET /orders/list" - route này đã đổi thành "GET /orders" (không còn "/list")
3. Request "GET /orders/{id}" cần đổi thành "GET /orders/{orderId}" để khớp tên param mới trong code
Sau khi review, yêu cầu AI áp dụng fix:
Cập nhật đúng 3 điểm trên trong collection "Order API", giữ nguyên các
request khác không đổi.
Mẹo: Đưa việc đối chiếu route-vs-collection này vào checklist trước mỗi lần merge PR có đổi route - phát hiện lệch sớm ở PR review rẻ hơn rất nhiều so với phát hiện khi CI báo fail hàng loạt sau merge.
Debug Test Fail Bằng Cách Đối Chiếu Với Code Implementation Trong Cursor
Khi một test Postman fail, câu hỏi đầu tiên luôn là: lỗi ở code hay lỗi ở test? Với Cursor, bạn để AI đọc cả log fail và code xử lý endpoint đó cùng lúc để đưa ra chẩn đoán có căn cứ, thay vì đoán mò.
Test "PATCH /orders/{id}/status - invalid transition" đang fail với lỗi:
expect status 400 nhưng thực tế trả về 500. Đọc OrderService.java, hàm
updateStatus(), giải thích tại sao có thể xảy ra 500 thay vì 400, và đề
xuất fix ở code hoặc ở test - nói rõ lý do chọn phương án nào.
Ví dụ phản hồi thực tế agent có thể đưa ra sau khi đọc code:
Nguyên nhân: hàm updateStatus() throw NullPointerException khi
currentStatus == null (trường hợp order mới tạo, chưa có status), code
hiện tại không catch exception này thành 400 mà để lọt ra ngoài GlobalExceptionHandler,
handler default trả 500.
Đề xuất: SỬA CODE (không sửa test) - vì test đang đúng theo spec nghiệp vụ
(chuyển trạng thái không hợp lệ phải trả 400, không phải lỗi hệ thống).
Thêm validate currentStatus != null trước khi check transition rule, throw
InvalidStatusTransitionException (map sang 400) thay vì để NPE lọt ra.
Đây là điểm khác biệt quan trọng: AI không chỉ báo "test fail", mà đưa ra khuyến nghị có lý do rõ ràng nên sửa code hay sửa test - quyết định cuối cùng vẫn nên do bạn xác nhận, nhưng AI đã rút gọn phần lớn công việc điều tra.
Mẹo: Luôn yêu cầu AI nêu rõ "sửa code hay sửa test, vì sao" thay vì chỉ đưa fix - tránh trường hợp AI có xu hướng "làm cho test pass" bằng cách nới lỏng assertion, che giấu bug thật trong code.
Giới Hạn và Cách Khắc Phục Khi Dùng Postman MCP Trong Cursor
- Agent Mode có thể gọi tool mà không hỏi xác nhận từng bước như đã nói ở phần 1 - khắc phục bằng cách tắt tool nguy hiểm trong Settings, hoặc dùng chế độ review diff trước khi apply nếu Cursor phiên bản bạn dùng hỗ trợ.
- Context giới hạn khi mở nhiều file lớn cùng lúc: nếu vừa mở toàn bộ OpenAPI spec, vừa mở nhiều file controller, vừa gọi Postman MCP, agent có thể bị cắt bớt context và bỏ sót vài route khi đối chiếu - nên giới hạn phạm vi file mở trong một session cho từng module cụ thể.
- Không có lịch sử version riêng cho thay đổi qua MCP: khác với sửa code có git track từng dòng, thay đổi trên Postman qua MCP chỉ có lịch sử của Postman Cloud (nếu team trả phí đủ cao để có version history) - nên vẫn cần thói quen export snapshot JSON định kỳ như một lớp bảo hiểm.
- Một số phiên bản @postman/mcp-server chưa hỗ trợ đầy đủ collection có Postman Flows (luồng logic phức tạp dạng visual) - nếu team đang dùng Flows nhiều, kiểm tra kỹ tool có hỗ trợ trước khi để AI sửa các collection loại này.
Mẹo: Với collection quan trọng (liên quan payment, auth), bật review mode nghiêm ngặt hơn: yêu cầu Cursor Agent chỉ đề xuất thay đổi dưới dạng plan text trước, bạn duyệt bằng lời rồi mới cho phép gọi tool ghi thật - đổi lấy một chút chậm hơn nhưng an toàn hơn nhiều cho các phần nhạy cảm.