Đây là một loạt bài gồm 10 phần chia sẻ cách Apidog đã phát triển Apidog CLI, một công cụ dòng lệnh để kiểm thử API và quản lý vòng đời API. Hãy đọc theo thứ tự hoặc chuyển đến bất kỳ bài viết nào bạn quan tâm:
| 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 (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, các Agent IDE khác nhau và nhiều sản phẩm SaaS đã nhanh chóng làm theo. Giao thức này hứa hẹn một cách tiêu chuẩn hóa để AI Agents kết nối với các công cụ và nguồn dữ liệu bên ngoài.
Trong giai đoạn đó, gần như mọi sản phẩm có API đều được hỏi cùng một câu hỏi:
"Bạn có MCP không?"
Đối với Apidog, lựa chọn này dường như đặc biệt tự nhiên.
Tại sao MCP dường như là câu trả lời
Bản thân Apidog đã tích lũy được một bộ khả năng phát triển API toàn diện:
- Tài liệu API
- Định nghĩa Schema
- Máy chủ giả lập (Mock servers)
- Các trường hợp kiểm thử (Test cases)
- Các kịch bản kiểm thử (Test scenarios)
- Các bộ kiểm thử (Test suites)
- Báo cáo kiểm thử
- Quy trình làm việc nhập/xuất
- Cộng tác nhánh
- Và nhiều hơn nữa
Nếu Agents trở thành điểm truy cập phần mềm mới – một cách mới để người dùng tương tác với sản phẩm – thì việc phơi bày các khả năng này thông qua MCP dường như là một tấm vé cần thiết.
Chúng tôi tin rằng nếu chúng tôi có thể đóng gói các khả năng của mình dưới dạng công cụ MCP, Agent sẽ có thể:
- Truy vấn tài liệu API
- Tạo các trường hợp kiểm thử
- Chạy các kịch bản kiểm thử
- Nhập/xuất dữ liệu dự án
- Quản lý môi trường và biến
- Cộng tác giữa các nhánh
Logic rất đơn giản: càng nhiều khả năng được phơi bày = Agent càng được hỗ trợ tốt hơn.
Những gì chúng tôi thực sự đã xây dựng
Chúng tôi đã không xem nhẹ điều này.
Apidog MCP không phải là một bản demo đơn giản với một vài endpoint được viết thủ công. Đó là một MCP Server hoàn chỉnh:
Hệ thống phiên
Client MCP đầu tiên khởi tạo một phiên. Máy chủ tạo ra một sessionId và lưu trạng thái phiên thông qua Redis. Các yêu cầu tiếp theo tiếp tục truy cập bằng sessionId.
Nói cách khác, đó không phải là một cuộc gọi HTTP một lần, mà là một hệ thống phiên cấp giao thức.
Danh mục công cụ
Lớp công cụ cũng không được viết thủ công với một vài endpoint cố định. Chúng tôi đã chia các công cụ của Apidog thành nhiều danh mục:
| Danh mục | Mô tả | Ví dụ |
|---|---|---|
| Công cụ dự án gốc | Được xây dựng cho các hoạt động 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, trường hợp kiểm thử, kịch bản kiểm thử |
| Công cụ OpenAPI được tạo | Được tự động chuyển đổi từ định nghĩa OpenAPI | 126 công cụ với mã định danh duy nhất, đường dẫn, phương thức HTTP, Schema đầu vào |
Danh mục cuối cùng đó: 126 công cụ được tạo.
Mỗi công cụ được tạo đều có:
- Một mã định danh duy nhất
- Một đường dẫn API cụ thể
- Một phương thức HTTP (GET, POST, PUT, DELETE, v.v.)
- Một Schema đầu vào hoàn chỉnh với mô tả trường, loại và giá trị enum
- Một cấu trúc trả về được định nghĩa
Tiết lộ dần dần
Để giảm áp lực phơi bày công cụ, chúng tôi cũng đã xây dựng một lớp khám phá động:
Agent có thể:
- Đầu tiên tìm kiếm các công cụ endpoint có sẵn (
listOpenApiEndpoints) - Sau đó nhận các chi tiết OpenAPI của một công cụ cụ thể (
getOpenApiDetails) - Cuối cùng thực hiện cuộc gọi HTTP thực tế bằng id công cụ (
executeOpenApi)
Đây là nỗ lực của chúng tôi trong việc tiết lộ dần dần. Chúng tôi không đơn giản phơi bày tất cả các endpoint cơ bản một cách trực tiếp và rõ ràng. Chúng tôi hy vọng rằng Agent sẽ tìm kiếm trước, sau đó nhận chi tiết và cuối cùng thực hiện.
Bức tường công cụ ngẫu nhiên
Nhưng khi bước vào các tác vụ thực tế, vấn đề nhanh chóng nảy sinh.
Hãy xem xét một yêu cầu đơn giản của người dùng:
"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 độ triển khai, đây là một yêu cầu hợp lý. Apidog có khả năng:
- Tìm kiếm endpoint
- Tạo các trường hợp kiểm thử
- Chạy các kịch bản kiểm thử
- Tạo báo cáo
Nhưng từ góc độ của Agent, yêu cầu đơn giản này thực sự kích hoạt một loạt các phán đoán liên tục:
| Đ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ê các trường hợp kiểm thử hiện có? | Cả hai đều có vẻ hợp lệ |
| Tạo như thế nào? | Sử dụng createTestCase trực tiếp? Tìm nhóm trường hợp trước? |
Yêu cầu không rõ ràng |
| Cập nhật như thế nào? | Gọi công cụ update trực tiếp? Nhập các bước rồi đọc lại? |
Quy trình làm việc ẩn |
Agent không chỉ cần tìm đúng công cụ. Nó cần giải quyết vấn đề "sử dụng công cụ nào" trước, trước khi có thể bắt đầu giải quyết vấn đề của người dùng.
Từ góc độ triển khai, tất cả các vấn đề này đều có thể được giải quyết thông qua các công cụ. Từ góc độ trải nghiệm của Agent, chúng tạo thành một bức tường gồm các công cụ ngẫu nhiên.
Bốn vấn đề cấu trúc
Thông 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.
Vấn đề 1: Chi phí khám phá công cụ tăng nhanh chóng
Apidog không phải là một sản phẩm có thể được mô tả chỉ 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 |
| Các trường hợp kiểm thử | Liệt kê, lấy, tạo, cập nhật, xóa, sao chép |
| Các kịch bản kiểm thử | Liệt kê, lấy, tạo, cập nhật, xóa, nhập các bước, chạy |
| Các bộ kiểm thử | 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, tùy chọn |
| Các nhánh | Liệt kê, tạo, gộp, xóa |
Khi số lượng công cụ tăng từ một tá lên hàng chục hoặc hàng trăm, Agent cần giải quyết vấn đề "sử dụng công cụ nào" trước khi có thể bắt đầu giải quyết các vấn đề của người dùng.
Chúng tôi đã cố gắng viết các quy trình làm việc vào description của công cụ (trường được sử dụng để hiển thị công cụ cho AI Agents). Ví dụ, một mô tả công cụ sẽ nêu rõ:
"Trước khi truy vấn dữ liệu endpoint, bạn cần xác nhận dự án thông qua một công cụ khác trước, sau đó lấy siêu dữ liệu dự án thông qua một công cụ thứ ba, và cuối cùng gọi công cụ hiện tại."
Phương pháp này hoạt động trong các bộ công cụ quy mô nhỏ. Nhưng trong một bức tường công cụ khổng lồ, description tự nó cạnh tranh sự chú ý của model.
Càng nhiều hướng dẫn chúng tôi viết vào mô tả, càng nhiều token được tiêu thụ — và Agent càng ít có khả năng đọc và tuân theo chúng.
Vấn đề 2: Business Schema xâm lấn Context
Mỗi công cụ MCP không chỉ là một tên công cụ.
Đằng sau mỗi công cụ là:
description(công cụ làm gì)input schema(tham số, loại, bắt buộc/tùy chọn)- Giải thích trường (cấu trúc lồng ghép, ràng buộc)
- Giá trị enum (tùy chọn cho phép)
- Cấu trúc trả về (định dạng phản hồi, xử lý lỗi)
Hãy thực hiện một ước tính thận trọng:
| Yếu tố | Giá trị |
|---|---|
| Số lượng công cụ | 100+ |
| Số token trung bình cho mỗi công cụ | ~500 |
| Tổng số token mô tả công cụ | ~50.000 |
Một câu hỏi của người dùng có thể chỉ dài 50 ký tự. Nhưng model buộc phải giới thiệu trước 50.000 token mô tả công cụ — chỉ cho một MCP server.
Đây không phải là lý thuyết. Dữ liệu ngành đã chứng minh điều đó.
Bài đăng blog chính thức của Cursor "Dynamic Context Discovery" đã cung cấp dữ liệu tham chiếu có giá trị: bằng cách chuyển đổi mô tả công cụ MCP, các phiên terminal và các cuộc hội thoại dài thành ngữ cảnh có thể tải theo yêu 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 trực tiếp hơn: giới hạn số lượng công cụ MCP và độ dài mô tả công cụ đơn lẻ:
- Giới hạn trên số lượng công cụ: 40
- Giới hạn mô tả công cụ đơn lẻ: 8000 ký tự
Thực tế, trong quá trình kiểm thử nội bộ ban đầu, nhiều nhóm đã báo cáo rằng Apidog MCP gặp vấn đề với một số công cụ không thể được gọi trong Trae. Agent buộc phải thực hiện các đánh đổi do giới hạn ngữ cảnh của model, và các công cụ bên ngoài là những thứ đầu tiên bị "cắt bỏ."
Tất cả các giải pháp này đều chỉ ra cùng một sự thật:
Mô tả công cụ không thể đưa vào ngữ cảnh của model vô hạn.
Vấn đề 3: Các phiên giao thức làm cho chuỗi thực thi nặng nề hơn
Apidog MCP server cần xử lý:
| 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 vận chuyển | Quản lý kết nối |
| Chạm phiên | Cơ chế giữ sống |
| 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 | Các tùy chọn định dạng đầu ra |
Đối với một lệnh gọi công cụ đơn giản, những chi phí này là chấp nhận được. Đối với các tác vụ Agent với số lượng lớn lệnh gọi và thường xuyên khám phá, các yêu cầu quản lý trạng thái này làm tăng độ phức tạp ở cả phía máy chủ và máy khách.
Khi triển khai Apidog MCP, nhóm đã tiêu tốn đáng kể năng lượng để khắc phục sự cố và thích ứng với các Agent client khác nhau (Cursor, Claude Code, Antigravity, Trae, v.v.). Tuy nhiên, các vấn đề tương thích giao thức vẫn tồn tại, và giao thức MCP chính thức tiếp tục được vá với các phiên bản mới.
Tất cả các bên đều phải chịu đựng rất nhiều.
Vấn đề 4: Các công cụ nguyên tử không thể diễn tả tự nhiên ngữ nghĩa sản phẩm
Trong các kịch bản kiểm thử của Apidog, đó không chỉ là một biểu thức mảng steps đơn giản.
Một kịch bản kiểm thử bao gồm:
| Thành phần | Độ phức tạp |
|---|---|
| Nhập | Các bước từ endpoint hoặc các trường hợp hiện có |
| Đọc lại | Nhận cấu trúc đầy đủ sau khi nhập |
| Các trường hợp nội bộ | Các yêu cầu HTTP được nhúng trong các bước |
| Bộ tiền/hậu xử lý | Các tập lệnh trước/sau yêu cầu |
| Xác nhận | Các quy tắc xác thực phản hồi |
| Trích xuất biến | Thu thập giá trị từ phản hồi |
| Môi trường thời gian chạy | Lựa chọn môi trường, biến |
| Xác minh báo cáo | Kiểm tra kết quả kiểm thử |
Sau khi chia những thứ này thành nhiều công cụ MCP, Agent vẫn phải tự thực hiện công việc điều phối kiểm thử.
Các công cụ càng nguyên tử, model càng cần hiểu ngữ nghĩa nội bộ của sản phẩm:
- Tại sao việc nhập cần đọc lại?
- Tại sao các trường hợp nội bộ có các dấu cập nhật khác nhau?
- Tại sao các xác nhận yêu cầu các bộ so sánh cụ thể?
- Tại sao việc trích xuất biến có các ràng buộc về loại?
Điều này rõ ràng nằm ngoài khả năng của model.
Nó buộc nhóm Apidog phải chủ động thực hiện các điều chỉnh kỹ thuật để phù hợp với ngữ nghĩa sản phẩm nội bộ. Các endpoint nguyên tử đã bị động thêm một lớp chuyển đổi, chỉ để thích ứng với một lớp điều phối công cụ MCP duy nhất.
Những thách thức kỹ thuật và chi phí bảo trì sau đó chắc chắn là rất khó khăn.
Nguyên nhân gốc rễ
Nguyên nhân gốc rễ của bốn vấn đề này là một:
MCP tốt hơn trong việc kết nối các công cụ, nhưng các tác vụ R&D phức tạp cần nhiều hơn là kết nối công cụ — chúng cần các quy trình kỹ thuật có thể thực thi được.
| Đ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 thể diễn tả quy trình làm việc |
| Giao thức thống nhất | Không thể hướng dẫn trình tự |
| Phơi bày công cụ | Không thể thực thi xác thực |
| Khám phá động | Không thể cung cấp phán đoán |
Đối với các sản phẩm đơn giản với một tá hoạt động được định nghĩa rõ ràng, MCP hoạt động tốt. Agent có thể hợp lý đoán đúng công cụ, gọi nó và nhận được kết quả.
Đối với các sản phẩm như Apidog — với hàng chục module, hàng trăm hoạt động, cấu trúc lồng ghép, quy trình làm việc ẩn và ngữ nghĩa đặc trưng của sản phẩm — chỉ MCP tạo ra một bức tường công cụ ngẫu nhiên mà Agent gặp khó khăn khi điều hướng.
Những gì chúng tôi đã học
| Bài học | Ý nghĩa |
|---|---|
| Nhiều công cụ ≠ hỗ trợ Agent tốt hơn | Số lượng công cụ là chi phí, không phải lợi ích |
| Mô tả công cụ cạnh tranh bối cảnh | 500 token mỗi công cụ × 100 công cụ = gánh nặng 50.000 token |
| Các giao thức phiên làm tăng chi phí thực thi | Mỗi cuộc gọi mang theo quản lý trạng thái giao thức |
| Các công cụ nguyên tử yêu cầu kiến thức sản phẩm | Agent phải hiểu 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 ra một câu hỏi khác:
Nếu MCP không phải là câu trả lời cho việc hỗ trợ Agent, thì cái gì là?
Chúng tôi không từ bỏ giá trị của MCP — nó cung cấp các kết nối tiêu chuẩn hóa, điều này quan trọng đối với hệ sinh thái. Nhưng chúng tôi cần một thứ có thể:
- Diễn tả các quy trình làm việc, không chỉ các công cụ
- Hướng dẫn Agent qua các trình tự
- Xác thực trước khi ghi
- Thực thi các cổng chất lượng kỹ thuật
- Hấp thụ sự phức tạp vào hệ thống
Câu trả lời mà chúng tôi đã đạt được: CLI + SKILL.
Trong bài viết 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ẽ khám phá sự thay đổi kiến trúc — nơi sự phức tạp chuyển từ ngữ cảnh model sang hệ thống kỹ thuật, và tại sao điều đó thay đổi mọi thứ đối với việc hỗ trợ Agent.
Những điểm chính
- MCP trở thành câu trả lời của ngành cho "làm thế nào Agent kết nối với các công cụ"
- Chúng tôi đã xây dựng 126 công cụ MCP, nghĩ rằng nhiều công cụ hơn = hỗ trợ tốt hơn
- Các tác vụ thực tế đã bộc lộ bốn vấn đề cấu trúc: chi phí khám phá, xâm lấn ngữ cảnh, chi phí phiên, ngữ nghĩa sản phẩm
- Nguyên nhân gốc rễ: MCP kết nối các công cụ, nhưng các tác vụ phức tạp cần các quy trình có thể thực thi được
- Nhiều công cụ hơn là một chi phí, không phải lợi ích, khi mô tả công cụ tiêu tốn ngữ cảnh
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.