Cara Membuat Server MCP untuk Memberi Agen AI Kemampuan Uji API

TL;DR

Buat server MCP dengan TypeScript yang mengekspos tiga alat: run_test, validate_schema, dan list_environments. Konfigurasikan di ~/.claude/settings.json untuk Claude Code atau .cursor/mcp.json untuk Cursor. Agen AI Anda kemudian dapat menjalankan pengujian Apidog, memvalidasi skema OpenAPI, dan mengambil lingkungan tanpa meninggalkan antarmuka obrolan. Kode sumber lengkapnya sekitar 150 baris dan menggunakan paket @modelcontextprotocol/sdk.

Buat server MCP yang memungkinkan Claude Code, Cursor, dan agen AI lainnya menjalankan pengujian API Apidog, memvalidasi skema, dan membandingkan respons, semuanya tanpa meninggalkan antarmuka obrolan mereka.

💡

Anda sedang dalam sesi pengkodean. Agen AI Anda baru saja selesai membangun sebuah endpoint API. Daripada menyalin kode, membuka Apidog, membuat koleksi pengujian, dan menjalankan validasi secara manual, Anda ingin mengetik satu perintah dan mendapatkan hasilnya.

tombol

Itulah yang dimungkinkan oleh Model Context Protocol (MCP). MCP memungkinkan agen AI mengakses alat eksternal melalui antarmuka standar. Bangun server MCP untuk Apidog, dan agen AI Anda dapat menjalankan pengujian, memvalidasi skema, dan mengambil lingkungan tanpa beralih konteks.

Apa itu MCP?

MCP (Model Context Protocol) adalah protokol bagi agen AI untuk mengakses alat dan sumber data eksternal. Anggap saja sebagai sistem plugin yang bekerja di Claude Code, Cursor, dan klien lain yang kompatibel dengan MCP.

Server MCP mengekspos alat (fungsi yang dapat dipanggil agen) dan sumber daya (data yang dapat dibaca agen). Server MCP Apidog Anda akan mengekspos alat untuk pengujian API.

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

Langkah 1: Siapkan Proyek

Buat proyek TypeScript baru:

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

Buat 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"]
}

Tambahkan skrip build ke package.json:

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

Langkah 2: Buat Kerangka Server MCP

Buat 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);

Kerangka ini membuat server MCP dan menghubungkannya ke transportasi stdio. Transportasi ini menangani komunikasi antara agen AI dan server Anda melalui input/output standar.

Langkah 3: Definisikan Alat run_test

Tambahkan alat pertama ke 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("ID proyek Apidog (ditemukan di URL proyek)"),
    environmentId: z.string().optional().describe("ID lingkungan opsional untuk eksekusi pengujian"),
    testSuiteId: z.string().optional().describe("ID test suite opsional untuk menjalankan suite tertentu")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Error: Variabel lingkungan APIDOG_API_KEY belum diatur"
        }]
      };
    }

    // 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: `Kesalahan API: ${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: `Permintaan gagal: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

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

Definisi alat memiliki tiga bagian:

Nama — run_test (agen memilih alat berdasarkan nama, jadi buatlah deskriptif)
Skema — Validasi Zod untuk parameter dengan deskripsi
Handler — Fungsi async yang memanggil API Apidog

Langkah 4: Tambahkan Alat validate_schema

Tambahkan validasi skema untuk menangkap kesalahan OpenAPI sebelum deployment:

// Tool: validate_schema
server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("Objek skema OpenAPI 3.x untuk divalidasi"),
    strict: z.boolean().optional().default(false).describe("Aktifkan mode ketat untuk pemeriksaan tambahan")
  },
  async ({ schema, strict }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Error: Variabel lingkungan APIDOG_API_KEY belum diatur"
        }]
      };
    }

    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: `Validasi gagal: ${JSON.stringify(result.errors, null, 2)}`
          }]
        };
      }

      return {
        content: [{
          type: "text",
          text: result.valid
            ? "Skema adalah OpenAPI 3.x yang valid"
            : `Peringatan: ${JSON.stringify(result.warnings, null, 2)}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Validasi gagal: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

Langkah 5: Tambahkan Alat list_environments

Tambahkan alat untuk mengambil lingkungan pengujian yang tersedia:

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

    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: `Kesalahan API: ${response.status} ${error}`
          }]
        };
      }

      const environments = await response.json();
      return {
        content: [{
          type: "text",
          text: environments.length === 0
            ? "Tidak ada lingkungan yang ditemukan untuk proyek ini"
            : environments.map((e: any) =>
                `- ${e.name} (ID: ${e.id})${e.isDefault ? " [default]" : ""}`
              ).join("\n")
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Permintaan gagal: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

Langkah 6: Build dan Uji

Build server:

npm run build

Uji dengan klien MCP sederhana. Buat test-client.js:

import { spawn } from "child_process";

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

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");

Langkah 7: Konfigurasi untuk Claude Code

Tambahkan server MCP ke konfigurasi Claude Code Anda:

Buat atau edit ~/.claude/settings.json:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "kunci-api-anda-di-sini"
      }
    }
  }
}

Mulai ulang Claude Code. Alat Apidog sekarang akan muncul saat Anda meminta bantuan pengujian API.

Penggunaan di Claude Code:

Gunakan alat run_test untuk menjalankan pengujian pada proyek Apidog saya.
ID Proyek: proj_12345
Lingkungan: staging

Validasi skema OpenAPI ini terhadap aturan Apidog:
[tempel skema]

Daftar semua lingkungan untuk proyek proj_12345

Langkah 8: Konfigurasi untuk Cursor

Cursor menggunakan konfigurasi MCP yang serupa. Buat .cursor/mcp.json di proyek Anda:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "kunci-api-anda-di-sini"
      }
    }
  }
}

Penggunaan di Cursor:

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

Kode Sumber Lengkap

Berikut adalah src/index.ts lengkap:

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("ID proyek Apidog"),
    environmentId: z.string().optional().describe("ID Lingkungan"),
    testSuiteId: z.string().optional().describe("ID test suite")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Error: APIDOG_API_KEY tidak diatur"
        }]
      };
    }

    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: `Permintaan gagal: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

// Tool: validate_schema
server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("Skema OpenAPI"),
    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 tidak diatur"
        }]
      };
    }

    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
          ? "Skema valid"
          : `Masalah: ${JSON.stringify(result.errors || result.warnings, null, 2)}`
      }]
    };
  }
);

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

    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);

Apa yang Anda Bangun

Komponen	Tujuan
Server MCP	Menjembatani agen AI ke API Apidog
`run_test`	Mengeksekusi koleksi pengujian secara terprogram
`validate_schema`	Menangkap kesalahan OpenAPI sebelum deployment
`list_environments`	Menemukan lingkungan pengujian yang tersedia
Validasi Zod	Penanganan parameter yang aman tipe
Transportasi Stdio	Bekerja dengan Claude Code, Cursor, klien MCP mana pun

Langkah Selanjutnya

Perluas server:

Tambahkan alat compare_responses untuk membedakan hasil pengujian di berbagai lingkungan
Tambahkan get_test_history untuk mengambil riwayat eksekusi pengujian
Tambahkan trigger_mock_server untuk memulai/menghentikan endpoint mock

Pertimbangan produksi:

Tambahkan logika coba ulang untuk permintaan jaringan yang tidak stabil
Terapkan pembatasan tingkat untuk menghindari throttling API
Tambahkan logging untuk debugging panggilan alat yang gagal
Simpan kunci API di vault yang aman alih-alih variabel lingkungan

Bagikan dengan tim Anda:

Publikasikan ke npm sebagai @your-org/apidog-mcp-server
Dokumentasikan variabel lingkungan yang diperlukan
Sertakan contoh konfigurasi MCP untuk klien umum

Memecahkan Masalah Umum

Server MCP tidak memuat di Claude Code:

Verifikasi bahwa jalur di ~/.claude/settings.json adalah absolut (bukan relatif)
Periksa apakah node ada di PATH Anda: which node
Pastikan dist/index.js yang dibuat ada: ls -la dist/
Cari kesalahan di log MCP Claude Code

Alat tidak muncul setelah konfigurasi:

Mulai ulang Claude Code sepenuhnya (keluar dan buka kembali)
Jalankan npm run build untuk memastikan TypeScript dikompilasi
Periksa apakah ketiga alat didefinisikan sebelum server.connect()
Verifikasi bahwa server dimulai tanpa kesalahan: node dist/index.js

Permintaan API gagal dengan 401:

