Blog

Hướng Dẫn Kiểm Thử Máy Chủ MCP: Thủ Công & Tự Động với Apidog

Ashley Innocent

Ashley Innocent

11 tháng 5 2026

Hướng Dẫn Kiểm Thử Máy Chủ MCP: Thủ Công & Tự Động với Apidog

Một bài đăng "Ableton Live MCP" trên Show HN đã đạt 118 điểm và 78 bình luận vào đầu tuần này. Mẫu hình này giờ đã quen thuộc: ai đó đã viết một máy chủ Giao thức Ngữ cảnh Mô hình (Model Context Protocol - MCP) cho một công cụ ít khả thi, cộng đồng Claude Desktop đã yêu thích nó, và một làn sóng các bài đăng "tôi có nên viết một cái cho X không?" đã nối tiếp. MCP đã đi từ một thử nghiệm chỉ dành cho Anthropic trở thành một lớp tích hợp tác nhân mặc định chỉ trong chưa đầy một năm.

Điều mà sự tăng trưởng đó che giấu là một lỗ hổng trong công cụ: chưa ai cung cấp một cách rõ ràng để kiểm thử máy chủ MCP. Việc chạy thủ công JSON-RPC qua stdio với trình gỡ lỗi thì ổn cho các ví dụ "hello-world"; nhưng nó sẽ sụp đổ ngay khi máy chủ của bạn có 12 công cụ, 3 lời nhắc, và một API thượng nguồn không ổn định. Hướng dẫn này cung cấp cho bạn một cẩm nang thực hành để kiểm thử máy chủ MCP một cách thủ công và tự động hóa các kiểm thử đó với Apidog, để bạn có thể phát hành máy chủ MCP theo cách bạn phát hành bất kỳ API nào khác: với một hợp đồng, một bản mô phỏng, và một bộ kiểm thử hồi quy.

Nếu bạn đến từ một ngữ cảnh tác nhân tổng quát hơn, hướng dẫn agents.md của chúng tôi rất phù hợp với điều này; các quy ước trong đó giúp hợp đồng máy chủ MCP dễ dàng truyền đạt hơn cho nhóm của bạn.

nút

TL;DR (Tóm tắt)

MCP thực sự là gì, trong hai phút

Đặc tả Giao thức Ngữ cảnh Mô hình định nghĩa một định dạng dây JSON-RPC 2.0 với một bề mặt nhỏ. Một máy khách (Claude Desktop, Cursor, tác nhân của riêng bạn) khởi động một máy chủ MCP, thực hiện bắt tay initialize, và sau đó đưa ra các cuộc gọi.

Năm cuộc gọi mà bạn sẽ dành 90 phần trăm thời gian của mình để kiểm thử:

Giao thức truyền tải có thể là stdio (các khung JSON-RPC được phân tách bằng dòng mới trên stdin/stdout) hoặc HTTP có thể truyền tải (thường là POST / với SSE để truyền tải). Hầu hết các máy chủ cục bộ sử dụng stdio; các máy chủ từ xa sử dụng HTTP.

Tại sao kiểm thử lại quan trọng: mọi người dùng Claude Desktop, mọi người dùng Cursor, mọi IDE hỗ trợ MCP đều sẽ gọi máy chủ của bạn. Lỗi trong hình dạng tools/list làm hỏng mọi máy khách cùng một lúc. Chi phí của một lỗi hồi quy là rất cao.

Những gì bạn nên kiểm thử

Một bộ kiểm thử máy chủ MCP vững chắc bao gồm sáu khía cạnh.

Phần còn lại của hướng dẫn này sẽ đi sâu vào từng điều này, bắt đầu với thủ công, sau đó là tự động hóa.

Kiểm thử thủ công với stdio

Bắt đầu với thiết lập đơn giản nhất có thể: một terminal, tệp thực thi máy chủ của bạn và trình kiểm tra MCP hoặc JSON-RPC thô bằng tay.

Nếu bạn chưa xây dựng máy chủ, hãy tạo một máy chủ với hướng dẫn khởi động nhanh SDK MCP chính thức bằng Python hoặc TypeScript. Ví dụ thời tiết hai công cụ là đủ để kiểm thử.

npx @modelcontextprotocol/inspector node your-server.js

