Debug Server MCP Apa Pun dalam 5 Menit dengan MCP Inspector

Server MCP kamu sudah jadi. Kodenya kelihatan benar. Schema-nya valid. Kamu sambungin ke Claude Code dan panggil sebuah tool, dan Claude bilang "I cannot find that tool" atau lebih buruk lagi, mengembalikan stack trace dari dalam proses kamu. Protokolnya melakukan sesuatu yang kamu nggak duga, dan kamu nggak tahu sisi mana yang salah.

Itulah fungsi MCP Inspector. Dia adalah developer tool resmi dari project Model Context Protocol, dan dia berfungsi sebagai client yang ngomong sama server kamu lewat wire format yang sama dengan host asli. Kamu jalanin, arahin ke server kamu, dan kamu lihat persis pesan apa yang lewat, capability apa yang di-advertise, dan argumen apa yang bakal dikirim oleh tool call beneran. Tanpa host, tanpa LLM yang nebak fungsi kamu maunya apa. Cuma protokolnya, mentah.

Package-nya @modelcontextprotocol/inspector di npm. Versi terkini 0.22.0 per tulisan ini. Kamu nggak install. Dia jalan lewat npx.

Prerequisites

Node.js 18+ (cek dengan node --version)
Server MCP yang kamu tulis, atau nama package dari npm atau PyPI
Browser (Inspector adalah web UI lokal di port 6274)

Langkah 1: Jalankan Inspector Menembak Package Remote

Cara tercepat untuk lihat apa yang Inspector lakukan adalah mengarahkan dia ke server publik beneran. Server filesystem resmi adalah target yang bagus.

npx -y @modelcontextprotocol/inspector   npx -y @modelcontextprotocol/server-filesystem /tmp

Satu perintah itu nge-start Inspector, nge-launch server filesystem sebagai child process, dan buka UI di http://localhost:6274. Inspector tetap di depan, server jalan di belakang, dan setiap JSON-RPC frame di antara mereka terlihat sama kamu.

Kalau package-nya ada di PyPI bukan npm, ganti launchernya:

npx -y @modelcontextprotocol/inspector   uvx mcp-server-git --repository ~/code/some-repo

Bentuk umumnya adalah inspector <launcher> <package> [args...]. Inspector cuma peduli bahwa hal pertama yang kamu kasih adalah sesuatu yang bisa dia jalanin dan ajak bicara lewat stdio.

Langkah 2: Pahami Empat Tab

UI-nya punya empat tab kerja dan connection pane di atas. Kamu bakal ngabisin大部分 waktu di tiga tab pertama.

Server connection pane. Ini adalah launchpad. Dia nunjukin transport (stdio dalam kasus kita), command, argumen, dan environment variable. Kalau kamu debug server yang butuh API key, kamu set di sini sebelum konek. Inspector spawn server sebagai child process dan ngomong JSON-RPC lewat stdin dan stdout-nya.

Resources tab. Nampilin setiap resource yang di-advertise server kamu waktu handshake initialize, dengan URI, MIME type, dan deskripsi. Kamu bisa klik sebuah resource untuk baca isinya, yang kirim request resources/read. Kalau resource ditandai sebagai subscribable, kamu juga bisa test apakah alur subscription-nya jalan. Ini tab yang kamu buka duluan kalau client asli bilang "saya nggak lihat file saya."

Prompts tab. Nampilin setiap template prompt yang di-declare server kamu. Kamu isi argumennya, klik "Get Prompt," dan Inspector kirim request prompts/get dan nunjukin rendered message list. Kalau promptnya ngarepin argumen yang kamu lupa declare sebagai required, tab ini kasih tahu sebelum host melakukannya.

Tools tab. Di sinilah sebagian besar debugging terjadi. Tab ini nampilin setiap tool dengan JSON Schema-nya. Kamu ketik argumen secara manual, pencet "Call Tool," dan Inspector kirim request tools/call dan nunjukin response, termasuk content terstruktur atau error. Dua skenario debugging yang langsung ketangkep di sini:

Tool yang declare required: ["query"] tapi schema-nya cuma nandain field sebagai description. Inspector jalanin call-nya, server kembalikan validation error, dan kamu lihat mismatch-nya tanpa butuh host.
Tool yang mengembalikan result dengan urutan yang host nggak bisa parse karena array content-nya mencampur item text dan resource dengan urutan yang client nggak duga. Inspector render raw response-nya jadi kamu bisa bandingin.

Notifications pane. Bawah jendela. Setiap log line dan server-sent notification masuk sini. Kalau server kamu emit progress update atau log message, di sinilah mereka muncul.

Langkah 3: Arahin ke Server Kamu Sendiri

Local development adalah use case yang sebenarnya. Kamu punya file Python di ./weather.py dan kamu mau lihat protokolnya kayak apa.

npx -y @modelcontextprotocol/inspector   uv --directory . run weather.py

Kalau server kamu TypeScript:

npx -y @modelcontextprotocol/inspector   node ./build/index.js

Kamu juga bisa set environment variable sebelum command launch. Inspector nangkep mereka, yang berguna untuk test server yang baca secret saat startup.

Langkah 4: Development Loop yang Beneran Nangkep Bug

