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? (node --version)
2. ✅ La Mind Key inizia con mk_? (non JWT eyJ...)
3. ✅ L'API di Synapse è raggiungibile? (curl https://synapse.schaefer.zone/health)
4. ✅ La Mind Key funziona? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
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? (npx -y synapse-mcp-api@latest)

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: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Cursor: ~/.cursor/config.json
   • Continue: ~/.continue/config.json
3. Validi il JSON — incolli la configurazione in https://jsonlint.com
4. Controlli i log del client per errori MCP:
   • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. Eseguia il server MCP manualmente per vedere gli errori di avvio:

   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

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 mk_, circa 40 caratteri
2. Testi direttamente:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

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:

   # Login to get JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Create new mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

Problema: npx non trovato

Sintomi

• Errore: "npx: command not found"
• Il server MCP non si avvia

Soluzioni

1. Installi Node.js 18+:
   • macOS: brew install node o scarichi da https://nodejs.org
   • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows: scarichi da https://nodejs.org
2. Riavvii il terminale dopo l'installazione
3. Verifichi: node --version && npx --version

Problema: SYNAPSE_URL 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à:

   curl https://synapse.schaefer.zone/health

2. Controlli il firewall aziendale — potrebbe bloccare l'HTTPS in uscita
3. Provi un URL alternativo:
   • Produzione: https://synapse.schaefer.zone
   • Server MCP: https://synapse-mcp.schaefer.zone
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:

   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest

2. Controlli i conflitti di porta — il server MCP usa la porta 13100 per impostazione predefinita
3. Pulisca la cache di npx:

   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx

4. Aggiorni all'ultima versione:

   npx -y synapse-mcp-api@latest --version

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 ?key= da qualche parte — passi all'autenticazione tramite header
2. Verifichi SYNAPSE_URL — 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. memory_recall, non memory.recall)
2. Verifichi gli argomenti — controlli lo schema di input dello strumento
3. Testi tramite API diretta:

   curl -X POST https://synapse.schaefer.zone/memory \
     -H "Authorization: Bearer mk_..." \
     -H "Content-Type: application/json" \
     -d '{"category":"fact","key":"test","content":"hello"}'

4. Controlli lo stato di Synapse:

   curl https://synapse.schaefer.zone/health

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 (npx -y synapse-mcp-api@latest --version)
   • 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