# 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:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   # 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à**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Aggiorni all'ultima versione**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [Configurazione di Claude Code](/docs/mcp/claude-code)
- [Errori API](/docs/api/errors)