Verifica e risoluzione problemi¶

Dopo aver configurato Claude Desktop con i server MCP, è importante verificare che tutto funzioni correttamente e sapere come affrontare eventuali problemi.

Indicatori visivi di attivazione MCP¶

Dopo aver riavviato Claude Desktop con una configurazione MCP valida, l'interfaccia mostra alcuni indicatori visivi che confermano l'attivazione dei server.

Fai clic sull'icona "Ricerca e strumenti" (quella con le due linee orizzontali) per aprire un menu a discesa. Oltre alle voci presenti quando si usa l'interfaccia web, qui compare anche l'elenco dei server MCP configurati.

Se vedi i tuoi server in questa lista, significa che la configurazione è stata caricata correttamente all'avvio dell'applicazione.

Test di funzionalità del server Filesystem¶

Per verificare che il server Filesystem funzioni correttamente, puoi utilizzare alcune richieste di test da rivolgere a Claude.

Test di lettura¶

Prova a chiedere a Claude di elencare i file presenti in una delle cartelle che hai reso accessibili:

"Elenca i file presenti in folder1"

Sostituisci "folder1" con il nome effettivo della cartella nella tua configurazione.

Test di scrittura¶

Verifica la capacità di creare file:

"Crea un file di testo in folder2 chiamato 'test.txt' con il contenuto 'Questo è un test'"

Anche qui, sostituisci "folder2" con il percorso effettivo.

Autorizzazioni¶

In risposta a queste richieste, Claude riconosce la necessità di utilizzare uno dei tool disponibili e richiede l'autorizzazione per accedere al filesystem. Questa richiesta di autorizzazione è un comportamento normale e serve a garantire che l'accesso ai file avvenga solo quando esplicitamente richiesto.

Dopo aver concesso l'autorizzazione, Claude esegue l'operazione richiesta e mostra il risultato nella conversazione.

Gestione dei log¶

I log dell'applicazione contengono informazioni dettagliate su eventuali errori o problemi durante il caricamento e l'esecuzione dei server MCP.

Accesso ai log generali¶

Per accedere ai log generali di Claude Desktop:

Fai clic sull'icona con le tre linee orizzontali in alto a sinistra
Seleziona "Sviluppatori"
Seleziona "Apri file di log MCP..."

Si apre la cartella contenente i file di log dell'applicazione.

Percorsi dei log¶

I log si trovano in posizioni diverse a seconda del sistema operativo:

Su Windows:

%APPDATA%\Claude\logs\mcp*.log

Su macOS:

~/Library/Logs/Claude/mcp*.log

Log specifici dei server¶

Oltre al file di log generale, ogni server MCP ha il proprio file di log. Questi log contengono informazioni specifiche sull'esecuzione di quel particolare server e sono utili per diagnosticare problemi relativi a un singolo server.

Problemi comuni e soluzioni¶

Se compare un popup che segnala un problema con un server MCP all'avvio di Claude Desktop, il primo passo consiste nel riavviare completamente l'applicazione.

Assicurati che l'applicazione sia stata chiusa correttamente prima di riavviarla. Su alcuni sistemi, l'applicazione potrebbe rimanere attiva in background anche dopo aver chiuso la finestra. Verifica nella barra delle applicazioni o nel menu dell'orologio di sistema che l'applicazione sia effettivamente terminata.

Errori di sintassi nel file di configurazione¶

Se i server non si caricano, verifica la sintassi del file JSON di configurazione. Gli errori più comuni includono:

Virgole mancanti o in eccesso: ogni elemento della lista deve essere separato da una virgola, tranne l'ultimo

Parentesi non bilanciate: ogni parentesi graffa o quadra aperta deve avere la corrispondente chiusa

Virgolette mancanti: tutti i nomi di proprietà e i valori stringa devono essere racchiusi tra virgolette doppie

Percorsi Windows errati: ricorda di usare il doppio backslash \\ nei percorsi Windows

Molti editor di testo moderni evidenziano automaticamente questi errori. Se hai dubbi sulla validità del tuo JSON, puoi copiarlo e incollarlo in un validatore JSON online per identificare rapidamente eventuali problemi di sintassi.

Percorsi non validi¶

Verifica che i percorsi specificati nella configurazione siano validi e assoluti, non relativi. Un percorso assoluto su Windows inizia con una lettera di unità (come C:\), mentre su macOS inizia con / o ~.

Controlla che le cartelle specificate esistano effettivamente sul sistema. Se una cartella non esiste, il server potrebbe non avviarsi correttamente.

Node.js non trovato¶

Se i log indicano che Node.js non viene trovato, verifica che sia installato correttamente eseguendo node --version dal terminale. Se il comando non viene riconosciuto, reinstalla Node.js seguendo le istruzioni nella sezione sui requisiti di sistema.

Dopo l'installazione di Node.js, riavvia Claude Desktop per permettere all'applicazione di rilevare la nuova installazione.

Verifica manuale dei server¶

Se le chiamate ai tool non funzionano come previsto, puoi provare ad avviare manualmente il server da terminale per identificare eventuali messaggi di errore.

Apri un terminale e esegui il comando specificato nella configurazione:

npx -y @modelcontextprotocol/server-filesystem /percorso/cartella

Sostituisci /percorso/cartella con uno dei percorsi specificati nella tua configurazione. Se il server si avvia correttamente, dovresti vedere messaggi che indicano l'inizializzazione. Eventuali errori vengono visualizzati direttamente nel terminale.

Problemi di rete in ambienti aziendali¶

In ambienti aziendali con restrizioni di rete, alcuni server MCP potrebbero non funzionare se tentano di connettersi a servizi esterni bloccati dal firewall.

Verifica con il reparto IT che:

I domini necessari siano accessibili dalla rete aziendale
Le porte richieste non siano bloccate
Il proxy aziendale, se presente, permetta le connessioni necessarie

Se utilizzi server che richiedono connessioni esterne, potrebbe essere necessario configurare il proxy nelle variabili d'ambiente del server.

Richiesta di supporto¶

Se dopo aver seguito questi passaggi il problema persiste, raccogli le seguenti informazioni prima di richiedere supporto:

Versione di Claude Desktop (visibile nel menu About)
Sistema operativo e versione
Contenuto del file di configurazione (rimuovi eventuali chiavi API sensibili)
Messaggi di errore dai log
Descrizione dettagliata del comportamento osservato

Queste informazioni aiuteranno chi fornisce supporto a identificare più rapidamente la causa del problema.

Pulizia della configurazione¶

Se desideri rimuovere tutti i server MCP e ripartire con una configurazione pulita, puoi semplicemente modificare il file di configurazione riportandolo allo stato iniziale:

{
  "mcpServers": {
  }
}

Salva il file, riavvia Claude Desktop e verifica che l'elenco dei server nel menu "Ricerca e strumenti" sia vuoto.

Best practice operative¶

Per mantenere una configurazione stabile e funzionante:

Testa i cambiamenti uno alla volta: quando aggiungi un nuovo server, testalo prima di aggiungerne altri. Questo facilita l'identificazione della causa di eventuali problemi.

Mantieni backup della configurazione: salva una copia del file di configurazione funzionante prima di modificarlo. Potrai ripristinarlo rapidamente in caso di errori.

Documenta le tue configurazioni: annota quali cartelle hai reso accessibili e perché. Questo ti aiuterà in futuro quando dovrai ricordare l'organizzazione scelta.

Aggiorna regolarmente: verifica periodicamente la disponibilità di aggiornamenti per Claude Desktop e per i server MCP che utilizzi.