Đây là loạt 10 bài chia sẻ cách Apidog phát triển Apidog CLI, công cụ dòng lệnh dùng để kiểm thử API và quản lý vòng đời API. Bạn có thể đọc theo thứ tự hoặc nhảy đến bài phù hợp với nhu cầu triển khai của mình.
| Tiêu đề | Trọng tâm | |
|---|---|---|
| 1 | Chúng tôi đã xây dựng 126 công cụ MCP. Nhưng đó không phải là giải pháp tốt nhất cho Agent | Khám phá vấn đề |
| 2 | Tại sao chúng tôi phát triển Apidog CLI hoàn toàn mới | Phát triển kiến trúc |
| 3 | Quy tắc vàng: CLI tạo ra sự thật, Model hành động dựa trên sự thật | Triết lý cốt lõi |
| 4 | agentHints: Dạy CLI giao tiếp với Agent |
Đầu ra có cấu trúc |
| 5 | SKILL: Đóng gói trải nghiệm vận hành thành mã | Trải nghiệm vận hành |
| 6 | Con số không biết nói dối: Giảm 30% lượt gọi công cụ, giảm 25% token | Kết quả định lượng |
| 7 | Từ PRD đến vòng lặp kiểm thử: Một quy trình làm việc Agent hoàn chỉnh với Apidog CLI | Hướng dẫn thực hành |
| 8 | Tại sao khả năng tương thích CI/CD là không thể bỏ qua đối với công cụ Agent | Góc nhìn DevOps |
| 9 | AI Branch: Thay đổi dự án an toàn hơn với AI Agents | Lớp bảo mật |
| 10 | Spec-First đã là quá khứ. Chào mừng đến với Skill-First. | Tầm nhìn & tương lai |
Khi MCP trở thành điểm nóng của ngành, chúng tôi đã xây dựng một MCP Server hoàn chỉnh với 126 công cụ được tạo. Đây là những gì đã sai — và tại sao nhiều công cụ hơn không có nghĩa là Agent được hỗ trợ tốt hơn.
Cơn sốt MCP
Đầu năm 2025, MCP, viết tắt của Model Context Protocol, trở thành một điểm nóng của ngành.
Anthropic quảng bá giao thức này. Cursor, Claude Code, Antigravity, nhiều Agent IDE và sản phẩm SaaS nhanh chóng làm theo. MCP hứa hẹn một cách tiêu chuẩn hóa để AI Agents kết nối với công cụ và nguồn dữ liệu bên ngoài.
Khi đó, gần như mọi sản phẩm có API đều nhận cùng một câu hỏi:
"Bạn có MCP không?"
Với Apidog, lựa chọn này nghe có vẻ rất tự nhiên.
Tại sao MCP dường như là câu trả lời
Apidog đã có sẵn một tập hợp năng lực phát triển API khá đầy đủ:
- Tài liệu API
- Định nghĩa Schema
- Mock servers
- Test cases
- Test scenarios
- Test suites
- Báo cáo kiểm thử
- Quy trình nhập/xuất
- Cộng tác nhánh
- Và nhiều năng lực khác
Nếu Agents trở thành điểm truy cập phần mềm mới, việc phơi bày các khả năng này qua MCP có vẻ là bước cần làm.
Kỳ vọng ban đầu của chúng tôi khá rõ:
- Agent truy vấn tài liệu API
- Agent tạo test case
- Agent chạy test scenario
- Agent nhập/xuất dữ liệu dự án
- Agent quản lý môi trường và biến
- Agent cộng tác giữa các nhánh
Logic khi đó là:
Càng nhiều khả năng được phơi bày = Agent càng được hỗ trợ tốt hơn.
Nhưng khi triển khai thực tế, công thức này không còn đúng.
Những gì chúng tôi thực sự đã xây dựng
Chúng tôi không xây một bản demo MCP đơn giản.
Apidog MCP là một MCP Server hoàn chỉnh, gồm hệ thống phiên, danh mục công cụ và lớp khám phá động.
1. Hệ thống phiên
Client MCP khởi tạo một phiên. Server tạo sessionId và lưu trạng thái phiên qua Redis. Các request tiếp theo tiếp tục truy cập bằng sessionId.
Nói cách khác, đây không phải một HTTP call đơn lẻ, mà là một hệ thống phiên cấp giao thức.
Một flow tối giản có thể hình dung như sau:
MCP Client
-> initialize
-> receive sessionId
-> call tool with sessionId
-> keep session alive
-> close/delete session
2. Danh mục công cụ
Chúng tôi chia công cụ của Apidog thành nhiều nhóm thay vì viết thủ công vài endpoint cố định.
| Danh mục | Mô tả | Ví dụ |
|---|---|---|
| Công cụ dự án gốc | Dùng cho thao tác cấp dự án | Tóm tắt dự án, cấu trúc thư mục, chi tiết tài nguyên |
| Công cụ miền tích hợp | Chức năng cốt lõi của Apidog | Nhập/xuất, chi tiết endpoint, test case, test scenario |
| Công cụ OpenAPI được tạo | Tự động chuyển đổi từ định nghĩa OpenAPI | 126 công cụ với định danh, path, HTTP method, input schema |
Nhóm cuối cùng là điểm đáng chú ý nhất: 126 công cụ được tạo.
Mỗi công cụ có:
- Mã định danh duy nhất
- API path cụ thể
- HTTP method như
GET,POST,PUT,DELETE - Input schema đầy đủ, gồm mô tả field, type và enum
- Cấu trúc trả về được định nghĩa
3. Tiết lộ dần dần
Để tránh phơi bày toàn bộ endpoint ngay từ đầu, chúng tôi xây một lớp khám phá động.
Agent được kỳ vọng thực hiện theo thứ tự:
- Tìm các endpoint tool có sẵn bằng
listOpenApiEndpoints - Lấy chi tiết OpenAPI của tool cụ thể bằng
getOpenApiDetails - Thực hiện HTTP call thực tế bằng
executeOpenApi
Ví dụ flow:
User request
-> listOpenApiEndpoints
-> getOpenApiDetails(toolId)
-> executeOpenApi(toolId, input)
-> return result
Mục tiêu là để Agent tìm kiếm trước, đọc chi tiết sau, rồi mới thực thi.
Trên giấy tờ, mô hình này hợp lý. Trong tác vụ thật, vấn đề xuất hiện rất nhanh.
Bức tường công cụ ngẫu nhiên
Xem xét một yêu cầu đơn giản:
"Hãy giúp tôi thêm một bài kiểm thử cho endpoint này và chạy xác minh."
Từ góc độ sản phẩm, Apidog có đủ năng lực để làm việc này:
- Tìm endpoint
- Tạo test case
- Chạy test scenario
- Tạo báo cáo
Nhưng từ góc độ Agent, request đơn giản này biến thành nhiều quyết định liên tiếp.
| Điểm quyết định | Tùy chọn | Không chắc chắn |
|---|---|---|
| Bắt đầu từ đâu? | Tìm dự án trước? Tìm endpoint trước? | Không có hướng dẫn rõ ràng |
| Đọc gì? | Đọc chi tiết endpoint? Liệt kê test case hiện có? | Cả hai đều có vẻ hợp lệ |
| Tạo như thế nào? | Gọi createTestCase trực tiếp? Tìm nhóm case trước? |
Yêu cầu không rõ ràng |
| Cập nhật như thế nào? | Gọi tool update? Nhập steps rồi đọc lại? | Workflow bị ẩn |
Vấn đề không chỉ là "Agent có gọi được tool không".
Vấn đề là:
Agent phải giải quyết câu hỏi "nên dùng tool nào, theo thứ tự nào" trước khi giải quyết yêu cầu thật của người dùng.
Từ góc độ triển khai, mọi thứ đều có thể được biểu diễn bằng tool. Nhưng từ góc độ trải nghiệm Agent, chúng tạo thành một bức tường công cụ ngẫu nhiên.
Bốn vấn đề cấu trúc
Qua kiểm thử thực tế và phản hồi nội bộ, chúng tôi xác định bốn vấn đề cấu trúc với cách tiếp cận MCP cho tác vụ R&D phức tạp.
Vấn đề 1: Chi phí khám phá công cụ tăng nhanh
Apidog không phải sản phẩm có thể mô tả bằng một tá endpoint.
| Module | Phân tích |
|---|---|
| Endpoints | Liệt kê, lấy, tạo, cập nhật, xóa |
| Schemas | Liệt kê, lấy, tạo, cập nhật, xóa |
| Môi trường | Liệt kê, lấy, tạo, cập nhật, xóa, biến |
| Mocks | Cấu hình, bật, tắt |
| Test cases | Liệt kê, lấy, tạo, cập nhật, xóa, sao chép |
| Test scenarios | Liệt kê, lấy, tạo, cập nhật, xóa, nhập steps, chạy |
| Test suites | Liệt kê, lấy, tạo, cập nhật, xóa |
| Báo cáo | Liệt kê, lấy, tạo, tải xuống |
| Nhập/xuất | Nhiều định dạng và tùy chọn |
| Nhánh | Liệt kê, tạo, gộp, xóa |
Khi số lượng tool tăng từ một tá lên hàng chục hoặc hàng trăm, Agent phải làm thêm một bước trước khi xử lý yêu cầu:
Hiểu yêu cầu người dùng
-> tìm tool phù hợp
-> đọc mô tả tool
-> so sánh với tool khác
-> chọn trình tự gọi
-> mới bắt đầu thực thi
Chúng tôi từng cố nhúng workflow vào description của tool. Ví dụ:
"Trước khi truy vấn dữ liệu endpoint, bạn cần xác nhận dự án bằng một tool khác, sau đó lấy metadata dự án bằng tool thứ ba, rồi cuối cùng gọi tool hiện tại."
Cách này có thể dùng với bộ tool nhỏ. Nhưng trong một danh sách tool lớn, description cũng cạnh tranh sự chú ý của model.
Càng viết nhiều hướng dẫn vào mô tả, càng tốn token. Và càng tốn token, Agent càng ít khả năng đọc kỹ và tuân thủ đúng.
Vấn đề 2: Business Schema xâm lấn context
Một MCP tool không chỉ gồm tên tool.
Mỗi tool thường mang theo:
-
description: tool làm gì -
input schema: tham số, type, required/optional - Giải thích field, gồm cấu trúc lồng nhau và ràng buộc
- Enum value
- Cấu trúc trả về
- Quy ước xử lý lỗi
Ước tính thận trọng:
| Yếu tố | Giá trị |
|---|---|
| Số lượng tool | 100+ |
| Số token trung bình mỗi tool | ~500 |
| Tổng token mô tả tool | ~50.000 |
Một câu hỏi của người dùng có thể chỉ dài vài chục ký tự. Nhưng model có thể phải mang theo hàng chục nghìn token mô tả tool cho một MCP server.
Đây không chỉ là giả thuyết. Bài viết chính thức của Cursor, "Dynamic Context Discovery", đưa ra dữ liệu tham chiếu quan trọng: bằng cách chuyển mô tả MCP tool, terminal sessions và hội thoại dài thành context tải theo nhu cầu, mức tiêu thụ token thời gian chạy giảm 46,9%.
Cách tiếp cận của Trae còn trực tiếp hơn: giới hạn số lượng MCP tool và độ dài mô tả từng tool.
- Giới hạn số lượng tool: 40
- Giới hạn mô tả tool đơn lẻ: 8000 ký tự
Trong kiểm thử nội bộ ban đầu, nhiều nhóm báo cáo rằng một số tool của Apidog MCP không thể được gọi trong Trae. Agent phải đánh đổi vì giới hạn context của model, và tool bên ngoài là nhóm đầu tiên bị cắt bỏ.
Kết luận thực tế:
Mô tả tool không thể được đưa vô hạn vào context của model.
Vấn đề 3: Phiên giao thức làm chuỗi thực thi nặng hơn
Apidog MCP server cần xử lý nhiều trạng thái giao thức.
| Trạng thái giao thức | Mô tả |
|---|---|
| Khởi tạo MCP | Bắt tay giữa client và server |
Tạo sessionId
|
Mã định danh duy nhất cho phiên |
| Lưu trữ phiên Redis | Duy trì trạng thái |
| Kết nối/đóng transport | Quản lý kết nối |
| Chạm phiên | Cơ chế keep-alive |
| Xóa phiên | Dọn dẹp khi hoàn tất |
| Phản hồi JSON hoặc cấu hình SSE | Tùy chọn định dạng đầu ra |
Với một tool call đơn giản, chi phí này có thể chấp nhận.
Nhưng với tác vụ Agent có nhiều lần gọi tool và nhiều bước khám phá, quản lý trạng thái làm tăng độ phức tạp ở cả server lẫn client.
Khi triển khai Apidog MCP, nhóm phải dành nhiều công sức để xử lý khác biệt giữa các Agent client như Cursor, Claude Code, Antigravity, Trae. Trong khi đó, MCP vẫn tiếp tục thay đổi và được vá qua các phiên bản mới.
Kết quả là chi phí vận hành không chỉ nằm ở business logic, mà còn nằm ở tầng tương thích giao thức.
Vấn đề 4: Tool nguyên tử không diễn tả được ngữ nghĩa sản phẩm
Trong Apidog, một test scenario không chỉ là một mảng steps.
Một scenario có thể bao gồm:
| Thành phần | Độ phức tạp |
|---|---|
| Nhập | Steps từ endpoint hoặc case hiện có |
| Đọc lại | Nhận cấu trúc đầy đủ sau khi nhập |
| Case nội bộ | HTTP request được nhúng trong steps |
| Tiền/hậu xử lý | Script trước/sau request |
| Xác nhận | Quy tắc xác thực response |
| Trích xuất biến | Thu thập giá trị từ response |
| Môi trường runtime | Chọn environment và biến |
| Xác minh báo cáo | Kiểm tra kết quả test |
Nếu chia toàn bộ thành các MCP tool nguyên tử, Agent vẫn phải tự điều phối workflow kiểm thử.
Agent cần hiểu các câu hỏi nội bộ như:
- Vì sao sau khi nhập phải đọc lại?
- Vì sao case nội bộ có cơ chế cập nhật khác nhau?
- Vì sao assertion cần comparator cụ thể?
- Vì sao trích xuất biến có ràng buộc type?
Đây không còn là vấn đề gọi API. Đây là vấn đề hiểu ngữ nghĩa sản phẩm.
Tool càng nguyên tử, model càng phải hiểu nhiều logic nội bộ để điều phối đúng.
Điều đó buộc nhóm sản phẩm phải thêm các lớp chuyển đổi chỉ để giúp MCP tool dễ dùng hơn với Agent. Chi phí kỹ thuật và bảo trì tăng lên đáng kể.
Nguyên nhân gốc rễ
Bốn vấn đề trên có cùng một nguyên nhân:
MCP phù hợp để kết nối tool, nhưng các tác vụ R&D phức tạp cần nhiều hơn kết nối tool. Chúng cần quy trình kỹ thuật có thể thực thi.
| Điểm mạnh của MCP | Hạn chế của MCP |
|---|---|
| Kết nối tiêu chuẩn hóa | Không diễn tả được workflow |
| Giao thức thống nhất | Không hướng dẫn được trình tự |
| Phơi bày tool | Không thực thi được validation |
| Khám phá động | Không cung cấp được phán đoán kỹ thuật |
Với sản phẩm đơn giản có khoảng một tá thao tác rõ ràng, MCP hoạt động tốt. Agent có thể đoán tool phù hợp, gọi tool và nhận kết quả.
Với sản phẩm như Apidog — nhiều module, hàng trăm thao tác, cấu trúc lồng nhau, workflow ẩn và ngữ nghĩa sản phẩm riêng — MCP đơn lẻ tạo ra một bức tường công cụ ngẫu nhiên.
Checklist nếu bạn đang thiết kế MCP Server
Nếu bạn đang xây MCP server cho sản phẩm của mình, hãy kiểm tra các điểm sau trước khi tạo thêm tool.
1. Đếm chi phí context trước khi đếm số tool
Đừng chỉ hỏi:
Chúng ta có thể expose bao nhiêu API?
Hãy hỏi:
Mỗi tool tốn bao nhiêu token mô tả?
Agent có cần đọc tất cả không?
Có thể tải context theo nhu cầu không?
2. Nhóm tool theo workflow, không chỉ theo endpoint
Thay vì chỉ expose:
createTestCase
updateTestCase
createScenario
runScenario
getReport
Hãy cân nhắc một abstraction gần với tác vụ hơn:
addApiTestAndRunVerification
Mục tiêu là giảm số quyết định Agent phải tự đưa ra.
3. Đưa quy tắc kỹ thuật vào hệ thống, không nhồi hết vào prompt
Nếu một workflow bắt buộc phải:
- Kiểm tra endpoint
- Tạo test case
- Nhập vào scenario
- Chạy test
- Đọc report
- Xác minh kết quả
Đừng chỉ viết quy trình đó vào description.
Hãy cân nhắc đóng gói nó thành một command hoặc workflow có thể thực thi.
4. Đo số lần gọi tool trong tác vụ thật
Một chỉ số thực dụng:
Một yêu cầu người dùng cần bao nhiêu tool calls để hoàn tất?
Nếu một yêu cầu đơn giản cần quá nhiều bước khám phá và gọi tool, vấn đề có thể không nằm ở model. Vấn đề có thể nằm ở thiết kế bề mặt tool.
Những gì chúng tôi đã học
| Bài học | Ý nghĩa |
|---|---|
| Nhiều tool ≠ hỗ trợ Agent tốt hơn | Số lượng tool là chi phí, không phải lợi ích |
| Mô tả tool cạnh tranh context | 500 token mỗi tool × 100 tool = gánh nặng 50.000 token |
| Giao thức phiên làm tăng chi phí thực thi | Mỗi call mang theo quản lý trạng thái giao thức |
| Tool nguyên tử yêu cầu kiến thức sản phẩm | Agent phải hiểu logic nội bộ để điều phối |
| Kết nối ≠ thực thi | MCP kết nối; CLI + SKILL thực thi |
Bước ngoặt
Nhận thức này khiến chúng tôi đặt câu hỏi khác:
Nếu MCP không phải câu trả lời đầy đủ cho việc hỗ trợ Agent, thì cái gì là?
Chúng tôi không phủ nhận giá trị của MCP. MCP cung cấp kết nối tiêu chuẩn hóa, và điều đó quan trọng với hệ sinh thái.
Nhưng với các tác vụ kỹ thuật phức tạp, chúng tôi cần một lớp có thể:
- Diễn tả workflow, không chỉ tool
- Hướng dẫn Agent qua các trình tự đúng
- Xác thực trước khi ghi
- Thực thi quality gates
- Hấp thụ độ phức tạp vào hệ thống thay vì đẩy hết vào model context
Câu trả lời chúng tôi đi đến là:
CLI + SKILL
Trong bài tiếp theo, Tại sao chúng tôi phát triển Apidog CLI hoàn toàn mới, chúng ta sẽ đi vào thay đổi kiến trúc: chuyển độ phức tạp từ context của model sang hệ thống kỹ thuật, và vì sao điều đó thay đổi cách hỗ trợ Agent.
Những điểm chính
- MCP trở thành câu trả lời phổ biến cho câu hỏi: "Agent kết nối với tool như thế nào?"
- Chúng tôi đã xây 126 MCP tool, ban đầu nghĩ rằng nhiều tool hơn đồng nghĩa hỗ trợ tốt hơn.
- Tác vụ thực tế bộc lộ bốn vấn đề: chi phí khám phá, xâm lấn context, chi phí phiên và ngữ nghĩa sản phẩm.
- Nguyên nhân gốc rễ: MCP kết nối tool, nhưng tác vụ phức tạp cần workflow có thể thực thi.
- Nhiều tool hơn có thể trở thành chi phí, đặc biệt khi mô tả tool tiêu tốn context của model.
- Với workflow kỹ thuật phức tạp, nên cân nhắc đóng gói quy trình vào CLI hoặc lớp thực thi thay vì chỉ expose endpoint nguyên tử.
Tải xuống Apidog để thiết kế, tạo mock, kiểm thử và viết tài liệu API trong một không gian làm việc. Tìm hiểu thêm về Apidog CLI để kiểm thử API dòng lệnh, tự động hóa CI và quy trình làm việc của AI Agent.
Top comments (0)