# Risoluzione dei problemi MCP
SUMMARY: Risolve i problemi comuni di integrazione MCP — server che non si avvia, strumenti che non appaiono, errori di autenticazione.

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

Risoluzione dei problemi MCP
Problemi comuni e soluzioni nell'integrazione di Synapse MCP con il proprio
client LLM.
Lista di controllo diagnostica rapida
1. ✅ Node.js 18+ installato? ()
2. ✅ La Mind Key inizia con ? (non JWT )
3. ✅ L'API di Synapse è raggiungibile? ()
4. ✅ La Mind Key funziona? ()
5. ✅ Il file di configurazione è JSON valido? (nessuna virgola finale, nessun commento)
6. ✅ Il client è stato riavviato dopo la modifica della configurazione?
7. ✅ Il server MCP si avvia manualmente? ()
Problema: nessuno strumento appare nel client
Sintomi
- Claude Desktop / Cursor / Continue mostra 0 strumenti
- Nessuna icona 🔌 o voce "synapse" nell'elenco dei server MCP
Soluzioni
1. Riavvi completamente il client — Cmd+Q su macOS (non solo chiuda la finestra)
2. Controlli la posizione del file di configurazione:
   - Claude Desktop macOS: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. Validi il JSON — incolli la configurazione in <https://jsonlint.com>
4. Controlli i log del client per errori MCP:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. Eseguia il server MCP manualmente per vedere gli errori di avvio:
   [CODE BLOCK]
Problema: errore "Mind Key invalid"
Sintomi
- Gli strumenti appaiono ma le chiamate falliscono con "401 Unauthorized"
- Errore: "Mind Key fehlt oder ungültig"
Soluzioni
1. Verifichi il formato della Mind Key — inizia con , circa 40 caratteri
2. Testi direttamente:
   [CODE BLOCK]
3. Controlli che la variabile d'ambiente sia impostata — per il trasporto
   stdio, la variabile deve trovarsi nella configurazione del server MCP, non
   nella shell
4. Ottenga una nuova Mind Key:
   [CODE BLOCK]
Problema: npx non trovato
Sintomi
- Errore: "npx: command not found"
- Il server MCP non si avvia
Soluzioni
1. Installi Node.js 18+:
   - macOS:  o scarichi da <https://nodejs.org>
   - Linux: 
   - Windows: scarichi da <https://nodejs.org>
2. Riavvii il terminale dopo l'installazione
3. Verifichi: 
Problema: SYNAPSEURL non raggiungibile
Sintomi
- Il server MCP si avvia ma le chiamate agli strumenti vanno in timeout
- Errore: "fetch failed" o "ECONNREFUSED"
Soluzioni
1. Testi la connettività:
   [CODE BLOCK]
2. Controlli il firewall aziendale — potrebbe bloccare l'HTTPS in uscita
3. Provi un URL alternativo:
   - Produzione: 
   - Server MCP: 
4. Per istanze self-hosted: si assicuri che la propria istanza Synapse sia in esecuzione e accessibile
Problema: il server MCP si blocca
Sintomi
- Il server MCP esce immediatamente dopo l'avvio
- I log del client mostrano "MCP server disconnected"
Soluzioni
1. Lo esegua manualmente per vedere l'errore:
   [CODE BLOCK]
2. Controlli i conflitti di porta — il server MCP usa la porta 13100 per impostazione predefinita
3. Pulisca la cache di npx:
   [CODE BLOCK]
4. Aggiorni all'ultima versione:
   [CODE BLOCK]
Problema: le chiamate agli strumenti restituiscono 429
Sintomi
- Errore: "Rate limit exceeded"
Soluzioni
Non dovrebbe succedere con MCP (usa l'autenticazione tramite header, nessun
rate limit). Se succede:
1. Controlli se sta usando  da qualche parte — passi all'autenticazione tramite header
2. Verifichi  — si assicuri che punti all'istanza corretta
3. Contatti l'assistenza se il problema persiste
Problema: gli strumenti appaiono ma non funzionano
Sintomi
- Strumenti elencati nel client
- La chiamata a uno strumento restituisce un errore o nessun risultato
Soluzioni
1. Controlli il nome dello strumento — deve essere esatto (es. , non )
2. Verifichi gli argomenti — controlli lo schema di input dello strumento
3. Testi tramite API diretta:
   [CODE BLOCK]
4. Controlli lo stato di Synapse:
   [CODE BLOCK]
Ottenere assistenza
Se nessuna delle soluzioni precedenti risolve il problema:
1. Controlli le issue esistenti: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. Apra una nuova issue con:
   - Versione del server MCP ()
   - Nome e versione del client
   - Sistema operativo
   - Estratti di log rilevanti
   - Passaggi per riprodurre il problema
Prossimi passi
- Configurazione di Claude Desktop
- Configurazione di Claude Code
- Errori API