{"title":"Risoluzione dei problemi MCP","slug":"troubleshooting","category":"mcp","summary":"Risolve i problemi comuni di integrazione MCP — server che non si avvia, strumenti che non appaiono, errori di autenticazione.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":638,"read_minutes":3,"llm_context":"Common issues:\n1. Node.js < 18 → upgrade to 18+\n2. Mind Key invalid → check format (mk_...), get fresh via POST /minds\n3. npx not found → install Node.js\n4. Tools not appearing → restart client, check config JSON validity\n5. SYNAPSE_URL unreachable → curl /health to verify\n6. MCP server crashes → check logs, run npx manually to see error\nDebug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr\nLogs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/\n","lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Risoluzione dei problemi MCP\n\nProblemi comuni e soluzioni nell'integrazione di Synapse MCP con il proprio\nclient LLM.\n\n## Lista di controllo diagnostica rapida\n\n1. ✅ Node.js 18+ installato? (`node --version`)\n2. ✅ La Mind Key inizia con `mk_`? (non JWT `eyJ...`)\n3. ✅ L'API di Synapse è raggiungibile? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ La Mind Key funziona? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Il file di configurazione è JSON valido? (nessuna virgola finale, nessun commento)\n6. ✅ Il client è stato riavviato dopo la modifica della configurazione?\n7. ✅ Il server MCP si avvia manualmente? (`npx -y synapse-mcp-api@latest`)\n\n## Problema: nessuno strumento appare nel client\n\n### Sintomi\n\n- Claude Desktop / Cursor / Continue mostra 0 strumenti\n- Nessuna icona 🔌 o voce \"synapse\" nell'elenco dei server MCP\n\n### Soluzioni\n\n1. **Riavvi completamente il client** — Cmd+Q su macOS (non solo chiuda la finestra)\n2. **Controlli la posizione del file di configurazione**:\n - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Claude Desktop Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - Cursor: `~/.cursor/config.json`\n - Continue: `~/.continue/config.json`\n3. **Validi il JSON** — incolli la configurazione in \n4. **Controlli i log del client** per errori MCP:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **Eseguia il server MCP manualmente** per vedere gli errori di avvio:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Problema: errore \"Mind Key invalid\"\n\n### Sintomi\n\n- Gli strumenti appaiono ma le chiamate falliscono con \"401 Unauthorized\"\n- Errore: \"Mind Key fehlt oder ungültig\"\n\n### Soluzioni\n\n1. **Verifichi il formato della Mind Key** — inizia con `mk_`, circa 40 caratteri\n2. **Testi direttamente**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **Controlli che la variabile d'ambiente sia impostata** — per il trasporto\n stdio, la variabile deve trovarsi nella configurazione del server MCP, non\n nella shell\n4. **Ottenga una nuova Mind Key**:\n ```bash\n # Login to get JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Create new mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## Problema: npx non trovato\n\n### Sintomi\n\n- Errore: \"npx: command not found\"\n- Il server MCP non si avvia\n\n### Soluzioni\n\n1. **Installi Node.js 18+**:\n - macOS: `brew install node` o scarichi da \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: scarichi da \n2. **Riavvii il terminale** dopo l'installazione\n3. **Verifichi**: `node --version && npx --version`\n\n## Problema: SYNAPSE_URL non raggiungibile\n\n### Sintomi\n\n- Il server MCP si avvia ma le chiamate agli strumenti vanno in timeout\n- Errore: \"fetch failed\" o \"ECONNREFUSED\"\n\n### Soluzioni\n\n1. **Testi la connettività**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Controlli il firewall aziendale** — potrebbe bloccare l'HTTPS in uscita\n3. **Provi un URL alternativo**:\n - Produzione: `https://synapse.schaefer.zone`\n - Server MCP: `https://synapse-mcp.schaefer.zone`\n4. **Per istanze self-hosted**: si assicuri che la propria istanza Synapse sia in esecuzione e accessibile\n\n## Problema: il server MCP si blocca\n\n### Sintomi\n\n- Il server MCP esce immediatamente dopo l'avvio\n- I log del client mostrano \"MCP server disconnected\"\n\n### Soluzioni\n\n1. **Lo esegua manualmente per vedere l'errore**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Controlli i conflitti di porta** — il server MCP usa la porta 13100 per impostazione predefinita\n3. **Pulisca la cache di npx**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **Aggiorni all'ultima versione**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Problema: le chiamate agli strumenti restituiscono 429\n\n### Sintomi\n\n- Errore: \"Rate limit exceeded\"\n\n### Soluzioni\n\nNon dovrebbe succedere con MCP (usa l'autenticazione tramite header, nessun\nrate limit). Se succede:\n\n1. **Controlli se sta usando `?key=` da qualche parte** — passi all'autenticazione tramite header\n2. **Verifichi `SYNAPSE_URL`** — si assicuri che punti all'istanza corretta\n3. **Contatti l'assistenza** se il problema persiste\n\n## Problema: gli strumenti appaiono ma non funzionano\n\n### Sintomi\n\n- Strumenti elencati nel client\n- La chiamata a uno strumento restituisce un errore o nessun risultato\n\n### Soluzioni\n\n1. **Controlli il nome dello strumento** — deve essere esatto (es. `memory_recall`, non `memory.recall`)\n2. **Verifichi gli argomenti** — controlli lo schema di input dello strumento\n3. **Testi tramite API diretta**:\n ```bash\n curl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer mk_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\":\"fact\",\"key\":\"test\",\"content\":\"hello\"}'\n ```\n4. **Controlli lo stato di Synapse**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Ottenere assistenza\n\nSe nessuna delle soluzioni precedenti risolve il problema:\n\n1. **Controlli le issue esistenti**: \n2. **Apra una nuova issue** con:\n - Versione del server MCP (`npx -y synapse-mcp-api@latest --version`)\n - Nome e versione del client\n - Sistema operativo\n - Estratti di log rilevanti\n - Passaggi per riprodurre il problema\n\n## Prossimi passi\n\n- [Configurazione di Claude Desktop](/docs/mcp/claude-desktop)\n- [Configurazione di Claude Code](/docs/mcp/claude-code)\n- [Errori API](/docs/api/errors)\n","content_html":"

Risoluzione dei problemi MCP

\n

Problemi comuni e soluzioni nell'integrazione di Synapse MCP con il proprio\nclient LLM.

\n

Lista di controllo diagnostica rapida

\n
    \n
  1. ✅ Node.js 18+ installato? (node --version)
    2. \n
  2. ✅ La Mind Key inizia con mk_? (non JWT eyJ...)
    3. \n
  3. ✅ L'API di Synapse è raggiungibile? (curl https://synapse.schaefer.zone/health)
    4. \n
  4. ✅ La Mind Key funziona? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
    5. \n
  5. ✅ Il file di configurazione è JSON valido? (nessuna virgola finale, nessun commento)
    6. \n
  6. ✅ Il client è stato riavviato dopo la modifica della configurazione?
    7. \n
  7. ✅ Il server MCP si avvia manualmente? (npx -y synapse-mcp-api@latest)
    8. \n
\n

Problema: nessuno strumento appare nel client

\n

Sintomi

\n
    \n
  • Claude Desktop / Cursor / Continue mostra 0 strumenti
    • \n
  • Nessuna icona 🔌 o voce "synapse" nell'elenco dei server MCP
    • \n
\n

Soluzioni

\n
    \n
  1. Riavvi completamente il client — Cmd+Q su macOS (non solo chiuda la finestra)
    2. \n
  2. Controlli la posizione del file di configurazione:
      \n
    • Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
      • \n
    • Claude Desktop Windows: %APPDATA%\\Claude\\claude_desktop_config.json
      • \n
    • Cursor: ~/.cursor/config.json
      • \n
    • Continue: ~/.continue/config.json
      • \n
    \n
    3. \n
  3. Validi il JSON — incolli la configurazione in https://jsonlint.com
    4. \n
  4. Controlli i log del client per errori MCP:
      \n
    • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
      • \n
    • Cursor: View → Output → MCP
      • \n
    \n
    5. \n
  5. Eseguia il server MCP manualmente per vedere gli errori di avvio:
    SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
    6. \n
\n

Problema: errore "Mind Key invalid"

\n

Sintomi

\n
    \n
  • Gli strumenti appaiono ma le chiamate falliscono con "401 Unauthorized"
    • \n
  • Errore: "Mind Key fehlt oder ungültig"
    • \n
\n

Soluzioni

\n
    \n
  1. Verifichi il formato della Mind Key — inizia con mk_, circa 40 caratteri
    2. \n
  2. Testi direttamente:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  3. Controlli che la variabile d'ambiente sia impostata — per il trasporto\nstdio, la variabile deve trovarsi nella configurazione del server MCP, non\nnella shell
    4. \n
  4. Ottenga una nuova Mind Key:
    # Login to get JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# Create new mind\ncurl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
    5. \n
\n

Problema: npx non trovato

\n

Sintomi

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

Soluzioni

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

Problema: SYNAPSE_URL non raggiungibile

\n

Sintomi

\n
    \n
  • Il server MCP si avvia ma le chiamate agli strumenti vanno in timeout
    • \n
  • Errore: "fetch failed" o "ECONNREFUSED"
    • \n
\n

Soluzioni

\n
    \n
  1. Testi la connettività:
    curl https://synapse.schaefer.zone/health
    2. \n
  2. Controlli il firewall aziendale — potrebbe bloccare l'HTTPS in uscita
    3. \n
  3. Provi un URL alternativo:
      \n
    • Produzione: https://synapse.schaefer.zone
      • \n
    • Server MCP: https://synapse-mcp.schaefer.zone
      • \n
    \n
    4. \n
  4. Per istanze self-hosted: si assicuri che la propria istanza Synapse sia in esecuzione e accessibile
    5. \n
\n

Problema: il server MCP si blocca

\n

Sintomi

\n
    \n
  • Il server MCP esce immediatamente dopo l'avvio
    • \n
  • I log del client mostrano "MCP server disconnected"
    • \n
\n

Soluzioni

\n
    \n
  1. Lo esegua manualmente per vedere l'errore:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Controlli i conflitti di porta — il server MCP usa la porta 13100 per impostazione predefinita
    3. \n
  3. Pulisca la cache di npx:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. Aggiorni all'ultima versione:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

Problema: le chiamate agli strumenti restituiscono 429

\n

Sintomi

\n
    \n
  • Errore: "Rate limit exceeded"
    • \n
\n

Soluzioni

\n

Non dovrebbe succedere con MCP (usa l'autenticazione tramite header, nessun\nrate limit). Se succede:

\n
    \n
  1. Controlli se sta usando ?key= da qualche parte — passi all'autenticazione tramite header
    2. \n
  2. Verifichi SYNAPSE_URL — si assicuri che punti all'istanza corretta
    3. \n
  3. Contatti l'assistenza se il problema persiste
    4. \n
\n

Problema: gli strumenti appaiono ma non funzionano

\n

Sintomi

\n
    \n
  • Strumenti elencati nel client
    • \n
  • La chiamata a uno strumento restituisce un errore o nessun risultato
    • \n
\n

Soluzioni

\n
    \n
  1. Controlli il nome dello strumento — deve essere esatto (es. memory_recall, non memory.recall)
    2. \n
  2. Verifichi gli argomenti — controlli lo schema di input dello strumento
    3. \n
  3. Testi tramite API diretta:
    curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer mk_..." \\\n  -H "Content-Type: application/json" \\\n  -d '{"category":"fact","key":"test","content":"hello"}'
    4. \n
  4. Controlli lo stato di Synapse:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Ottenere assistenza

\n

Se nessuna delle soluzioni precedenti risolve il problema:

\n
    \n
  1. Controlli le issue esistenti: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
    2. \n
  2. Apra una nuova issue con:
      \n
    • Versione del server MCP (npx -y synapse-mcp-api@latest --version)
      • \n
    • Nome e versione del client
      • \n
    • Sistema operativo
      • \n
    • Estratti di log rilevanti
      • \n
    • Passaggi per riprodurre il problema
      • \n
    \n
    3. \n
\n

Prossimi passi

\n\n","urls":{"html":"/docs/mcp/troubleshooting","text":"/docs/mcp/troubleshooting?format=text","json":"/docs/mcp/troubleshooting?format=json","llm":"/docs/mcp/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}