Debug di Server LLM Senza Grattacapi con MCP Inspector

Conosci quella sensazione quando stai cercando di far funzionare un agente AI con la tua API locale, e questo si blocca oppure sputa fuori qualche errore criptico? Ti siedi lì a chiederti: è il prompt che è rotto, il server è andato in crash, oppure i dati arrivano nel formato sbagliato? Storia familiare. Gli sviluppatori di Anthropic sembrano aver vissuto la stessa esperienza, ed è per questo che hanno rilasciato MCP Inspector.

Questo è un debugger visivo per il Model Context Protocol (MCP). In breve, MCP è un nuovo standard che aiuta i modelli linguistici a comunicare con strumenti esterni, database e file system. E Inspector è fondamentalmente un Postman, ma specifico per lavorare con i server LLM.

Cosa c'è sotto il cofano e come funziona

Lo strumento è composto da due parti. La prima è un client React che vedi nel browser. La seconda è un server proxy che gira su Node.js. Questo proxy è la parte più interessante: può convertire stream di input/output standard (stdio) o stream HTTP in un'interfaccia accessibile dal browser.

Molti server MCP funzionano attraverso input/output standard della console. Un browser non può comunicare direttamente con un processo del genere, quindi il proxy fa da ponte: lancia il tuo server, intercetta i suoi messaggi e li trasmette all'interfaccia web.

Come iniziare rapidamente

Se hai Node.js versione 22.7.5 o superiore, basta digitare nel tuo terminale:

npx @modelcontextprotocol/inspector

Il comando avvierà un'interfaccia web sulla porta http://localhost:6274. A proposito, la scelta delle porte qui è divertente: 6274 corrisponde ai tasti MCPI (MCP Inspector) su un vecchio telefono con tastiera.

Se stai costruendo il tuo server, puoi puntare l'inspector direttamente su di esso:

npx @modelcontextprotocol/inspector node build/index.js

L'inspector rileva il build, passa gli argomenti necessari e apre il browser con tutti i tuoi strumenti e risorse visibili.

Cosa può fare questo debugger

Il principale punto di forza dell'inspector è la sua interattività. Non devi scrivere script per testare ogni funzione.

Prima di tutto, c'è il test degli strumenti. Vedi un elenco di tutte le funzioni che il server espone al modello. Puoi compilare gli argomenti direttamente nel form (niente JSON manuale nella console) e premere "Call Tool". La risposta arriva istantaneamente, e puoi vedere subito se la struttura dati è "cambiata" o è andata in malora.

Secondo, c'è l'esplorazione delle risorse. Se il tuo server fornisce accesso a file o log, puoi esplorarli in un'interfaccia ad albero nell'inspector. Questo è un salvavita quando devi capire esattamente quale contesto sta ricevendo il modello.

Terzo, c'è la gestione dei prompt. Puoi testare i template di prompt incorporati nel server e vedere come vengono popolati con i dati in tempo reale.

Sicurezza e sfumature

Gli sviluppatori non hanno messo quell'enorme avviso nel README per niente. Il succo è che il server proxy ha il diritto di lanciare processi sulla tua macchina. Se apri semplicemente la sua porta su internet, chiunque può eseguire codice arbitrario.

Di default, l'inspector genera un token di sessione casuale. Sembra così: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=ваш_длинный_хеш

Non ti consiglierei di disabilitare questo controllo con il flag DANGEROUSLY_OMIT_AUTH, anche se sei troppo pigro per copiare il link. Ci sono stati casi (CVE-2025-49596) in cui tali porte aperte potrebbero portare a RCE semplicemente visitando un sito malevolo in un'altra scheda del browser.

Quando usarlo

Per me, la scoperta più grande è stata la modalità CLI. È perfetta per accoppiarla con Cursor o altri assistenti di codifica AI. Puoi eseguire un comando:

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

E ottenere JSON pulito con un elenco di strumenti. Questo accelera il ciclo "ho scritto il codice — ho testato — ho corretto" a passi da gigante.

L'inspector tornerà sicuramente utile se:

1. Stai costruendo un server MCP personalizzato per la tua azienda.
2. Stai cercando di collegare Claude Desktop con un database locale.
3. Stai eseguendo il debug di catene di chiamate di strumenti complesse dove la sequenza degli argomenti conta.

Lo strumento si è rivelato sorprendentemente solido per un protocollo così giovane. Sì, la documentazione è ancora un po' scarsa, e l'interfaccia sembra spartana, ma eccelle nel suo lavoro — "mostrarti cosa c'è sotto il cofano di un server LLM".

Se stai pianificando di integrare agenti AI nei tuoi flussi di lavoro, aggiungi questo repo ai preferiti. Ti farà risparmiare un sacco di ore di debug su campi mancati negli schema JSON o percorsi file errati.