Gestione degli errori del server MCP: cosa ho imparato
Pensavo di aver finito dopo che il mio server MCP è stato eseguito per la prima volta. Ha restituito un elenco di strumenti. Ha chiamato uno strumento. Mi sono sentito soddisfatto.
Mi sbagliavo.
Far girare un server MCP in produzione mi ha insegnato che i tutorial si concentrano sul percorso ideale. Ignorano cosa succede quando le cose si rompono. Ecco cosa ho imparato mentre costruivo un server per la mia base di conoscenza di 1.800 ore.
Restituisci sempre contenuti per i risultati vuoti La maggior parte dei client si blocca quando riceve una risposta vuota. Se la tua ricerca non trova nulla, non restituire il nulla. Restituisci un messaggio di testo. Spiega all'utente perché non ci sono risultati e quanti elementi esistono nel tuo database.
Gestisci l'avvio lento delle connessioni Ospito su un piano gratuito che va in standby. Quando si risveglia, impiega 15 secondi. Molti client MCP vanno in timeout prima di allora. • Invia header precoci per mantenere attiva la connessione. • Imposta limiti rigidi sulla dimensione della risposta. Tronca i risultati grandi in modo da non superare i limiti di timeout.
Smetti di costruire manualmente il JSON Una singola virgoletta doppia non escapata in un titolo ha rotto l'intera risposta JSON. Il client si è disconnesso senza alcun errore. Usa un framework come Jackson per gestire la serializzazione. Lascia che la libreria gestisca l'escaping per te.
Aspettati un'autenticazione incoerente Diversi client gestiscono le chiavi API in modo differente. Alcuni usano gli header. Altri usano i parametri di query. Altri non usano nessuno dei due. • Supporta più modi per inviare le chiavi. • Restituisci sempre un corpo di errore JSON appropriato se l'autenticazione fallisce.
Imposta esplicitamente il Content-Length Alcuni client hanno difficoltà con la chunked encoding. Se le tue risposte vengono troncate, smetti di usare la compressione. Calcola preventivamente la dimensione della risposta e imposta esplicitamente l'header Content-Length.
I Pro: • Privacy: solo gli snippet rilevanti vengono inviati all'IA. • Interoperabilità: il server funziona su diversi client. • Semplicità: il mio server è di sole 150 righe di codice.
I Contro: • Ecosistema giovane: la documentazione omette molti casi limite. • Hosting: devi gestire i tuoi endpoint e i cold start. • Evoluzione: il protocollo cambia spesso.
MCP ha trasformato i miei appunti inutilizzati in uno strumento utile. Rende i miei dati disponibili in modo che l'IA possa svolgere il lavoro pesante.
Hai costruito un server MCP? Quali errori hai riscontrato? Fammi sapere nei commenti.
Community di apprendimento opzionale: https://t.me/GyaanSetuAi