Panduan Pengujian Server MCP: Manual + Otomatis dengan Apidog

Post Show HN "Ableton Live MCP" mencapai 118 poin dan 78 komentar awal minggu ini. Polanya familiar: seseorang menulis server Model Context Protocol untuk alat yang tidak terduga, komunitas Claude Desktop menyukainya, lalu muncul banyak pertanyaan "haruskah saya menulis satu untuk X?". Dalam waktu kurang dari setahun, MCP bergerak dari eksperimen khusus Anthropic menjadi lapisan integrasi agen yang makin standar.

Coba Apidog hari ini

Masalahnya: tooling untuk menguji server MCP masih belum rapi. Menjalankan JSON-RPC manual lewat stdio cukup untuk hello-world, tetapi cepat berantakan ketika server punya 12 tool, 3 prompt, dan API upstream yang tidak stabil. Panduan ini menunjukkan cara menguji server MCP secara manual, lalu mengotomatiskannya dengan Apidog, sehingga server MCP bisa dikirim seperti API lain: dengan kontrak, mock, dan regression suite.

Jika Anda bekerja di konteks agen yang lebih umum, panduan agents.md juga relevan. Konvensi di sana membantu tim mendokumentasikan kontrak server MCP dengan lebih jelas.

TL;DR

• MCP adalah Model Context Protocol dari Anthropic: JSON-RPC 2.0 melalui stdio atau HTTP.
• MCP mengekspos tiga primitif utama: tools, resources, dan prompts.
• Pengujian server MCP berarti memverifikasi respons initialize, tools/list, tools/call, resources/read, dan prompts/get terhadap kontrak.
• Mulai dari manual: jalankan server via stdio, cek respons JSON-RPC, lalu simpan request/response kanonik.
• Lanjutkan ke otomatisasi: simpan request di Apidog, tambahkan assertion, mock API upstream, dan jalankan suite di CI.
• Gunakan mock server Apidog agar pengujian tetap deterministik.
• Unduh Apidog jika Anda ingin request collection, mock server, dan CI runner dalam satu workflow.

Apa itu MCP dalam dua menit

Spesifikasi Model Context Protocol mendefinisikan protokol JSON-RPC 2.0 dengan permukaan kecil. Klien seperti Claude Desktop, Cursor, atau agen Anda sendiri memulai server MCP, melakukan handshake initialize, lalu memanggil method MCP.

Method yang paling sering perlu diuji:

• initialize: negosiasi versi protokol dan kapabilitas.
• tools/list: daftar tool yang diekspos server, termasuk JSON Schema argumen.
• tools/call: pemanggilan tool berdasarkan nama dan argumen.
• resources/list dan resources/read: akses konten berbasis URI.
• prompts/list dan prompts/get: daftar dan render template prompt.

Transport bisa berupa:

• stdio: frame JSON-RPC dipisahkan newline melalui stdin/stdout.
• HTTP streaming: biasanya POST /, sering dengan SSE untuk streaming.

Sebagian besar server lokal memakai stdio. Server remote biasanya memakai HTTP.

Kenapa pengujian penting? Karena bug pada bentuk respons tools/list bisa merusak semua klien sekaligus. Setiap Claude Desktop, Cursor, IDE, atau agen yang memakai server Anda akan membaca kontrak yang sama.

Apa yang perlu diuji

Suite pengujian server MCP yang berguna sebaiknya mencakup enam area.

1. Kesesuaian protokol

Pastikan initialize mengembalikan:

• protocolVersion yang benar
• capabilities yang sesuai dengan fitur yang benar-benar didukung server

Contoh assertion:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2026-04-01",
    "capabilities": {}
  }
}

Yang perlu dicek pada respons:

• $.result.protocolVersion ada
• $.result.capabilities ada
• tidak ada error JSON-RPC untuk handshake valid

2. Kebenaran schema

Pada tools/list, pastikan setiap tool punya:

• name
• description
• inputSchema

Deskripsi kosong atau terlalu pendek bisa menurunkan kualitas pemilihan tool oleh klien AI. JSON Schema yang salah juga membuat klien gagal membangun form argumen.

3. Perilaku tool

Untuk setiap tools/call, cek:

• response berisi content
• setiap block punya type
• type yang digunakan valid, misalnya text, image, atau resource
• error bisnis dikembalikan dengan isError: true, bukan error protokol JSON-RPC

Contoh respons tool yang sehat:

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Weather in Tokyo: 22°C, cloudy"
      }
    ]
  }
}

