La causa di gran lunga più comune di «l'assistente non vede i miei dati» non è
un server rotto. È un client che non è mai stato riavviato dopo la modifica
della configurazione. Quasi tutti i client MCP leggono la propria configurazione
all'avvio e mai più, quindi un file modificato mentre l'applicazione era aperta
è un file che l'applicazione non ha letto. Va chiusa del tutto — su macOS
chiudere la finestra lascia il processo in esecuzione — e poi riaperta. In
Claude Code si esegue /mcp invece di riavviare il terminale.
Se questo non basta, la domanda utile non è «quale client sto usando» ma «che cosa sta succedendo esattamente». Un server assente, un server che si collega ma non espone strumenti, strumenti che non restituiscono nulla e strumenti che falliscono solo quando provano a modificare qualcosa sono quattro guasti diversi con quattro rimedi diversi — e il rimedio dipende poco dall'applicazione in uso. Ogni dettaglio di questa pagina è stato controllato sulla documentazione dei fornitori il 14 agosto 2026.
Prima di modificare qualsiasi cosa conviene guardare che cosa il client già sa. Ogni client ha esattamente un posto che risponde alla domanda «questo server si è collegato?», e tirare a indovinare dalla finestra di chat è il modo in cui si passa un'ora su un problema che quella schermata nomina in un secondo.
| Client | Dove guardare | Come si presenta un server sano |
|---|---|---|
| Claude Code | claude mcp list oppure il pannello /mcp |
✔ Connected |
| Claude Desktop | icona più nel campo di chat → Connectors | il server elencato con i suoi strumenti |
| Cursor | pannello Output (Cmd+Shift+U) → MCP Logs |
inizializzazione, nessun errore di connessione |
| VS Code | MCP: List Servers nella Command Palette | il server parte, il registro Show Output è pulito |
| Zed | Settings → AI → MCP Servers | pallino verde, suggerimento Server is active |
Claude Code è il più informativo dei cinque. claude mcp list stampa uno stato
di salute accanto a ogni server — ✔ Connected, ! Needs authentication,
✘ Failed to connect, ⏸ Pending approval — e aggiunge il dettaglio del
guasto sulla stessa riga; claude mcp get <name> mostra la stessa cosa su una
riga Issue:, incluso il testo dell'errore restituito dal server.
Se la schermata di stato non mostra il server, il client non sta leggendo la voce che è stata scritta. Tre cause coprono quasi tutti i casi.
Il file non è JSON valido. Basta una virgola di troppo o una parentesi mancante e il client ignora l'intero file — non solo la voce rotta — di solito senza dirlo. Conviene incollare il file in un validatore JSON prima di sospettare qualunque altra cosa.
È stato modificato un file diverso da quello che il client legge. Quasi ogni
client ha sia una configurazione personale sia una legata al progetto, e
modificare quella sbagliata produce esattamente questo sintomo. Cursor legge
~/.cursor/mcp.json a livello globale e .cursor/mcp.json dentro un progetto;
VS Code legge .vscode/mcp.json in un'area di lavoro e un mcp.json del profilo
utente, che si apre con MCP: Open User Configuration. Claude Code ha tre
ambiti — locale e utente in ~/.claude.json, progetto in un .mcp.json alla
radice del repository — e quando un nome è definito in più di uno, il locale
vince sul progetto, che vince sull'utente. La voce arriva per intero dall'ambito
vincente: i campi non vengono fusi.
Il nome della chiave non è quello di quel client. La chiave di primo livello
di VS Code è servers, quella di Zed è context_servers, tutti gli altri usano
mcpServers. Un blocco mcpServers incollato in VS Code non è un errore che
l'editor segnala: è semplicemente una chiave che non legge. La questione è
trattata client per client in
dove sta la configurazione MCP.
Un caso sembra un server mancante ma non lo è: in Claude Code un server legato al
progetto resta su ⏸ Pending approval finché non si esegue claude in modo
interattivo in quella cartella e lo si approva, e le approvazioni committate nel
repository vengono ignorate finché l'area di lavoro non viene dichiarata fidata.
Quando nella configurazione non è cambiato nulla e il server ha smesso di
collegarsi, di solito la configurazione contiene ancora un percorso assoluto a un
programma che non è più lì. Aggiornare un'applicazione dentro un'altra cartella,
rinominarla o spostarla fuori da Applicazioni rompe il percorso mentre il JSON
sembra ancora corretto, e nulla nell'errore del client indica lo spostamento.
Prima di ogni altra cosa conviene confrontare il valore di command con la
realtà:
ls -l "/absolute/path/from/your/config"
Lo stesso tipo di guasto colpisce i server avviati tramite un gestore di
versioni. Se command è node, npx, python o uv e il runtime arriva da
nvm, pyenv o asdf, il percorso esiste nel terminale e non esiste per il client,
perché il client non avvia una shell di login. Il nome nudo va sostituito con il
percorso assoluto — lo restituisce which node — oppure command va puntato
direttamente sul binario.
Uno stato verde con l'elenco degli strumenti vuoto significa che l'handshake è
riuscito e che tools/list non ha restituito nulla di utile. Due cose lo
producono.
La prima è un server che dichiara davvero un insieme di strumenti vuoto, cosa che si può confermare fuori dal client con MCP Inspector — l'interfaccia di prova di riferimento, che si collega direttamente a un server stdio o Streamable HTTP ed elenca ciò che pubblica. Se Inspector vede gli strumenti e il client no, il guasto è nella configurazione del client.
La seconda è un tetto degli strumenti. VS Code limita una singola richiesta di chat a 128 strumenti attivi e rifiuta la richiesta quando il totale lo supera, soglia che una macchina affollata raggiunge più in fretta di quanto si pensi; il pulsante Configure Tools nella vista Chat è il posto dove disattivare qualche server per rientrare sotto il limite. Cursor consente di disattivare i singoli server dal pannello Customize nella barra laterale, e un server disattivato non viene caricato e non compare in chat — vale la pena controllarlo per primo, perché un interruttore spostato il mese scorso è indistinguibile da un server che non è partito.
Gli strumenti sono elencati, l'assistente li chiama e i risultati sono vuoti. Qui il trasporto è a posto: la questione riguarda i dati, non la configurazione. Va verificato che la libreria letta dal server sia quella che si ha in mente — account giusto, dispositivo giusto, e contenuti davvero sincronizzati su questa macchina invece che presenti solo su un'altra. Poi vanno guardati gli argomenti della chiamata nel registro del client: un assistente che ha indovinato un intervallo di date o un filtro può produrre un risultato vuoto da una libreria perfettamente sana.
Se le ricerche riescono ma ogni tentativo di rinominare, etichettare o aggiornare qualcosa fallisce, non è un problema di trasporto. I server si dividono spesso in strumenti che leggono e strumenti che modificano i dati, e la metà che modifica porta di frequente un requisito in più: un'applicazione in esecuzione, una sessione autenticata, un permesso che il client non ha ricevuto. Due cause lato client vanno escluse per prime. Gli strumenti che modificano i dati sono dichiarati come tali, quindi il client chiede conferma prima di eseguirli — e una richiesta di conferma respinta si legge nella trascrizione come un fallimento. Inoltre, un server avviato con un flag di sola lettura non pubblica affatto quegli strumenti: è una scelta di configurazione, non un guasto.
Questo è un difetto del server, non di chi lo usa, e vale la pena riconoscerlo
perché il messaggio d'errore confonde. Su stdio il protocollo richiede che
l'output standard trasporti soltanto messaggi JSON-RPC, quindi un server che
stampa su stdout un'intestazione di versione, una riga «avvio in corso» o un
registro colorato corrompe il flusso, e il client fallisce con un errore di
parsing che cita i primi caratteri di ciò che è stato stampato —
Unexpected token 'S', "Starting s"... is not valid JSON. La correzione spetta
all'autore del server: le righe di registro vanno su stderr, che l'host cattura
comunque.
L'ambiente è l'altra trappola all'avvio. Un server stdio eredita solo un
sottoinsieme limitato di variabili d'ambiente, che dipende dalla piattaforma —
non il profilo della shell — e la sua directory di lavoro può essere indefinita,
di fatto / su macOS. Quel che serve al server va passato con la chiave env
nella sua voce di configurazione, tenendo assoluti tutti i percorsi.
command esista, come percorso assoluto.Partire dall'alto costa un minuto. Cominciare dal punto sette è il modo in cui un problema da cinque secondi diventa un pomeriggio.
Speak-Y include il proprio server MCP dentro l'applicazione macOS, quindi diversi
dei guasti visti sopra non possono capitargli: non c'è alcun pacchetto npm da
installare, nessun runtime da risolvere attraverso nvm, nessun token che scada.
Quello che può capitare è il percorso obsoleto, e l'applicazione lo ripara da
sola. All'avvio controlla le configurazioni di Claude Code, Claude Desktop e
Cursor e riscrive il valore di command dove punta a una vecchia posizione
dell'applicazione — solo per le voci che sono davvero sue, riconosciute dal suo
binario e dall'argomento --mcp, così un server diverso che per caso condivide il
nome resta intatto. Se serve farlo a mano, Impostazioni → Integrazioni mostra
Reinstalla accanto a ogni client rilevato; dopodiché si riavvia il client,
oppure si esegue /mcp in Claude Code.
La divisione fra lettura e modifica è l'altro sintomo da saper riconoscere.
Cercare fra le registrazioni e leggere trascrizioni, riassunti e punti d'azione
funziona direttamente sulla libreria presente su questa macchina e non richiede
nulla in esecuzione. Gli strumenti che organizzano — tag, titoli, nomi degli
interlocutori, ri-trascrizione, pubblicazione in un canale del team —
passano dall'applicazione in esecuzione, quindi con Speak-Y chiuso falliscono
mentre la ricerca continua a funzionare. Questa asimmetria è già una diagnosi: se
la lettura funziona e la modifica no, conviene avviare l'applicazione invece di
modificare qualsiasi configurazione. Aggiungere --read-only agli argomenti del
server toglie del tutto gli strumenti che modificano dalla vista del client:
comportamento voluto, non malfunzionamento. E risultati vuoti da un server sano
di solito significano che la registrazione è ancora su un altro dispositivo: il
server legge questo disco e non va a prendere il resto.
Se si sta configurando invece che riparando, le guide dedicate a ciascun client sono più utili di questa pagina: Claude Desktop e Claude Code passo per passo, e VS Code, Zed e Devin Desktop per gli editor la cui forma di configurazione si discosta da quella di tutti gli altri.
Quasi tutti i client leggono la configurazione MCP solo all'avvio, quindi una configurazione scritta mentre il client era in esecuzione non è ancora stata caricata. Si chiude del tutto l'applicazione e la si riapre — su macOS chiudere la finestra non basta — mentre in Claude Code si esegue /mcp invece di riavviare il terminale.
Ogni client ha un posto preciso che risponde. Claude Code: claude mcp list, che stampa ✔ Connected, ! Needs authentication oppure ✘ Failed to connect accanto a ciascun server. Claude Desktop: l'icona più nel campo di chat, poi Connectors. VS Code: MCP: List Servers dalla Command Palette. Cursor: il pannello Output con MCP Logs selezionato. Zed: Settings → AI → MCP Servers, dove un pallino verde riporta Server is active.
In ~/Library/Logs/Claude su macOS e in %APPDATA%\Claude\logs su Windows. Si seguono dal vivo con tail -n 20 -F ~/Library/Logs/Claude/mcp*.log. Il file mcp.log contiene gli eventi generali di connessione, mentre mcp-server-NOME.log contiene ciò che quel server ha scritto su stderr.
È il client ad avviare il processo, non la shell di login. Non eredita il PATH completo ma solo un sottoinsieme limitato di variabili d'ambiente, che dipende dalla piattaforma, e la sua directory di lavoro può essere indefinita. Conviene usare un percorso assoluto per command, percorsi assoluti negli argomenti e passare esplicitamente le variabili necessarie con la chiave env.
Quasi sempre il percorso assoluto nella configurazione MCP, che punta a dove l'applicazione si trovava prima. Reinstallarla in un'altra cartella, rinominarla o spostarla fuori da Applicazioni rompe il percorso mentre la configurazione continua a sembrare corretta. Si riesegue l'installazione a un clic del client, così il percorso viene riscritto.