Trình kiểm tra khởi động một giao diện người dùng web cục bộ giao tiếp MCP với máy chủ của bạn và hiển thị mọi yêu cầu và phản hồi. Đây là cách nhanh nhất để xác nhận máy chủ khởi động, quảng bá khả năng và phản hồi tools/list.

Khi giao diện trình kiểm tra trông đúng, hãy chạy luồng tương tự với stdio thô để bạn có thể chụp các khung cho Apidog:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js

Bạn sẽ nhận được phản hồi JSON-RPC trên stdout. Lưu yêu cầu và phản hồi. Lặp lại cho tools/list, tools/call, resources/list, và phần còn lại. Đến cuối bài tập này, bạn sẽ có từ 6 đến 12 cặp yêu cầu-phản hồi chuẩn xác định hợp đồng cấp dây của máy chủ của bạn.

Hai điều cần lưu ý.

Đầu tiên, các khối nội dung. Kết quả của công cụ trả về content: [{ type: "text", text: "..." }] hoặc content: [{ type: "image", data: "...", mimeType: "image/png" }]. Được phép trộn các loại trong một phản hồi; các máy khách khác nhau về cách chúng hiển thị.

Thứ hai, lỗi. Đặc tả MCP rõ ràng: lỗi thực thi công cụ trả về kết quả bình thường với isError: true và một khối nội dung mô tả lỗi. Không ném các phản hồi lỗi JSON-RPC từ bên trong một công cụ; điều đó báo hiệu một lỗi cấp giao thức, không phải cấp công cụ. Nhiều máy khách sẽ ngắt kết nối khi gặp lỗi giao thức.

Từ thủ công đến tự động: xây dựng bộ kiểm thử trong Apidog

Kiểm thử thủ công phát hiện các lỗi rõ ràng. Bạn chuyển sang tự động hóa khi bạn bắt đầu hỏi, “thay đổi gần đây của tôi có làm hỏng schema đối số của công cụ 7 không?” và không muốn gõ 12 lệnh curl để tìm hiểu.

Mô hình: lấy mọi cặp yêu cầu-phản hồi mà bạn đã lưu trong quá trình kiểm thử thủ công, dán nó vào Apidog dưới dạng một yêu cầu đã lưu, thêm các khẳng định và chạy bộ kiểm thử trên mỗi lần đẩy.

1. Tạo một dự án Apidog cho máy chủ MCP

Mở Apidog, tạo một dự án mới, đặt URL cơ sở thành điểm cuối HTTP của máy chủ MCP của bạn (hoặc URL cầu nối stdio; xem bên dưới). Các dự án Apidog hỗ trợ cả REST và JSON-RPC; hãy tạo một môi trường JSON-RPC.

Đối với các máy chủ stdio không có giao diện HTTP, hãy chạy chúng đằng sau một trình bao bọc HTTP mỏng để kiểm thử. Trình kiểm tra chính thức cung cấp một cái; ngoài ra, một tập lệnh Node 30 dòng đọc JSON-RPC qua HTTP và chuyển tiếp đến stdio cũng hoạt động tốt. Chúng tôi sử dụng cùng một mẫu trong kiểm thử API không cần Postman vào năm 2026 cho các backend không phải HTTP.

2. Lưu các yêu cầu chuẩn

Đối với mỗi initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, hãy lưu thân JSON-RPC dưới dạng một yêu cầu. Apidog lưu trữ chúng với thân, tiêu đề và trạng thái dự kiến.

Một yêu cầu tools/call trông như thế này trong chế độ xem thân yêu cầu của Apidog:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Tokyo"
    }
  }
}

3. Thêm các khẳng định

Mục đích của tự động hóa là khẳng định phản hồi, chứ không phải gửi yêu cầu. Apidog hỗ trợ các khẳng định JSONPath nguyên bản. Đối với tools/list, bạn muốn ít nhất:

Đối với tools/call trên một đầu vào tốt đã biết, bạn muốn:

Đối với tools/call trên một đầu vào xấu đã biết (thiếu đối số bắt buộc), bạn muốn:

Apidog lưu trữ các khẳng định này cho mỗi yêu cầu. Các lỗi sẽ hiển thị trong báo cáo chạy.

4. Mô phỏng các API thượng nguồn

