Panduan Pengujian Server MCP: Manual + Otomatis dengan Apidog

Post Show HN "Ableton Live MCP" telah mencapai 118 poin dan 78 komentar awal minggu ini. Pola ini sudah tidak asing lagi: seseorang menulis server Model Context Protocol untuk alat yang tidak terduga, komunitas Claude Desktop menyukainya, dan gelombang postingan "haruskah saya menulis satu untuk X?" pun bermunculan. MCP beralih dari eksperimen khusus Anthropic menjadi lapisan integrasi agen standar dalam waktu kurang dari setahun.

Pertumbuhan itu menyembunyikan celah dalam perkakas: belum ada yang menghadirkan cara yang rapi untuk menguji server MCP. Menjalankan JSON-RPC secara manual melalui stdio dengan debugger itu baik untuk hello-world; namun akan berantakan saat server Anda memiliki 12 alat, 3 perintah, dan API upstream yang tidak stabil. Panduan ini memberikan panduan praktis untuk menguji server MCP secara manual dan mengotomatiskan pengujian tersebut dengan Apidog, sehingga Anda dapat mengirimkan server MCP seperti Anda mengirimkan API lainnya: dengan kontrak, mock, dan suite regresi.

Jika Anda berasal dari konteks agen yang lebih umum, panduan agents.md kami sangat cocok dengan ini; konvensi di sana membuat kontrak server MCP lebih mudah dikomunikasikan kepada tim Anda.

button

TL;DR

MCP adalah Model Context Protocol dari Anthropic; ini adalah JSON-RPC 2.0 melalui stdio atau HTTP dan mengekspos tiga primitif: alat, sumber daya, dan perintah.
Menguji server MCP berarti memverifikasi respons initialize, tools/list, tools/call, resources/read, dan prompts/get terhadap sebuah kontrak.
Mulai secara manual: jalankan server dari baris perintah dengan stdio, konfirmasikan respons secara visual, dan perbaiki bug bentuk sebelum menambahkan klien.
Pindah ke otomatis: tangkap lalu lintas JSON-RPC di Apidog, ubah setiap panggilan menjadi permintaan yang disimpan, bangun asersi pada bentuk dan konten respons, dan jalankan suite di CI.
Gunakan server mock Apidog untuk mensimulasikan API upstream yang dipanggil oleh server MCP Anda, agar pengujian tetap deterministik.
Unduh Apidog untuk mendapatkan koleksi permintaan, server mock, dan CI runner di satu tempat.

Apa itu MCP sebenarnya, dalam dua menit

Spesifikasi Model Context Protocol mendefinisikan format wire JSON-RPC 2.0 dengan permukaan kecil. Klien (Claude Desktop, Cursor, agen Anda sendiri) memulai server MCP, melakukan jabat tangan initialize, dan kemudian mengeluarkan panggilan.

Lima panggilan yang akan Anda habiskan 90 persen waktu Anda untuk mengujinya:

initialize: negosiasi versi dan pengungkapan kapabilitas.
tools/list: server mengembalikan alat yang dieksposnya, termasuk JSON Schema untuk argumen.
tools/call: klien memanggil alat berdasarkan nama dengan argumen.
resources/list dan resources/read: server mengekspos konten yang dapat dibaca dan dialamatkan URI.
prompts/list dan prompts/get: server mengekspos template perintah yang dapat dirender klien.

Transportasi bisa berupa stdio (frame JSON-RPC yang dipisahkan baris baru pada stdin/stdout) atau HTTP yang dapat dialirkan (biasanya POST / dengan SSE untuk streaming). Sebagian besar server lokal menggunakan stdio; server jarak jauh menggunakan HTTP.

Mengapa pengujian penting: setiap pengguna Claude Desktop, setiap pengguna Cursor, setiap IDE yang menambahkan dukungan MCP akan memanggil server Anda. Bug dalam bentuk tools/list akan merusak setiap klien sekaligus. Biaya regresi itu tinggi.

Apa yang seharusnya Anda uji

Suite pengujian server MCP yang solid mencakup enam dimensi.

Kesesuaian protokol. Apakah initialize mengembalikan protocolVersion yang benar? Apakah server mengiklankan kapabilitas yang benar-benar didukungnya?

Kebenaran skema. Apakah setiap alat di tools/list memiliki JSON Schema yang valid untuk argumen? Apakah bidang yang wajib ditandai? Apakah deskripsinya lebih panjang dari tiga kata? Deskripsi kosong merusak pemilihan alat di Claude.

Perilaku alat. Untuk setiap alat, apakah tools/call mengembalikan blok konten dengan jenis yang benar (text, image, resource)? Apakah kasus kesalahan mengembalikan hasil isError: true daripada memicu kesalahan JSON-RPC?