Contoh error tingkat tool:

{
  "jsonrpc": "2.0",
  "id": 43,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Missing required argument: city"
      }
    ]
  }
}

4. Akses resource

Untuk resource, uji alur lengkap:

1. panggil resources/list
2. ambil salah satu URI
3. panggil resources/read
4. cek konten yang dikembalikan

Jika server mendukung pagination, uji halaman setelah halaman pertama.

5. Render prompt

Untuk prompt, uji:

• prompts/list mengembalikan daftar template
• prompts/get mengembalikan array messages
• substitusi argumen masuk ke lokasi yang benar

6. Mode kegagalan

Uji kondisi yang biasanya muncul di produksi:

• API upstream mati
• argumen wajib hilang
• tipe argumen salah
• timeout
• rate limit
• respons upstream berubah bentuk

Pengujian manual dengan stdio

Mulai dari setup paling kecil: terminal, server MCP, dan inspector.

Jika belum punya server, buat satu dari quickstart SDK MCP resmi di Python atau TypeScript. Contoh weather server dengan dua tool sudah cukup untuk latihan.

Jalankan server dengan inspector:

npx @modelcontextprotocol/inspector node your-server.js

Inspector akan membuka UI web lokal yang berbicara MCP ke server Anda. Gunakan untuk memverifikasi:

• server berhasil start
• initialize sukses
• capability benar
• tools/list menampilkan tool yang diharapkan
• tools/call mengembalikan konten valid

Setelah itu, jalankan request mentah via stdio agar Anda bisa menyimpan frame JSON-RPC untuk otomatisasi di Apidog:

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

Simpan request dan response. Ulangi untuk:

• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Pada akhir langkah ini, Anda akan punya 6–12 pasangan request/response kanonik yang mendefinisikan kontrak wire-level server MCP Anda.

Perhatikan bentuk content block

Hasil tool biasanya berbentuk:

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

Atau untuk gambar:

{
  "content": [
    {
      "type": "image",
      "data": "...",
      "mimeType": "image/png"
    }
  ]
}

Mencampur beberapa jenis content dalam satu respons diperbolehkan, tetapi klien bisa berbeda dalam cara render-nya.

Pisahkan error tool dan error protokol

Untuk kegagalan eksekusi tool, gunakan hasil normal dengan isError: true.

Jangan memicu error JSON-RPC dari dalam tool kecuali memang terjadi kegagalan protokol. Banyak klien akan memperlakukan error JSON-RPC sebagai masalah koneksi atau protokol, bukan error bisnis.

Dari manual ke otomatis: membangun test suite di Apidog

Pengujian manual bagus untuk menemukan bug awal. Tetapi begitu server punya banyak tool, Anda butuh regression suite.

Polanya:

1. ambil request/response kanonik dari pengujian manual
2. simpan setiap request di Apidog
3. tambahkan assertion
4. mock API upstream
5. jalankan suite di CI

1. Buat proyek Apidog untuk server MCP

Buka Apidog, buat proyek baru, lalu atur base URL ke endpoint HTTP server MCP Anda.

Jika server MCP Anda hanya mendukung stdio, jalankan wrapper HTTP tipis untuk testing. Inspector resmi bisa membantu untuk kebutuhan manual. Alternatifnya, buat script Node kecil yang menerima JSON-RPC via HTTP lalu meneruskannya ke proses stdio.

Pola yang sama juga dipakai dalam pengujian API tanpa Postman di tahun 2026 untuk backend non-HTTP.

2. Simpan request kanonik

Simpan satu request untuk setiap method penting:

• initialize
• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Contoh body tools/call:

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

Buat beberapa variasi request untuk setiap tool:

• happy path
• argumen wajib hilang
• tipe argumen salah
• upstream error

3. Tambahkan assertion

Otomatisasi berguna jika Anda menegaskan bentuk dan isi respons, bukan sekadar mengirim request.

Untuk tools/list, minimal cek:

• $.result.tools ada
• $.result.tools.length lebih besar dari nol
• setiap tool punya name
• setiap tool punya description
• setiap tool punya inputSchema
• setiap inputSchema valid sebagai JSON Schema

Untuk tools/call dengan input valid, cek:

• $.result.isError bernilai false atau tidak ada
• $.result.content adalah array
• $.result.content[0].type ada
• konten sesuai ekspektasi

Untuk tools/call dengan input invalid, cek:

• $.result.isError bernilai true
• $.result.content[0].text cocok dengan pola error yang stabil

Hindari assertion yang terlalu rapuh, misalnya mencocokkan seluruh string error secara persis. Gunakan regex atau kode error stabil jika tersedia.

4. Mock API upstream

Banyak server MCP membungkus API eksternal:

• weather API
• GitHub
• Linear
• Notion
• database internal
• layanan observability

CI sebaiknya tidak memanggil API live di setiap commit. Alasannya:

• lambat
• rentan rate limit
• hasil bisa berubah
• butuh credential eksternal
• bisa membuat test flaky

Gunakan mock server bawaan Apidog:

1. definisikan endpoint upstream sebagai mock route
2. isi respons JSON realistis
3. arahkan konfigurasi server MCP ke URL mock saat testing
4. gunakan URL produksi saat runtime nyata

Workflow mock ini juga dibahas dalam pengembangan API contract-first.

Hasilnya: test suite berjalan cepat, deterministik, dan tidak bergantung pada jaringan eksternal.

5. Jalankan suite di CI

Ekspor proyek Apidog ke CLI runner. Perintah apidog run menjalankan request yang tersimpan, mengevaluasi assertion, lalu keluar dengan status non-zero jika ada kegagalan.

Contoh GitHub Actions:

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

Dengan ini, setiap push menjalankan kontrak MCP. Jika schema tool berubah tanpa sengaja, CI akan gagal sebelum perubahan masuk ke main branch.

Contoh cakupan test yang sehat

Untuk server MCP di Apidog, rencana pengujian biasanya berisi:

• 1 request initialize dengan assertion capability
• 1 request tools/list dengan assertion bentuk dan JSON Schema
• 2–4 request tools/call per tool:
  • happy path
  • argumen hilang
  • tipe tidak valid
  • upstream error
• 1 request resources/list
• 1 request resources/read per famili resource
• 1 request prompts/list
• 1 request prompts/get per template prompt

Untuk server dengan 10 tool, 3 resource, dan 4 prompt, suite bisa berisi 50–70 request. Dengan mock server yang siap, suite seperti ini biasanya cukup cepat untuk dijalankan di CI.

Kesalahan umum saat menguji server MCP

Melewatkan initialize

Beberapa server membangun registry tool saat handshake. Jika Anda langsung memanggil tools/list, server bisa crash atau mengembalikan respons tidak lengkap.

Selalu jalankan initialize terlebih dahulu.

Assertion terlalu kaku pada string error

Pesan error bisa berubah. Lebih aman cek:

• isError: true
• kode error stabil jika ada
• regex pada bagian pesan yang penting

Mock menyimpang dari produksi

Mock yang tidak mirip respons asli memberi rasa aman palsu. Rekam ulang fixture mock dari respons nyata secara berkala, terutama sebelum rilis besar.

Tidak menguji streaming

Server MCP HTTP dapat mengalirkan hasil tool melalui SSE. Jika server Anda mendukung streaming, aktifkan mode streaming pada request test dan assert hasil stream yang sudah dirakit.

Tidak menguji concurrency

Klien MCP bisa mengirim beberapa tools/call secara paralel. Jika server menyimpan shared state tanpa kontrol, single-request test bisa lulus sementara produksi gagal.

Tambahkan parallel run test untuk tool yang menyentuh state bersama.

Mencampur error protokol dan error tool

Gunakan error JSON-RPC untuk masalah protokol. Gunakan isError: true untuk kegagalan eksekusi tool. Pemisahan ini penting agar klien seperti Claude Desktop tidak menutup koneksi karena mengira protokol rusak.

Jenis bug kontrak serupa juga dibahas dalam pengembangan platform API contract-first.

Kasus penggunaan dunia nyata

Sebuah tim yang membangun server MCP internal untuk API manajemen insiden menemukan tiga regresi dalam satu minggu dengan assertion Apidog pada bentuk tools/list. Tanpa pengujian kontrak, bug tersebut akan terkirim ke semua engineer yang memakai Claude Desktop.

Seorang pengembang solo yang menerbitkan server MCP open-source untuk Notion memakai mock Apidog agar CI tidak menyentuh rate limit Notion. Suite berjalan di setiap PR, memakan waktu sekitar beberapa detik, dan fixture mock disimpan di repo sehingga kontributor tidak memerlukan akses API.