Hầu hết các máy chủ MCP bao bọc một API bên ngoài: dữ liệu thời tiết, GitHub, Linear, một cơ sở dữ liệu nội bộ. Bạn không muốn các lần chạy CI truy cập các API trực tiếp mỗi khi commit. Có hai lý do: chi phí và sự không ổn định.

Máy chủ mô phỏng tích hợp sẵn của Apidog khắc phục điều này. Định nghĩa mỗi điểm cuối thượng nguồn dưới dạng một tuyến đường được mô phỏng trả về một thân JSON thực tế. Trỏ cấu hình máy chủ MCP của bạn đến URL mô phỏng trong quá trình kiểm thử và đến môi trường sản xuất trong các lần chạy thực tế. Chúng tôi trình bày chi tiết quy trình công việc mô phỏng trong phát triển API theo hợp đồng trước.

Kết quả: một bộ kiểm thử chạy trong vài giây, không yêu cầu mạng bên ngoài và phát hiện các lỗi hồi quy schema rất lâu trước khi chúng được phát hành.

5. Chạy bộ kiểm thử trong CI

Các dự án Apidog xuất ra các trình chạy CLI. Lệnh apidog run nhận một ID dự án, chạy mọi yêu cầu đã lưu, đánh giá các khẳng định và thoát với mã lỗi nếu thất bại. Hãy tích hợp nó vào GitHub Actions hoặc bất kỳ nhà cung cấp CI nào bạn đã sử dụng.

Một quy trình công việc tối thiểu:

name: MCP server tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - name: Start MCP HTTP wrapper
        run: node test/wrapper.js &
      - name: Run Apidog suite
        run: npx apidog run --project-id $APIDOG_PROJECT --env ci
        env:
          APIDOG_PROJECT: ${{ secrets.APIDOG_PROJECT }}
          APIDOG_TOKEN:   ${{ secrets.APIDOG_TOKEN }}

Mỗi lần đẩy chạy toàn bộ hợp đồng MCP. Lỗi hồi quy schema của công cụ 7 không thể vượt qua mà không bị phát hiện.

Phạm vi kiểm thử tốt trông như thế nào

Một kế hoạch kiểm thử máy chủ MCP hoàn chỉnh trong Apidog thường bao gồm:

Đối với một máy chủ 10 công cụ với 3 tài nguyên và 4 lời nhắc, bộ kiểm thử sẽ thực hiện từ 50 đến 70 yêu cầu. Apidog chạy điều đó cục bộ trong vòng dưới 10 giây với máy chủ mô phỏng đã khởi động.

Những sai lầm thường gặp khi kiểm thử máy chủ MCP

Đây là những mẫu chúng tôi thường thấy nhất.

Các trường hợp sử dụng trong thực tế

Một nhóm đang xây dựng máy chủ MCP nội bộ cho API quản lý sự cố của công ty họ đã phát hiện ba lỗi hồi quy trong một tuần bằng cách sử dụng các khẳng định Apidog trên hình dạng tools/list. Nếu không có kiểm thử đó, các lỗi đã được chuyển đến mọi kỹ sư sử dụng Claude Desktop cùng một lúc.

Một nhà phát triển độc lập xuất bản một máy chủ MCP mã nguồn mở cho Notion sử dụng các bản mô phỏng Apidog để chạy bộ kiểm thử mà không gặp phải giới hạn tốc độ của Notion trong quá trình CI. Bộ kiểm thử của họ chạy trên mọi PR, mất 8 giây và lưu trữ các fixture mô phỏng của Apidog trong kho lưu trữ để những người đóng góp không cần quyền truy cập API để phát triển.

Một nhóm nền tảng đang vận hành 14 máy chủ MCP nội bộ đã xây dựng một không gian làm việc Apidog chia sẻ nơi chứa hợp đồng của mọi máy chủ. Các máy chủ mới kế thừa một bộ kiểm thử cơ bản; người đánh giá có thể so sánh các khác biệt schema song song trước khi hợp nhất. Nhóm báo cáo đã ngăn chặn được hai sự cố trong quý đầu tiên, cả hai đều được phát hiện bởi các khẳng định hình dạng tools/list trên một PR đáng lẽ đã chuyển một đối số được đổi tên đến mọi người dùng Claude Desktop trong công ty.