Akses sumber daya. Apakah URI resources/list diselesaikan saat dipanggil melalui resources/read? Apakah paginasi berfungsi melewati halaman pertama?

Render perintah. Apakah perintah mengembalikan array messages yang terbentuk dengan baik? Apakah substitusi argumen ditempatkan di lokasi yang benar?

Mode kegagalan. Apa yang terjadi ketika API upstream mati? Ketika argumen alat hilang? Ketika klien waktu habis? Ini adalah bug yang muncul di produksi, bukan di hello-world.

Sisa panduan ini membahas setiap dimensi ini, dimulai secara manual, kemudian otomatis.

Pengujian manual dengan stdio

Mulai dengan pengaturan sesederhana mungkin: terminal, biner server Anda, dan inspektur MCP atau JSON-RPC mentah secara manual.

Jika Anda belum membuat server, buat satu dengan quickstart SDK MCP resmi di Python atau TypeScript. Contoh cuaca dua alat sudah cukup untuk diuji.

Jalankan server dalam mode inspektur:

npx @modelcontextprotocol/inspector node your-server.js

Inspektur mem-boot UI web lokal yang berbicara MCP ke server Anda dan menunjukkan setiap permintaan dan respons. Ini adalah cara tercepat untuk mengonfirmasi bahwa server dimulai, mengiklankan kapabilitas, dan merespons tools/list.

Setelah tampilan inspektur terlihat benar, jalankan alur yang sama dengan stdio mentah sehingga Anda dapat menangkap frame untuk Apidog:

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

Anda akan mendapatkan respons JSON-RPC pada stdout. Simpan permintaan dan responsnya. Ulangi untuk tools/list, tools/call, resources/list, dan sisanya. Pada akhir latihan ini, Anda memiliki 6 hingga 12 pasangan permintaan-respons kanonik yang mendefinisikan kontrak tingkat wire server Anda.

Dua hal yang perlu diperhatikan.

Pertama, blok konten. Hasil alat mengembalikan content: [{ type: "text", text: "..." }] atau content: [{ type: "image", data: "...", mimeType: "image/png" }]. Mencampur jenis dalam satu respons diperbolehkan; klien berbeda dalam cara mereka merender.

Kedua, kesalahan. Spesifikasi MCP jelas: kesalahan eksekusi alat mengembalikan hasil normal dengan isError: true dan blok konten yang menjelaskan kegagalan. Jangan memicu respons kesalahan JSON-RPC dari dalam alat; itu menandakan kegagalan tingkat protokol, bukan tingkat alat. Banyak klien memutuskan koneksi pada kesalahan protokol.

Dari manual ke otomatis: membangun suite pengujian di Apidog

Pengujian manual memunculkan bug yang jelas. Anda beralih ke otomatisasi ketika Anda mulai bertanya, "apakah perubahan terakhir saya merusak skema argumen alat 7?" dan tidak ingin mengetik 12 perintah curl untuk mencari tahu.

Pola: ambil setiap pasangan permintaan-respons yang Anda simpan selama pengujian manual, tempelkan ke Apidog sebagai permintaan yang disimpan, tambahkan asersi, dan jalankan suite pada setiap push.

1. Buat proyek Apidog untuk server MCP

Buka Apidog, buat proyek baru, atur URL dasar ke endpoint HTTP server MCP Anda (atau URL bridge stdio; lihat di bawah). Proyek Apidog mendukung REST dan JSON-RPC; buat lingkungan JSON-RPC.

Untuk server stdio yang tidak memiliki antarmuka HTTP, jalankan di belakang wrapper HTTP tipis untuk pengujian. Inspektur resmi menyediakannya; sebagai alternatif, skrip Node 30 baris yang membaca JSON-RPC melalui HTTP dan meneruskan ke stdio berfungsi dengan baik. Kami menggunakan pola yang sama dalam pengujian API tanpa Postman di tahun 2026 untuk backend non-HTTP.

2. Simpan permintaan kanonik

Untuk setiap initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, simpan body JSON-RPC sebagai permintaan. Apidog menyimpannya dengan body, header, dan status yang diharapkan.

Permintaan tools/call terlihat seperti ini di tampilan body permintaan Apidog:

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

3. Tambahkan asersi

Tujuan otomatisasi adalah menegaskan pada respons, bukan mengirim permintaan. Apidog mendukung asersi JSONPath secara native. Untuk tools/list Anda ingin setidaknya:

$.result.tools ada
$.result.tools.length lebih besar dari nol
Setiap alat memiliki name, description, dan inputSchema
Setiap inputSchema adalah JSON Schema yang valid

Untuk tools/call pada input yang diketahui baik, Anda ingin:

$.result.isError adalah false (atau tidak ada)
$.result.content adalah array
Blok konten pertama memiliki type dan konten yang diharapkan

Untuk tools/call pada input yang diketahui buruk (argumen wajib hilang), Anda ingin:

$.result.isError adalah true
$.result.content[0].text cocok dengan pesan kesalahan yang Anda harapkan

Apidog menyimpan asersi ini per permintaan. Kegagalan akan terlihat di laporan eksekusi.

4. Mock API upstream

Sebagian besar server MCP membungkus API eksternal: data cuaca, GitHub, Linear, database internal. Anda tidak ingin CI berjalan mengenai API langsung setiap commit. Ada dua alasan: biaya dan ketidakstabilan.

Server mock bawaan Apidog memperbaiki ini. Definisikan setiap endpoint upstream sebagai rute mock yang mengembalikan body JSON yang realistis. Arahkan konfigurasi server MCP Anda ke URL mock selama pengujian dan ke produksi selama eksekusi nyata. Kami membahas alur kerja mock secara rinci dalam pengembangan API contract-first.

Hasilnya: suite pengujian yang berjalan dalam hitungan detik, tidak memerlukan jaringan eksternal, dan menangkap regresi skema jauh sebelum dikirimkan.

5. Jalankan suite di CI

Proyek Apidog dapat diekspor ke CLI runner. Perintah apidog run mengambil ID proyek, menjalankan setiap permintaan yang disimpan, mengevaluasi asersi, dan keluar dengan non-nol pada kegagalan. Sambungkan ke GitHub Actions Anda atau penyedia CI apa pun yang sudah Anda gunakan.

Alur kerja minimal:

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 }}

Setiap push menjalankan seluruh kontrak MCP. Regresi skema alat 7 tidak dapat masuk tanpa terdeteksi.

Seperti apa cakupan pengujian yang baik itu

Rencana pengujian server MCP lengkap di Apidog biasanya meliputi:

1 permintaan initialize dengan asersi kapabilitas
1 permintaan tools/list dengan asersi bentuk dan JSON Schema
2 hingga 4 permintaan tools/call per alat: happy path, argumen hilang, tipe tidak valid, kesalahan upstream
1 resources/list ditambah 1 resources/read per famili sumber daya
1 prompts/list ditambah 1 prompts/get per template perintah

Untuk server 10-alat dengan 3 sumber daya dan 4 perintah, suite ini membutuhkan 50 hingga 70 permintaan. Apidog menjalankannya secara lokal dalam waktu kurang dari 10 detik dengan server mock yang hangat.

Kesalahan umum saat menguji server MCP

Ini adalah pola yang paling sering kita lihat.

Melewatkan putaran initialize. Beberapa server crash pada tools/list jika initialize tidak pernah dipanggil karena mereka membangun registri alat mereka secara malas di dalam jabat tangan. Selalu jalankan initialize terlebih dahulu.

Menegaskan pada string kesalahan mentah. Pesan kegagalan alat akan berubah. Tegaskan pada isError: true dan pada kode kesalahan stabil atau regex, bukan pada kecocokan string yang persis.

Membiarkan mock menyimpang dari produksi. Mock yang mengembalikan bentuk yang tidak pernah dikembalikan oleh API nyata memberikan Anda tes hijau pada integrasi yang rusak. Rekam ulang fixture mock dari respons nyata setiap rilis.

Melupakan streaming. Server MCP HTTP mengalirkan hasil alat melalui SSE. Test runner Anda harus menangani SSE; Apidog melakukannya, tetapi Anda harus mengaktifkan streaming pada permintaan.

Tidak menguji konkurensi. Klien MCP mengirim permintaan tools/call secara bersamaan dalam loop agen. Jika server Anda menyimpan state bersama tanpa kunci, tes permintaan tunggal lulus dan produksi rusak. Tambahkan tes parallel-run ke suite.

Membingungkan kesalahan protokol dengan kesalahan alat. Spesifikasi MCP memisahkannya dengan sengaja; mencampurkannya membuat Claude Desktop menutup koneksi. Kami membahas jenis bug kontrak yang sama dalam pengembangan platform API contract-first.

Kasus penggunaan dunia nyata

Sebuah tim yang membangun server MCP internal untuk API manajemen insiden perusahaan mereka menemukan tiga regresi dalam satu minggu menggunakan asersi Apidog pada bentuk tools/list. Tanpa pengujian, bug tersebut akan dikirimkan ke setiap insinyur yang menggunakan Claude Desktop secara bersamaan.

Seorang pengembang solo yang menerbitkan server MCP open-source untuk Notion menggunakan mock Apidog untuk menjalankan suite pengujian tanpa mencapai batas laju Notion selama CI. Suite mereka berjalan pada setiap PR, membutuhkan 8 detik, dan menyimpan cache fixture mock Apidog di repo sehingga kontributor tidak memerlukan akses API untuk mengembangkan.

