Nếu công việc hằng ngày của bạn diễn ra trong Cursor, Claude Code hoặc VS Code, việc chuyển sang tab trình duyệt để đọc đặc tả API sẽ làm đứt mạch làm việc và mất ngữ cảnh. Apidog MCP Server giải quyết vấn đề này bằng cách đưa đặc tả API thực vào agent, để agent có thể đọc, tham chiếu và sinh mã theo đúng hợp đồng API ngay trong trình chỉnh sửa.
Tại sao nên đưa đặc tả API vào agent AI?
Agent AI thường sinh rất nhiều mã client API. Vấn đề là nếu không có đặc tả trong ngữ cảnh, agent sẽ đoán.
Ví dụ, khi bạn yêu cầu Cursor viết hàm gọi POST /orders, agent có thể:
- Tự tạo tên field không tồn tại.
- Dùng sai kiểu enum.
- Hiểu nhầm
statuslà string trong khi thực tế là integer. - Bỏ sót field bắt buộc.
- Sinh DTO không khớp schema.
Cách xử lý là đưa agent về đúng nguồn chân lý: đặc tả API.
Khi agent có thể đọc trực tiếp thiết kế API, nó không còn phải suy đoán cấu trúc request/response. Đây là mục tiêu chính của việc kết nối máy chủ MCP với đặc tả API: giảm hallucination, giảm vòng lặp sửa lỗi, và giúp mã sinh ra bám sát hợp đồng ngay từ đầu.
Cần làm rõ: “quản lý API” ở đây là công việc trong giai đoạn thiết kế, gồm đọc, tham chiếu, sinh mã và suy luận dựa trên hợp đồng API. Nó không phải quản lý lưu lượng runtime. Apidog không phải API gateway, không định tuyến request production, không throttle caller, và không nằm trong request path như Kong hay Apigee. Apidog tập trung vào thiết kế, mock, kiểm thử và tài liệu API; MCP Server đưa các phần đó vào agent của bạn.
Apidog MCP Server làm gì?
Apidog MCP Server cấp quyền đọc đặc tả API cho công cụ viết mã AI. Khi được kết nối, agent có thể truy vấn nội dung đặc tả theo yêu cầu thay vì chỉ suy luận từ codebase.
Theo tài liệu Apidog, một assistant kết nối qua MCP Server có thể:
- Sinh mã dựa trên đặc tả API.
- Tìm kiếm và truy vấn nội dung đặc tả.
- Cập nhật DTO theo field mới trong đặc tả.
- Thêm comment tài liệu vào code dựa trên đặc tả.
- Sinh mã MVC hoàn chỉnh cho endpoint cụ thể.
MCP Server chạy cục bộ và IDE giao tiếp với nó. Nó hoạt động với các trình chỉnh sửa hoặc agent có hỗ trợ MCP, gồm Cursor, VS Code và Claude Code.
Luồng cơ bản:
- Chuẩn bị nguồn đặc tả API.
- Kết nối Apidog MCP Server với công cụ AI.
- Trỏ server đến nguồn đặc tả.
- Yêu cầu agent sinh hoặc sửa code dựa trên hợp đồng API.
- Khi đặc tả thay đổi, yêu cầu agent làm mới dữ liệu.
Ba cách kết nối nguồn đặc tả
Bạn có thể chọn nguồn đặc tả tùy theo workflow hiện tại.
| Nguồn | Token cần thiết | Phù hợp nhất cho |
|---|---|---|
| Dự án Apidog | Token truy cập cá nhân | API nội bộ, riêng tư của nhóm được thiết kế trong Apidog |
| Tài liệu Apidog đã xuất bản | Không | Tài liệu API công khai đã publish |
| Tệp Swagger / OpenAPI cục bộ hoặc URL | Không | File openapi.yaml hoặc openapi.json trong repo hoặc được host ở nơi khác |
Điểm quan trọng: bạn không bắt buộc phải dùng dự án Apidog để bắt đầu. Nếu repo đã có openapi.yaml, agent vẫn có thể đọc file đó thông qua MCP Server và sinh mã dựa trên schema thực tế.
Ví dụ prompt trong Cursor hoặc Claude Code:
Đọc đặc tả API qua MCP Server và tạo TypeScript client cho endpoint POST /orders.
Đảm bảo request body, response type và enum khớp schema.
Hoặc:
Dựa trên đặc tả API hiện tại, cập nhật DTO OrderRequest trong src/dto/order.ts.
Không tự thêm field ngoài schema.
Các giới hạn cần biết
1. MCP Server chỉ đọc
Apidog MCP Server truy xuất và cung cấp dữ liệu đặc tả cho agent đọc. Nó không cho phép agent ghi ngược thay đổi vào thiết kế API thông qua server.
Bạn vẫn chỉnh sửa hợp đồng trong:
- Dự án Apidog.
- File OpenAPI/Swagger.
- Quy trình thiết kế API hiện tại của nhóm.
Agent sử dụng hợp đồng đó để sinh code, cập nhật DTO hoặc viết test.
2. Dữ liệu được cache cục bộ
Server giữ bản sao cục bộ của dữ liệu đặc tả để tăng tốc truy vấn. Nếu bạn vừa thay đổi API trong Apidog hoặc file OpenAPI, agent có thể vẫn đọc bản cũ.
Sau khi cập nhật thiết kế, hãy yêu cầu agent làm mới:
Làm mới đặc tả API từ MCP Server rồi kiểm tra lại DTO SubscriptionRequest.
3. Đây không phải API gateway
Apidog MCP Server không xử lý traffic production. Nó không route request, không rate limit, không xác thực caller ở runtime. Vai trò của nó là đưa hợp đồng API vào agent trong giai đoạn thiết kế và phát triển.
Apidog MCP Server nằm ở đâu trong workflow API?
MCP Server hữu ích nhất khi nó đứng trên cùng một hợp đồng API mà bạn dùng để mock, test và xuất tài liệu.
Mock API trước khi backend sẵn sàng
Frontend và agent không nên phải chờ backend hoàn chỉnh. Apidog có thể tạo mock server từ đặc tả để bạn phát triển dựa trên response thực tế sớm hơn.
Bạn có thể dùng mock API để:
- Cho frontend gọi endpoint trước khi backend triển khai xong.
- Cho agent sinh test dựa trên response mẫu.
- Kiểm tra request/response contract sớm.
- Chạy mock headless trong CI nếu cần.
Nếu bạn mới bắt đầu với mock API, xem thêm giải thích API mô phỏng và hướng dẫn mô phỏng API chuyên sâu. Khi so sánh công cụ, bài tổng hợp công cụ mock API tốt nhất sẽ hữu ích.
Chạy kiểm thử API từ CLI trong CI
Thiết kế API chỉ là một nửa. Bạn vẫn cần xác minh implementation có khớp contract hay không.
Apidog CLI cho phép chạy test headless bằng lệnh:
apidog run
CLI hỗ trợ:
- Chạy test API từ dòng lệnh.
- Data-driven testing với CSV hoặc JSON.
- Xuất báo cáo CLI, HTML, JSON và JUnit.
- Tích hợp với CI để pipeline đọc kết quả.
Xem thêm hướng dẫn kiểm thử REST API bằng dòng lệnh để có quy trình đầy đủ.
Điểm liên quan đến agent: công cụ AI có thể gọi CLI thay bạn.
Ví dụ prompt:
Chạy bộ kiểm thử API bằng Apidog CLI. Đọc báo cáo JUnit và tóm tắt các test thất bại.
Agent có thể gọi apidog run, đọc output và đề xuất sửa lỗi trong cùng phiên làm việc mà nó đã viết code.
Bảng workflow thực tế
| Giai đoạn | Thành phần Apidog | Chạy trong agent? |
|---|---|---|
| Đọc hợp đồng API | MCP Server, chỉ đọc | Có, qua MCP |
| Mock endpoint | Mock server, có thể chạy headless trong CI | Gián tiếp, agent dùng mock URL để viết code/test |
| Kiểm thử implementation | Apidog CLI với apidog run
|
Có, agent gọi CLI và đọc báo cáo |
| Quản lý vòng đời API | Dự án Apidog: thiết kế, version, tài liệu | Hiển thị cho agent qua MCP ở giai đoạn thiết kế |
Một vòng lặp thực tế trong Cursor
Giả sử bạn đang thêm endpoint POST /subscriptions vào một service hiện có.
Workflow có thể như sau:
- Thiết kế
POST /subscriptionstrong Apidog, gồm request schema, response schema và mã lỗi. - Kết nối Apidog MCP Server với Cursor.
- Yêu cầu agent tạo handler cho endpoint.
- Agent đọc schema qua MCP và sinh DTO đúng field, đúng type, đúng required flag.
- Yêu cầu agent viết test dựa trên mock endpoint.
- Yêu cầu agent chạy test bằng CLI.
- Agent đọc báo cáo và chỉ ra assertion bị fail.
- Nếu bạn chỉnh lại thiết kế API, yêu cầu agent refresh đặc tả rồi cập nhật code.
Ví dụ prompt:
Dựa trên đặc tả API qua MCP, tạo handler POST /subscriptions trong service hiện tại.
Sinh DTO, validation và response mapping. Không thêm field ngoài schema.
Sau đó:
Viết test cho POST /subscriptions dựa trên mock server.
Chạy test bằng Apidog CLI và báo cáo lỗi nếu có.
Bạn không cần mở trình duyệt để tra schema thủ công. Hợp đồng API vẫn là nguồn chân lý, còn agent bám theo hợp đồng đó.
Để xem thêm workflow trực quan, tham khảo gỡ lỗi trực quan với Apidog MCP client. Nếu cần kiểm thử MCP server, xem sổ tay kiểm thử máy chủ MCP.
So sánh với các công cụ CLI và đặc tả khác
Nhiều công cụ xử lý một phần của workflow này. Khác biệt chính nằm ở phạm vi.
- Newman chạy Postman collection từ dòng lệnh. Nó mạnh ở vai trò test runner cho collection, nhưng không phải cầu nối MCP để agent đọc contract thiết kế trong IDE.
- inso từ Insomnia CLI chạy collection và lint đặc tả từ terminal. Nó hữu ích cho workflow Insomnia, nhưng không tập trung vào việc đưa đặc tả vào agent qua MCP.
- Prism mock và validate dựa trên OpenAPI. Nó rất tốt cho mock theo spec, nhưng là công cụ tập trung cho một phần workflow.
- WireMock và Mockoon CLI là mock server mạnh. Chúng giải quyết tốt bài toán mock, nhưng không quản lý toàn bộ vòng đời contract hoặc expose đặc tả cho agent qua MCP.
Góc nhìn của Apidog không phải là “một test runner khác”. Điểm chính là dùng một hợp đồng API để thúc đẩy thiết kế, mock, kiểm thử, tài liệu và cung cấp ngữ cảnh cho agent qua MCP.
Nếu bạn đang so sánh test runner, xem thêm Apidog CLI vs Postman CLI. Nếu muốn thiết kế pipeline rộng hơn, tham khảo các thực hành kiểm thử CI/CD cho API.
FAQ
Agent AI có thể chỉnh sửa đặc tả API qua MCP Server không?
Không. Apidog MCP Server chỉ đọc. Agent có thể đọc, tìm kiếm và sinh mã từ đặc tả, nhưng không ghi ngược thay đổi vào thiết kế API qua server.
Bạn chỉnh sửa contract trong Apidog hoặc file OpenAPI, sau đó yêu cầu agent làm mới để đọc phiên bản mới.
Tôi có cần tài khoản Apidog để dùng MCP Server không?
Không phải với mọi nguồn.
- Dự án Apidog riêng tư cần token truy cập cá nhân.
- Tài liệu Apidog đã publish không cần token.
- File Swagger/OpenAPI cục bộ hoặc qua URL không cần token.
Vì vậy, bạn có thể bắt đầu bằng một file openapi.yaml trong repo.
Đây có phải API gateway không?
Không. MCP Server và nền tảng Apidog tập trung vào giai đoạn thiết kế: thiết kế, mock, kiểm thử và tài liệu API. Chúng giúp bạn quản lý API như một sản phẩm, nhưng không route hoặc throttle traffic production.
Nếu cần runtime gateway, bạn vẫn cần công cụ như Kong hoặc Apigee.
Những công cụ AI nào có thể dùng với nó?
Bất kỳ công cụ viết mã AI nào hỗ trợ MCP, gồm Cursor, VS Code và Claude Code. Bạn kết nối server cho từng công cụ, trỏ đến nguồn đặc tả, rồi agent có thể truy vấn từ đó.
Tổng kết
Ý tưởng cốt lõi rất đơn giản: giữ hợp đồng API làm nguồn chân lý và cho agent AI đọc hợp đồng đó ngay trong nơi bạn viết code.
Apidog MCP Server đưa đặc tả API vào Cursor, Claude Code hoặc VS Code để agent ngừng đoán schema và bắt đầu sinh mã theo thiết kế thực tế. Khi kết hợp với mock server và Apidog CLI, bạn có thể xây dựng vòng lặp thiết kế → mock → code → test ngay trong trình chỉnh sửa.
Chỉ cần nhớ ranh giới: đây là workflow quản lý vòng đời API ở giai đoạn thiết kế và phát triển, không phải API gateway runtime.
Bạn có thể bắt đầu bằng cách tải xuống Apidog, kết nối MCP Server với trình chỉnh sửa, rồi trỏ agent vào một đặc tả API thực tế. Tài liệu tại Apidog hướng dẫn cách cấu hình từng nguồn đặc tả.
Top comments (0)