Konfirmasi APIDOG_API_KEY diatur dalam konfigurasi
Periksa spasi atau tanda kutip tambahan di sekitar nilai kunci
Verifikasi akun Apidog Anda memiliki akses API yang diaktifkan
Uji kunci secara manual: curl -H "Authorization: Bearer $APIDOG_API_KEY" https://api.apidog.com/v1/user

Kesalahan validasi Zod:

Pastikan nama parameter cocok persis dengan skema
Periksa apakah bidang yang diperlukan disediakan (tidak ada salah ketik di projectId)
Verifikasi bidang opsional menggunakan .optional() di skema
Baca pesan kesalahan lengkap — Zod memberi tahu Anda bidang mana yang gagal

Kesalahan kompilasi TypeScript:

Jalankan npm install untuk memastikan semua dependensi terinstal
Periksa versi TypeScript: npx tsc --version (seharusnya 5.x)
Bersihkan dan build ulang: rm -rf dist && npm run build
Cari ketidakcocokan tipe dalam respons fetch (tambahkan pernyataan tipe as)

Menguji Server MCP Anda Secara Lokal

Sebelum menerapkan ke produksi, uji server Anda secara lokal:

Pengujian manual dengan stdio:

# Mulai server
node dist/index.js

# Di terminal lain, kirim pesan pengujian
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

Output yang diharapkan:

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

Uji panggilan alat:

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

Agen AI Anda sekarang memiliki akses langsung ke kemampuan pengujian Apidog. Tidak perlu lagi menyalin-menempel antara obrolan dan browser. Tidak perlu lagi menjalankan pengujian secara manual. Ketik perintah, dapatkan hasilnya kembali.

Itulah kekuatan MCP: perluas agen AI Anda dengan alat khusus domain, dan biarkan mereka melakukan apa yang seharusnya mereka lakukan — membantu Anda meluncurkan lebih cepat.

Poin Penting

Server MCP menjembatani agen AI ke API eksternal — Buat sekali, gunakan di Claude Code, Cursor, dan klien yang kompatibel dengan MCP lainnya
Tiga alat mencakup sebagian besar kebutuhan pengujian API — run_test untuk eksekusi, validate_schema untuk validasi OpenAPI, list_environments untuk penemuan
Validasi Zod mencegah parameter yang salah — Definisi alat yang aman tipe menangkap kesalahan sebelum panggilan API
Konfigurasi spesifik alat — Claude Code menggunakan ~/.claude/settings.json, Cursor menggunakan .cursor/mcp.json
Produksi membutuhkan penanganan kesalahan — Tambahkan logika coba ulang, pembatasan tingkat, dan penyimpanan kunci yang aman sebelum deployment

tombol

FAQ

Apa itu MCP dalam AI?MCP (Model Context Protocol) adalah protokol standar yang memungkinkan agen AI mengakses alat dan sumber data eksternal. Anggap saja sebagai sistem plugin untuk agen AI.

Bagaimana cara membuat server MCP untuk Apidog?Instal @modelcontextprotocol/sdk, definisikan alat dengan validasi Zod, implementasikan handler yang memanggil API Apidog, dan sambungkan melalui StdioServerTransport.

Bisakah saya menggunakan ini dengan Cursor?Ya. Tambahkan konfigurasi server MCP ke .cursor/mcp.json di root proyek Anda. Server yang sama bekerja dengan Claude Code, Cursor, dan klien MCP lainnya.

Alat apa yang harus saya ekspos?Mulai dengan run_test untuk menjalankan koleksi pengujian, validate_schema untuk validasi OpenAPI, dan list_environments untuk mengambil lingkungan yang tersedia.

Apakah server MCP Apidog siap produksi?Kode tutorial adalah titik awal. Tambahkan logika coba ulang, pembatasan tingkat, penanganan kesalahan yang tepat, dan penyimpanan kunci API yang aman sebelum digunakan dalam produksi.

Apakah saya memerlukan kunci API Apidog?Ya. Atur APIDOG_API_KEY sebagai variabel lingkungan. Server membaca ini saat runtime untuk mengautentikasi permintaan API.

Bisakah saya berbagi server MCP ini dengan tim saya?Ya. Publikasikan ke npm sebagai paket pribadi, dokumentasikan variabel lingkungan yang diperlukan, dan sertakan contoh konfigurasi MCP.