Sebuah tim platform yang menjalankan 14 server MCP internal membangun ruang kerja Apidog bersama tempat kontrak setiap server berada. Server baru mewarisi suite pengujian dasar; peninjau dapat membandingkan perbedaan skema secara berdampingan sebelum menggabungkan. Tim melaporkan dua pemadaman yang dicegah pada kuartal pertama, keduanya ditangkap oleh asersi bentuk tools/list pada PR yang akan mengirimkan argumen yang diganti namanya ke setiap pengguna Claude Desktop di dalam perusahaan.

Tim kedua yang membangun server MCP untuk platform observabilitas internal menggunakan penukar lingkungan Apidog untuk menjalankan suite yang sama terhadap staging dan produksi. Setiap lingkungan menunjuk ke file fixture mock yang berbeda, sehingga 60 asersi yang sama mengonfirmasi kedua deployment tanpa menulis ulang satu permintaan pun.

Kesimpulan

MCP menjadi mainstream tahun ini, tetapi kisah pengujiannya masih seperti pengujian REST API satu dekade yang lalu: ad hoc, manual, rapuh. Anda tidak perlu menunggu ekosistem untuk menyusul. Perlakukan server MCP Anda sebagai API apa adanya, rancang kontrak, mock upstream, dan jalankan asersi di CI.

Lima poin penting:

Server MCP adalah API JSON-RPC; ujilah dengan ketelitian yang sama dengan API REST.
Mulai secara manual dengan inspektur resmi, lalu tangkap permintaan kanonik dan beralih ke otomatisasi.
Apidog menangani JSON-RPC, asersi, mock, dan CI dalam satu proyek.
Cakup enam dimensi: kesesuaian protokol, kebenaran skema, perilaku alat, akses sumber daya, render perintah, dan mode kegagalan.
Mock API upstream di Apidog agar suite pengujian tetap cepat dan deterministik.

Langkah selanjutnya: buka Apidog, buat proyek, tempelkan body permintaan yang Anda tangkap secara manual, tambahkan asersi JSONPath untuk tools/list, dan jalankan suite. Anda akan tahu dalam satu jam apakah kontrak server Anda cukup solid untuk dikirimkan.

FAQ

Apa itu MCP?

MCP, Model Context Protocol, adalah spesifikasi terbuka Anthropic untuk bagaimana klien AI (seperti Claude Desktop) memanggil alat, sumber daya, dan perintah eksternal. Ini adalah JSON-RPC 2.0 melalui stdio atau HTTP yang dapat dialirkan. Spesifikasi MCP lengkap diterbitkan di modelcontextprotocol.io.

Dapatkah saya menguji server MCP tanpa wrapper HTTP?

Ya. Inspektur MCP resmi berbicara stdio secara langsung dan memberi Anda UI untuk pengujian manual. Untuk pengujian otomatis di Apidog, bungkus stdio dalam server HTTP tipis selama CI; lalu lintas produksi masih melalui stdio.

Bagaimana cara melakukan mock API upstream yang dipanggil oleh server MCP saya?

Definisikan setiap endpoint upstream sebagai mock di proyek Apidog Anda, arahkan konfigurasi server MCP ke URL mock selama pengujian, dan beralih ke URL produksi saat runtime. Kami membahas pola yang sama dalam alat pengujian API untuk insinyur QA.

Bagaimana dengan streaming hasil alat?

Server MCP HTTP mengalirkan hasil alat melalui Server-Sent Events. Apidog mendukung SSE dalam permintaan yang disimpan; nyalakan di pengaturan permintaan dan tegaskan pada stream yang dirakit.

Haruskah saya menguji versi protokol?

Ya. Sematkan protocolVersion yang Anda dukung dalam initialize dan tegaskan terhadapnya. Ketidakcocokan menyebabkan ketidaksesuaian klien yang diam.

Dapatkah saya menguji server MCP saya terhadap Claude Desktop yang asli?

Anda bisa, dan Anda harus melakukannya setidaknya sekali sebelum setiap rilis. Tetapi jangan mengandalkan Claude Desktop sebagai loop pengujian Anda; itu lambat, manual, dan non-deterministik. Gunakan Apidog untuk suite regresi dan Claude Desktop untuk smoke test.

Di mana saya bisa melihat contoh server MCP yang nyata?

Repositori server MCP resmi memiliki implementasi referensi untuk filesystem, GitHub, Slack, Postgres, dan lusinan lainnya. Baca definisi alatnya; itu adalah cara termudah untuk memahami seperti apa bentuk MCP yang baik itu.