Dokumentasi Inspector ngasih workflow. Saya ikutin versi yang lebih ketat.

Launch Inspector yang nunjuk ke server kamu. Konfirmasi connection pane nunjukin transport yang tepat dan indikator "Connected" hijau. Kalau merah, server gagal waktu handshake initialize. Notifications pane punya alasannya.
Cek capability negotiation. Buka tab Resources, Prompts, dan Tools. List-nya harus cocok sama yang sebenarnya di-expose server kamu. Kalau tool hilang, bug-nya hampir selalu di kode registrasi, bukan di protokol.
Panggil setiap tool sekali dengan argumen minimal. Kamu nggak test business logic di sini. Kamu test bahwa round trip jalan dan response shape-nya cocok sama schema. Sebagian besar mismatch protokol muncul di sini.
Panggil setiap tool dengan edge case. String kosong, optional field yang nggak ada, input yang sangat panjang, unicode, dan apapun yang mungkin bikin handler kamu trip. Inspector ngizinin kamu kirim apa pun, jadi dorong.
Reconnect setelah setiap perubahan kode yang berarti. Inspector nggak hot-reload. Kamu ubah server, klik "Reconnect," dan kamu test ulang. Kedengeran obvious, tapi saya udah lihat engineer ngabisin dua puluh menit debug fix yang sebenernya nggak pernah di-load.
Baca Notifications pane. Kalau server kamu diam, itu juga informasi. Server yang well-behaved emit log line waktu koneksi. Yang diam menyembunyikan sesuatu.

Apa yang Ditangkep Inspector yang Disembunyiin Host

Host asli nambahin layer antara kamu dan protokol. Claude Code retry call yang gagal. Claude Desktop normalisasi error. Integrasi IDE mungkin filter resource sebelum nyampe ke kamu. Inspector nggak ngapa-ngapain itu. Kalau server kamu punya bug, kamu lihat bug-nya, bukan interpretasi host.

Tiga hal yang saya sendiri pernah tangkep pakai Inspector yang bakal kelewat kalau nggak:

Tool handler yang mengembalikan objek Python datetime alih-alih string. Python SDK serialize itu jadi string, tapi schema-nya bilang string dengan format date-time, dan validator host nolak. Inspector nunjukin schema mismatch di tab Tools.
Resource yang nunjuk ke path file yang proses server nggak bisa baca karena working directory-nya beda dari asumsi saya. Tab Resources ngizinin saya klik dan lihat error aslinya dari server, yaitu "Permission denied" yang jelas. Saya lagi mantengin log host yang bilang "Resource not found" dan ngira URI-nya salah.
Panggilan logging/setLevel yang server saya nggak pernah implement. Inspector surface itu sebagai "Method not found" di Notifications pane. Host bakal diem-diem ngabaikan.

Kesalahan Umum

Stdio buffering. Kalau server kamu nulis ke stdout tapi Inspector nggak lihat output, penyebabnya hampir selalu I/O buffer. Di Python, panggil sys.stdout.flush() setelah setiap tulis, atau pake print(..., flush=True). Server MCP stdio harus flush setelah setiap JSON-RPC frame, atau Inspector bakal nunggu pesan yang lagi duduk di buffer.

Working directory salah. Inspector spawn server kamu di direktori tempat kamu nge-launch npx, bukan di direktori server-nya. Kalau server kamu baca config file relatif, jalanin Inspector dari direktori yang tepat atau kirim path absolut.

Proses long-lived. Inspector bunuh server child process waktu kamu tutup koneksi. Kalau kamu start server di luar Inspector dan arahin ke URL-nya, itu alur kode yang beda. Untuk local development, biarin Inspector jadi parent-nya.

Autentikasi untuk server remote. Inspector support streamable HTTP dan SSE, dengan dukungan bearer token di connection pane. Untuk alur OAuth 2.1 (spesifikasi nambahin ini di revisi 2025-06-18), Inspector belum ngelakuin authorization dance secara penuh. Kamu perlu obtain token di luar dan paste manual.

Kapan Pake Inspector vs Claude Code

Inspector untuk debugging protokol. Claude Code untuk behavior end-to-end. Pake Inspector kalau pertanyaannya "apa yang protokol lihat." Pake Claude Code kalau pertanyaannya "apakah agent-nya ngelakuin hal yang tepat sama server saya."

Splittan praktis: bangun server, debug setiap tool dan resource di Inspector sampai round trip-nya bersih, lalu sambungin ke Claude Code dan test perilaku agentik. Campur dua-duanya itu resep buat ngejar layer yang salah kalau ada yang rusak.

Lanjut ke Mana

Inspector itu sendiri: github.com/modelcontextprotocol/inspector. Open source dan nerima kontribusi.
Spesifikasi resmi di modelcontextprotocol.io/specification/2025-06-18. Inspector cuma cek apa yang dibilang spec harus dia cek, jadi spec adalah source of truth kalau ada perilaku yang bikin kamu kaget.
Debugging Guide di modelcontextprotocol.io/docs/tools/debugging. Nguli tools lain di luar Inspector, termasuk mcp-debug dan testing curl manual untuk server streamable HTTP.