Sebuah tim platform yang menjalankan 14 server MCP internal membuat workspace Apidog bersama untuk kontrak tiap server. Server baru mewarisi test suite dasar. Reviewer bisa membandingkan perubahan schema sebelum merge. Dua potensi outage tertangkap dari assertion tools/list pada PR yang mengganti nama argumen tool.

Tim lain yang membangun server MCP untuk platform observability internal memakai environment switcher Apidog untuk menjalankan suite yang sama terhadap staging dan production. Environment berbeda menunjuk ke fixture mock berbeda, sementara request dan assertion tetap sama.

Checklist implementasi

Gunakan checklist ini saat menyiapkan pengujian MCP:

• [ ] Jalankan server dengan inspector resmi.
• [ ] Verifikasi initialize.
• [ ] Verifikasi tools/list.
• [ ] Simpan request/response JSON-RPC kanonik.
• [ ] Buat proyek di Apidog.
• [ ] Simpan request initialize, tools/list, tools/call, resources/read, dan prompts/get.
• [ ] Tambahkan assertion JSONPath.
• [ ] Tambahkan test untuk argumen invalid.
• [ ] Mock API upstream.
• [ ] Jalankan suite di CI.
• [ ] Jalankan smoke test manual di Claude Desktop sebelum rilis.

Kesimpulan

MCP makin mainstream, tetapi praktik pengujiannya masih sering ad hoc dan manual. Cara paling praktis adalah memperlakukan server MCP sebagai API JSON-RPC biasa: definisikan kontrak, simpan request kanonik, mock dependency, dan jalankan assertion di CI.

Poin penting:

• Server MCP adalah API JSON-RPC; uji dengan disiplin yang sama seperti REST API.
• Mulai dari inspector resmi, lalu simpan request kanonik.
• Apidog dapat dipakai untuk JSON-RPC request, assertion, mock, dan CI.
• Cakup enam area: protokol, schema, tool behavior, resource, prompt, dan failure mode.
• Mock API upstream di Apidog agar suite cepat dan deterministik.

Langkah berikutnya: buka Apidog, buat proyek, tempelkan body request MCP yang Anda tangkap secara manual, tambahkan assertion untuk tools/list, lalu jalankan suite. Dalam waktu singkat, Anda akan tahu apakah kontrak server MCP Anda cukup stabil untuk dikirim.

FAQ

Apa itu MCP?

MCP, atau Model Context Protocol, adalah spesifikasi terbuka Anthropic untuk cara klien AI seperti Claude Desktop memanggil tool, resource, dan prompt eksternal. MCP menggunakan JSON-RPC 2.0 melalui stdio atau HTTP streaming. Spesifikasi MCP tersedia di modelcontextprotocol.io.

Dapatkah saya menguji server MCP tanpa wrapper HTTP?

Ya. Inspector MCP resmi berbicara langsung via stdio dan menyediakan UI untuk pengujian manual.

Untuk otomatisasi di Apidog, bungkus stdio dalam server HTTP tipis selama CI. Traffic produksi tetap bisa memakai stdio.

Bagaimana cara mock API upstream yang dipanggil server MCP?

Definisikan setiap endpoint upstream sebagai mock di proyek Apidog, arahkan konfigurasi server MCP ke URL mock saat test, lalu gunakan URL produksi saat runtime. Pola serupa dibahas dalam alat pengujian API untuk insinyur QA.

Bagaimana dengan streaming hasil tool?

Server MCP HTTP dapat mengalirkan hasil tool melalui Server-Sent Events. Apidog mendukung SSE dalam request yang disimpan. Aktifkan streaming pada pengaturan request, lalu buat assertion pada hasil stream yang sudah dirakit.

Haruskah saya menguji versi protokol?

Ya. Sematkan protocolVersion yang Anda dukung di initialize, lalu assert nilainya. Ketidakcocokan versi bisa menyebabkan incompatibility yang sulit terlihat.

Dapatkah saya menguji server MCP terhadap Claude Desktop asli?

Bisa, dan sebaiknya dilakukan minimal sekali sebelum rilis. Namun jangan jadikan Claude Desktop sebagai loop pengujian utama. Itu lambat, manual, dan tidak deterministik. Gunakan Apidog untuk regression suite dan Claude Desktop untuk smoke test.

Di mana saya bisa melihat contoh server MCP nyata?

Repositori server MCP resmi berisi implementasi referensi untuk filesystem, GitHub, Slack, Postgres, dan banyak lainnya. Baca definisi tool-nya untuk memahami bentuk MCP yang baik.