Hướng Dẫn Tạo MCP Server Cho AI Agent Kiểm Thử API Hiệu Quả

Tóm tắt

Xây dựng một máy chủ MCP bằng TypeScript để hiển thị ba công cụ: run_test, validate_schema và list_environments. Cấu hình nó trong ~/.claude/settings.json cho Claude Code hoặc .cursor/mcp.json cho Cursor. Các tác nhân AI của bạn sau đó có thể chạy các bài kiểm tra Apidog, xác thực lược đồ OpenAPI và tìm nạp môi trường mà không cần rời khỏi giao diện trò chuyện. Mã nguồn đầy đủ khoảng 150 dòng và sử dụng gói @modelcontextprotocol/sdk.

Xây dựng một máy chủ MCP cho phép Claude Code, Cursor và các tác nhân AI khác chạy các bài kiểm tra API Apidog, xác thực lược đồ và so sánh phản hồi, tất cả mà không cần rời khỏi giao diện trò chuyện của chúng.

💡

Bạn đang ở giữa một phiên viết mã. Tác nhân AI của bạn vừa hoàn thành việc xây dựng một điểm cuối API. Thay vì sao chép mã, mở Apidog, tạo một bộ sưu tập kiểm tra và chạy xác thực thủ công, bạn muốn gõ một lệnh và nhận lại kết quả.

nút

Đó là những gì Giao thức Ngữ cảnh Mô hình (MCP) cho phép. MCP cho phép các tác nhân AI truy cập các công cụ bên ngoài thông qua một giao diện chuẩn hóa. Xây dựng một máy chủ MCP cho Apidog, và tác nhân AI của bạn có thể chạy các bài kiểm tra, xác thực lược đồ và tìm nạp môi trường mà không cần chuyển đổi ngữ cảnh.

MCP là gì?

MCP (Model Context Protocol) là một giao thức để các tác nhân AI truy cập các công cụ và nguồn dữ liệu bên ngoài. Hãy nghĩ nó như một hệ thống plugin hoạt động trên Claude Code, Cursor và các máy khách tương thích MCP khác.

Một máy chủ MCP hiển thị các công cụ (các hàm mà tác nhân có thể gọi) và tài nguyên (dữ liệu mà tác nhân có thể đọc). Máy chủ MCP Apidog của bạn sẽ hiển thị các công cụ để kiểm thử API.

┌─────────────────┐         ┌──────────────────┐         ┌─────────────┐
│  AI Agent       │         │  MCP Server      │         │  Apidog     │
│  (Claude Code)  │◄───────►│  (Your Code)     │◄───────►│  API        │
└─────────────────┘   JSON  └──────────────────┘  HTTP   └─────────────┘

Bước 1: Thiết lập dự án

Tạo một dự án TypeScript mới:

mkdir apidog-mcp-server
cd apidog-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

Tạo tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Thêm một script xây dựng vào package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Bước 2: Tạo khung máy chủ MCP

Tạo src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "apidog",
  version: "1.0.0",
  description: "Apidog API testing tools for AI agents"
});

// Tools will be defined here

const transport = new StdioServerTransport();
await server.connect(transport);

Khung này tạo một máy chủ MCP và kết nối nó với truyền tải stdio. Truyền tải này xử lý giao tiếp giữa tác nhân AI và máy chủ của bạn thông qua đầu vào/đầu ra tiêu chuẩn.

Bước 3: Định nghĩa công cụ run_test

Thêm công cụ đầu tiên vào src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "apidog",
  version: "1.0.0",
  description: "Apidog API testing tools for AI agents"
});

