La diagnosi in ordine
Segui questi controlli nell'ordine: il primo che trovi è quasi sempre la causa.
- Valida il JSON. È l'errore più frequente. Copia il contenuto del file di configurazione in una chat dell'AI (sul browser) e chiedi: "questo JSON è valido? correggilo". Una virgola di troppo o una parentesi mancante impediscono il caricamento di tutti i server, non solo di quello nuovo.
- Riavvia l'app del tutto. Gli assistenti leggono la configurazione solo all'avvio. Non basta chiudere la finestra: esci davvero (anche dall'icona in basso, se resta attiva) e riapri. È la soluzione che risolve metà dei "non vedo il server".
- Verifica Node.js. Apri il terminale e scrivi
node --version. Se non risponde con un numero, Node non è installato o non è nel percorso di sistema: installalo dal sito ufficiale e riapri terminale e app. - Controlla il percorso. Il percorso del server o della cartella deve essere esatto e assoluto. Copialo dalle proprietà della cartella invece di scriverlo a mano; su Windows servono le doppie barre nel file.
Esempio concreto
A Luca il server filesystem non compare in Claude Desktop. Invece di reinstallare tutto a caso, segue l'ordine. Primo controllo: incolla il file in una chat e chiede se il JSON è valido. L'AI gli segnala una virgola mancante dopo il blocco di un altro server. La aggiunge, salva, e riavvia Claude del tutto.
Al riavvio il server compare. Tempo perso: tre minuti, invece di un pomeriggio a sospettare Node, i permessi, il server. La lezione è l'ordine: il problema era il più comune di tutti (JSON rotto), e partire da lì lo ha trovato subito. Se avesse cominciato a reinstallare Node non avrebbe risolto nulla.
Quando NON funziona (e come rimediare)
Se il server non compare proprio
Dopo aver validato il JSON e riavviato, se ancora non c'è, controlla che la voce sia scritta nel posto giusto del file (dentro mcpServers, o servers in VS Code) e che il nome non sia duplicato. Per vedere cosa succede davvero, apri il server con lo strumento ufficiale MCP Inspector (npx @modelcontextprotocol/inspector), che mostra i messaggi scambiati e gli errori.
Se compare "command not found"
Il computer non trova il comando del server (di solito npx o node). Significa che Node non è installato o non è nel percorso di sistema. Reinstalla Node.js, e dopo l'installazione chiudi e riapri sia il terminale sia l'assistente, così riconoscono il nuovo comando.
Se il server parte e si chiude subito
A volte il server si avvia e crasha. Le cause comuni: la versione di Node troppo vecchia per quel server, o il server che stampa messaggi dove non dovrebbe e rompe la comunicazione. Aggiorna Node all'ultima versione stabile, e prova il server con l'MCP Inspector: l'errore mostrato lì ti dice cosa non va.
Un consiglio da chi lo usa davvero
Quando aggiungi un server nuovo, collegane uno alla volta e verifica subito che funzioni prima di aggiungere il successivo. Così, se qualcosa si rompe, sai esattamente qual è la voce colpevole. Aggiungere cinque server insieme e poi scoprire che "non funziona niente" ti costringe a smontare tutto per trovare l'errore: un risparmio apparente che diventa una caccia al colpevole.
Domande frequenti
Dove trovo i messaggi di errore?
Due posti: l'MCP Inspector (npx @modelcontextprotocol/inspector), che apre il server in una finestra e mostra ogni scambio, e i log dell'app stessa (gli assistenti seri tengono un registro degli errori dei server, di solito raggiungibile dalle impostazioni sviluppatore). Partire da lì batte il tentare a caso.
Ho cambiato il file ma non succede niente, perché?
Quasi sempre perché manca il riavvio completo. La configurazione si legge all'avvio: finché non esci davvero dall'app e la riapri, le modifiche non hanno effetto. È il primo controllo da rifare ogni volta che "non cambia niente".
A volte il problema è un bug dell'app e non mio?
Sì, capita. Ci sono state regressioni note in cui un aggiornamento dell'app rompeva la connessione ai server per tutti, indipendentemente dalla configurazione. Se hai verificato JSON, Node, percorso e riavvio e ancora non funziona, cerca se altri segnalano lo stesso problema dopo un aggiornamento recente: in quel caso si aspetta la correzione, non è colpa tua.