MCP Inspector - Foglio di aiuto per il debug dei server Model Context Protocol
MCP Inspector è lo strumento visivo ufficiale di test e debug per i server Model Context Protocol. Quando stai costruendo un server MCP, devi vedere cosa espone effettivamente e come risponde — Inspector si connette al tuo server, elenca i suoi strumenti, risorse e prompt, ti permette di invocare ognuno con argomenti arbitrari e mostra i messaggi JSON-RPC grezzi che fluiscono in entrambe le direzioni. È il modo più veloce per verificare che un server funzioni prima di collegarlo a Claude, Cursor o un altro client.
Esecuzione
| Metodo | Comando |
|---|
| npx (nessuna installazione) | npx @modelcontextprotocol/inspector |
| Con il tuo server | npx @modelcontextprotocol/inspector node build/index.js |
| Server Python | npx @modelcontextprotocol/inspector uv run server.py |
| Server remoto/SSE | avvia, quindi inserisci l’URL nell’interfaccia |
| UI | si apre nel browser (predefinito http://localhost:6274) |
Tipi di connessione
| Trasporto | Uso |
|---|
| STDIO | Server locale eseguito come sottoproce (più comune) |
| SSE | Server remoto su Server-Sent Events |
| Streamable HTTP | Trasporto remoto moderno |
# Ispeziona un server stdio locale, passando arg e env
npx @modelcontextprotocol/inspector \
-e API_KEY=abc123 \
node build/index.js --verbose
L’interfaccia
| Scheda | Mostra |
|---|
| Tools | Ogni strumento, il suo schema JSON e un modulo per chiamarlo |
| Resources | Risorse esposte e i loro contenuti |
| Prompts | Template di prompt e i loro argomenti |
| Notifications | Messaggi/log avviati dal server |
| History | Ogni coppia request/response |
Test degli strumenti
| Step | Azione |
|---|
| 1 | Apri la scheda Tools; conferma che il tuo strumento è elencato |
| 2 | Verifica che lo schema di input sia visualizzato correttamente (tipi, campi obbligatori) |
| 3 | Riempi il modulo generato e fai clic per invocare |
| 4 | Ispeziona il contenuto restituito e qualsiasi flag isError |
| 5 | Leggi il JSON-RPC grezzo in History per eseguire il debug dei problemi di forma |
Questo ciclo cattura gli errori MCP più comuni: uno schema malformato, uno strumento che restituisce la forma di contenuto sbagliata o un errore non gestito.
Cosa verificare prima di spedire
| Controllo | Perché |
|---|
| I nomi degli strumenti sono univoci/descrittivi | I client li espongono al modello |
| Le descrizioni spiegano quando usare lo strumento | Guida la selezione corretta del modello |
| Lo schema di input è preciso | Previene le chiamate malformate |
Gli errori restituiscono isError con un messaggio | Il modello può recuperare |
| Gli output grandi sono impaginati/troncati | Evita di far esplodere la finestra di contesto |
| Le risorse hanno URI stabili | I client le cachano/riferiscono |
Suggerimenti per il debug
| Sintomo | Guarda |
|---|
| Il server non si connette | Comando/arg; stderr nel terminale di lancio |
| Strumento mancante | Codice di registrazione; riavvia il server |
| Lo schema si rende male | Tipi JSON Schema nella definizione dello strumento |
| Il client si comporta diversamente | Confronta il JSON-RPC grezzo in History |
| Bug dipendente da env | Riavvia Inspector con -e KEY=value |
Workflow comuni
# Ciclo sviluppo-e-test per un server MCP TypeScript
npm run build && npx @modelcontextprotocol/inspector node build/index.js
# Testa un server Python con uv
npx @modelcontextprotocol/inspector uv run my_server.py
# Verifica un server SSE remoto prima di aggiungerlo a un client
npx @modelcontextprotocol/inspector # scegli SSE, incolla l'URL
MCP Inspector vs Alternative
| Approccio | Trade-off |
|---|
| MCP Inspector | Costruito a scopo, visivo, mostra il protocollo grezzo |
| Collegamento a un client reale | Realistico ma ciclo di feedback lento |
| JSON-RPC scritto manualmente | Controllo completo, tedioso |
| Test unitari | Veloce e ripetibile; abbina Inspector per l’esplorazione |
Usa Inspector mentre costruisci, poi aggiungi test automatizzati; vedi MCP servers per i pattern di implementazione del server.
Risorse