// Tool: run_test
server.tool(
  "run_test",
  {
    projectId: z.string().describe("Apidog project ID (found in project URL)"),
    environmentId: z.string().optional().describe("Optional environment ID for test execution"),
    testSuiteId: z.string().optional().describe("Optional test suite ID to run specific suite")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Error: APIDOG_API_KEY environment variable not set"
        }]
      };
    }

    // Build API URL
    let url = `https://api.apidog.com/v1/projects/${projectId}/tests/run`;
    const params = new URLSearchParams();
    if (environmentId) params.append("environmentId", environmentId);
    if (testSuiteId) params.append("testSuiteId", testSuiteId);
    if (params.toString()) url += `?${params.toString()}`;

    try {
      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        }
      });

      if (!response.ok) {
        const error = await response.text();
        return {
          content: [{
            type: "text",
            text: `API Error: ${response.status} ${error}`
          }]
        };
      }

      const results = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(results, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Request failed: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Định nghĩa công cụ có ba phần:

Tên — run_test (các tác nhân chọn công cụ theo tên, vì vậy hãy đặt tên có tính mô tả)
Lược đồ — Xác thực Zod cho các tham số có mô tả
Trình xử lý — Hàm bất đồng bộ gọi API Apidog

Bước 4: Thêm công cụ validate_schema

Thêm xác thực lược đồ để bắt lỗi OpenAPI trước khi triển khai:

// Tool: validate_schema
server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("OpenAPI 3.x schema object to validate"),
    strict: z.boolean().optional().default(false).describe("Enable strict mode for additional checks")
  },
  async ({ schema, strict }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Error: APIDOG_API_KEY environment variable not set"
        }]
      };
    }

    try {
      const response = await fetch("https://api.apidog.com/v1/schemas/validate", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({ schema, strict })
      });

      const result = await response.json();

      if (!response.ok) {
        return {
          content: [{
            type: "text",
            text: `Validation failed: ${JSON.stringify(result.errors, null, 2)}`
          }]
        };
      }

      return {
        content: [{
          type: "text",
          text: result.valid
            ? "Schema is valid OpenAPI 3.x"
            : `Warnings: ${JSON.stringify(result.warnings, null, 2)}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Validation failed: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

Bước 5: Thêm công cụ list_environments

Thêm một công cụ để tìm nạp các môi trường kiểm tra có sẵn:

// Tool: list_environments
server.tool(
  "list_environments",
  {
    projectId: z.string().describe("Apidog project ID")
  },
  async ({ projectId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Error: APIDOG_API_KEY environment variable not set"
        }]
      };
    }

    try {
      const response = await fetch(
        `https://api.apidog.com/v1/projects/${projectId}/environments`,
        {
          headers: {
            "Authorization": `Bearer ${apiKey}`
          }
        }
      );

      if (!response.ok) {
        const error = await response.text();
        return {
          content: [{
            type: "text",
            text: `API Error: ${response.status} ${error}`
          }]
        };
      }

      const environments = await response.json();
      return {
        content: [{
          type: "text",
          text: environments.length === 0
            ? "No environments found for this project"
            : environments.map((e: any) =>
                `- ${e.name} (ID: ${e.id})${e.isDefault ? " [default]" : ""}`
              ).join("\n")
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Request failed: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

Bước 6: Xây dựng và kiểm tra

Xây dựng máy chủ:

npm run build

Kiểm tra với một máy khách MCP đơn giản. Tạo test-client.js:

import { spawn } from "child_process";

const server = spawn("node", ["dist/index.js"], {
  env: { ...process.env, APIDOG_API_KEY: "your-api-key" }
});

server.stdout.on("data", (data) => {
  console.log(`Server output: ${data}`);
});

server.stderr.on("data", (data) => {
  console.error(`Server error: ${data}`);
});

// Send a test message
const message = {
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: {
    protocolVersion: "2024-11-05",
    capabilities: {},
    clientInfo: { name: "test-client", version: "1.0.0" }
  }
};

server.stdin.write(JSON.stringify(message) + "\n");

Bước 7: Cấu hình cho Claude Code

Thêm máy chủ MCP vào cấu hình Claude Code của bạn:

Tạo hoặc chỉnh sửa ~/.claude/settings.json:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "your-api-key-here"
      }
    }
  }
}

Khởi động lại Claude Code. Các công cụ Apidog bây giờ sẽ xuất hiện khi bạn yêu cầu trợ giúp kiểm thử API.

Cách sử dụng trong Claude Code:

Use the run_test tool to run tests on my Apidog project.
Project ID: proj_12345
Environment: staging

Validate this OpenAPI schema against Apidog rules:
[paste schema]

List all environments for project proj_12345

Bước 8: Cấu hình cho Cursor

Cursor sử dụng cấu hình MCP tương tự. Tạo .cursor/mcp.json trong dự án của bạn:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cách sử dụng trong Cursor:

@apidog run_test projectId="proj_12345" environmentId="staging"

Mã nguồn hoàn chỉnh

Dưới đây là tệp src/index.ts hoàn chỉnh:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "apidog",
  version: "1.0.0",
  description: "Apidog API testing tools for AI agents"
});