Một nhóm thứ hai xây dựng máy chủ MCP cho một nền tảng quan sát nội bộ sử dụng bộ chuyển đổi môi trường của Apidog để chạy cùng một bộ kiểm thử đối với môi trường staging và production. Mỗi môi trường trỏ đến một tệp fixture mô phỏng khác nhau, vì vậy cùng 60 khẳng định xác nhận cả hai triển khai mà không cần viết lại một yêu cầu nào.

Kết luận

MCP đã trở nên phổ biến trong năm nay, nhưng câu chuyện kiểm thử vẫn còn ở giai đoạn kiểm thử API REST cách đây một thập kỷ: tùy tiện, thủ công, dễ vỡ. Bạn không cần phải chờ đợi hệ sinh thái bắt kịp. Hãy coi máy chủ MCP của bạn là một API thực sự, thiết kế một hợp đồng, mô phỏng các thượng nguồn và chạy các khẳng định trong CI.

Năm điểm chính:

Bước tiếp theo: mở Apidog, tạo một dự án, dán các thân yêu cầu bạn đã chụp thủ công, thêm các khẳng định JSONPath cho tools/list, và chạy bộ kiểm thử. Bạn sẽ biết trong vòng một giờ liệu hợp đồng máy chủ của bạn có đủ vững chắc để phát hành hay không.

Câu hỏi thường gặp (FAQ)

MCP là gì?

MCP, Giao thức Ngữ cảnh Mô hình (Model Context Protocol), là đặc tả mở của Anthropic về cách các máy khách AI (như Claude Desktop) gọi các công cụ, tài nguyên và lời nhắc bên ngoài. Nó là JSON-RPC 2.0 qua stdio hoặc HTTP có thể truyền tải. Đặc tả MCP đầy đủ được công bố trên modelcontextprotocol.io.

Tôi có thể kiểm thử một máy chủ MCP mà không cần trình bao bọc HTTP không?

Có. Trình kiểm tra MCP chính thức giao tiếp trực tiếp qua stdio và cung cấp cho bạn giao diện người dùng để kiểm thử thủ công. Để kiểm thử tự động trong Apidog, hãy bao bọc stdio trong một máy chủ HTTP mỏng trong quá trình CI; lưu lượng sản xuất vẫn đi qua stdio.

Làm cách nào để mô phỏng các API thượng nguồn mà máy chủ MCP của tôi gọi?

Định nghĩa mỗi điểm cuối thượng nguồn dưới dạng một bản mô phỏng trong dự án Apidog của bạn, trỏ cấu hình máy chủ MCP đến URL mô phỏng trong quá trình kiểm thử và chuyển sang các URL production trong thời gian chạy. Chúng tôi trình bày cùng một mẫu trong các công cụ kiểm thử API cho kỹ sư QA.

Còn kết quả công cụ truyền tải thì sao?

Các máy chủ MCP HTTP truyền tải kết quả công cụ qua Server-Sent Events. Apidog hỗ trợ SSE trong các yêu cầu đã lưu; hãy bật nó trong cài đặt yêu cầu và khẳng định trên luồng đã được tập hợp.

Tôi có nên kiểm thử phiên bản giao thức không?

Có. Ghim protocolVersion mà bạn hỗ trợ trong initialize và khẳng định chống lại nó. Sự không khớp gây ra sự không tương thích máy khách thầm lặng.

Tôi có thể kiểm thử máy chủ MCP của mình với Claude Desktop thực không?

Bạn có thể, và bạn nên làm ít nhất một lần trước mỗi lần phát hành. Nhưng đừng dựa vào Claude Desktop làm vòng lặp kiểm thử của bạn; nó chậm, thủ công và không mang tính xác định. Sử dụng Apidog cho bộ kiểm thử hồi quy và Claude Desktop cho kiểm thử khói.

Tôi có thể xem các ví dụ về máy chủ MCP thực ở đâu?

Kho lưu trữ máy chủ MCP chính thức có các triển khai tham chiếu cho hệ thống tệp, GitHub, Slack, Postgres và hàng tá cái khác. Đọc các định nghĩa công cụ; đó là cách dễ nhất để hiểu hình dạng MCP tốt trông như thế nào.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống
Hướng Dẫn Kiểm Thử Máy Chủ MCP: Thủ Công & Tự Động với Apidog