// Tool: run_test
server.tool(
  "run_test",
  {
    projectId: z.string().describe("Apidog project ID"),
    environmentId: z.string().optional().describe("Environment ID"),
    testSuiteId: z.string().optional().describe("Test suite ID")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Error: APIDOG_API_KEY not set"
        }]
      };
    }

    let url = `https://api.apidog.com/v1/projects/${projectId}/tests/run`;
    const params = new URLSearchParams();
    if (environmentId) params.append("environmentId", environmentId);
    if (testSuiteId) params.append("testSuiteId", testSuiteId);
    if (params.toString()) url += `?${params.toString()}`;

    try {
      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        }
      });

      const results = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(results, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Request failed: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

// Tool: validate_schema
server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("OpenAPI schema"),
    strict: z.boolean().optional().default(false)
  },
  async ({ schema, strict }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Error: APIDOG_API_KEY not set"
        }]
      };
    }

    const response = await fetch("https://api.apidog.com/v1/schemas/validate", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ schema, strict })
    });

    const result = await response.json();
    return {
      content: [{
        type: "text",
        text: result.valid
          ? "Schema is valid"
          : `Issues: ${JSON.stringify(result.errors || result.warnings, null, 2)}`
      }]
    };
  }
);

// Tool: list_environments
server.tool(
  "list_environments",
  {
    projectId: z.string().describe("Apidog project ID")
  },
  async ({ projectId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Error: APIDOG_API_KEY not set"
        }]
      };
    }

    const response = await fetch(
      `https://api.apidog.com/v1/projects/${projectId}/environments`,
      {
        headers: { "Authorization": `Bearer ${apiKey}` }
      }
    );

    const environments = await response.json();
    return {
      content: [{
        type: "text",
        text: environments.map((e: any) =>
          `- ${e.name} (${e.id})${e.isDefault ? " [default]" : ""}`
        ).join("\n")
      }]
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Những gì bạn đã xây dựng

Thành phần	Mục đích
Máy chủ MCP	Kết nối các tác nhân AI với API Apidog
`run_test`	Thực thi các bộ sưu tập kiểm tra theo lập trình
`validate_schema`	Bắt lỗi OpenAPI trước khi triển khai
`list_environments`	Khám phá các môi trường kiểm tra có sẵn
Xác thực Zod	Xử lý tham số an toàn kiểu
Truyền tải Stdio	Hoạt động với Claude Code, Cursor, bất kỳ máy khách MCP nào

Các bước tiếp theo

Mở rộng máy chủ:

Thêm công cụ compare_responses để so sánh kết quả kiểm tra giữa các môi trường
Thêm get_test_history để tìm nạp lịch sử các lần chạy kiểm tra
Thêm trigger_mock_server để khởi động/dừng các điểm cuối giả lập

Lưu ý khi triển khai thực tế:

Thêm logic thử lại cho các yêu cầu mạng không ổn định
Triển khai giới hạn tốc độ để tránh bị điều tiết API
Thêm ghi nhật ký để gỡ lỗi các cuộc gọi công cụ thất bại
Lưu trữ khóa API trong một kho an toàn thay vì biến môi trường

Chia sẻ với nhóm của bạn:

Xuất bản lên npm dưới dạng @your-org/apidog-mcp-server
Tài liệu hóa các biến môi trường bắt buộc
Bao gồm các cấu hình MCP mẫu cho các máy khách phổ biến

Khắc phục sự cố thường gặp

Máy chủ MCP không tải trong Claude Code:

Xác minh đường dẫn trong ~/.claude/settings.json là tuyệt đối (không tương đối)
Kiểm tra xem node có trong PATH của bạn không: which node
Đảm bảo tệp dist/index.js đã được xây dựng tồn tại: ls -la dist/
Tìm kiếm lỗi trong nhật ký MCP của Claude Code

Các công cụ không xuất hiện sau khi cấu hình:

Khởi động lại hoàn toàn Claude Code (thoát và mở lại)
Chạy npm run build để đảm bảo TypeScript đã được biên dịch
Kiểm tra xem tất cả ba công cụ đã được định nghĩa trước server.connect() chưa
Xác minh máy chủ khởi động mà không có lỗi: node dist/index.js

Yêu cầu API thất bại với mã 401:

Xác nhận APIDOG_API_KEY đã được đặt trong cấu hình
Kiểm tra xem có khoảng trắng thừa hoặc dấu ngoặc kép xung quanh giá trị khóa không
Xác minh tài khoản Apidog của bạn đã bật quyền truy cập API
Kiểm tra khóa thủ công: curl -H "Authorization: Bearer $APIDOG_API_KEY" https://api.apidog.com/v1/user

Lỗi xác thực Zod:

Đảm bảo tên tham số khớp chính xác với lược đồ
Kiểm tra xem các trường bắt buộc đã được cung cấp chưa (không có lỗi chính tả trong projectId)
Xác minh các trường tùy chọn sử dụng .optional() trong lược đồ
Đọc thông báo lỗi đầy đủ — Zod sẽ cho bạn biết trường nào bị lỗi

Lỗi biên dịch TypeScript:

Chạy npm install để đảm bảo tất cả các phụ thuộc đã được cài đặt
Kiểm tra phiên bản TypeScript: npx tsc --version (nên là 5.x)
Xóa và xây dựng lại: rm -rf dist && npm run build
Tìm kiếm sự không khớp kiểu trong phản hồi fetch (thêm khẳng định kiểu as)

Kiểm tra máy chủ MCP của bạn cục bộ

Trước khi triển khai lên môi trường sản phẩm, hãy kiểm tra máy chủ của bạn cục bộ:

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

# Start the server
node dist/index.js

# In another terminal, send a test message
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

Đầu ra mong đợi:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      { "name": "run_test", "description": "...", "inputSchema": {...} },
      { "name": "validate_schema", "description": "...", "inputSchema": {...} },
      { "name": "list_environments", "description": "...", "inputSchema": {...} }
    ]
  }
}

Kiểm tra một cuộc gọi công cụ:

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_environments","arguments":{"projectId":"your-project-id"}}}' | node dist/index.js

Các tác nhân AI của bạn giờ đây có quyền truy cập trực tiếp vào các khả năng kiểm thử của Apidog. Không còn sao chép-dán giữa trò chuyện và trình duyệt. Không còn chạy kiểm thử thủ công. Gõ một lệnh, nhận lại kết quả.

Đó là sức mạnh của MCP: mở rộng các tác nhân AI của bạn với các công cụ chuyên biệt theo lĩnh vực, và để chúng làm những gì chúng phải làm — giúp bạn triển khai nhanh hơn.

Những điểm chính

Máy chủ MCP kết nối các tác nhân AI với API bên ngoài — Xây dựng một lần, sử dụng trên Claude Code, Cursor và bất kỳ máy khách tương thích MCP nào
Ba công cụ đáp ứng hầu hết các nhu cầu kiểm thử API — run_test để thực thi, validate_schema để xác thực OpenAPI, list_environments để khám phá
Xác thực Zod ngăn chặn các tham số không hợp lệ — Định nghĩa công cụ an toàn kiểu giúp bắt lỗi trước khi gọi API
Cấu hình là dành riêng cho công cụ — Claude Code sử dụng ~/.claude/settings.json, Cursor sử dụng .cursor/mcp.json
Triển khai thực tế yêu cầu xử lý lỗi — Thêm logic thử lại, giới hạn tốc độ và lưu trữ khóa an toàn trước khi triển khai

nút

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

MCP trong AI là gì?MCP (Model Context Protocol) là một giao thức chuẩn hóa cho phép các tác nhân AI truy cập các công cụ và nguồn dữ liệu bên ngoài. Hãy coi nó như một hệ thống plugin cho các tác nhân AI.

Làm cách nào để tạo một máy chủ MCP cho Apidog?Cài đặt @modelcontextprotocol/sdk, định nghĩa các công cụ với xác thực Zod, triển khai các trình xử lý gọi API Apidog và kết nối thông qua StdioServerTransport.

Tôi có thể sử dụng cái này với Cursor không?Có. Thêm cấu hình máy chủ MCP vào .cursor/mcp.json trong thư mục gốc dự án của bạn. Cùng một máy chủ hoạt động với Claude Code, Cursor và các máy khách MCP khác.

Tôi nên hiển thị những công cụ nào?Bắt đầu với run_test để thực thi các bộ sưu tập kiểm tra, validate_schema để xác thực OpenAPI và list_environments để tìm nạp các môi trường có sẵn.

Máy chủ MCP Apidog đã sẵn sàng cho môi trường sản phẩm chưa?Mã hướng dẫn này là một điểm khởi đầu. Thêm logic thử lại, giới hạn tốc độ, xử lý lỗi thích hợp và lưu trữ khóa API an toàn trước khi sử dụng trong môi trường sản phẩm.

Tôi có cần khóa API Apidog không?Có. Đặt APIDOG_API_KEY làm biến môi trường. Máy chủ sẽ đọc biến này khi chạy để xác thực các yêu cầu API.

Tôi có thể chia sẻ máy chủ MCP này với nhóm của mình không?Có. Xuất bản lên npm dưới dạng một gói riêng tư, tài liệu hóa các biến môi trường bắt buộc và bao gồm các cấu hình MCP mẫu.