# Dépannage MCP

Problèmes courants et solutions lors de l'intégration de MCP Synapse avec votre client
LLM.

## Liste de vérification de diagnostic rapide

1. ✅ Node.js 18+ installé ? (`node --version`)
2. ✅ La Mind Key commence par `mk_` ? (pas un JWT `eyJ...`)
3. ✅ L'API Synapse est accessible ? (`curl https://synapse.schaefer.zone/health`)
4. ✅ La Mind Key fonctionne ? (`curl -H "Authorization: Bearer mk_..." .../memory/recall`)
5. ✅ Le fichier de config est du JSON valide ? (pas de virgules finales, pas de commentaires)
6. ✅ Le client a-t-il été redémarré après le changement de config ?
7. ✅ Le serveur MCP démarre-t-il manuellement ? (`npx -y synapse-mcp-api@latest`)

## Problème : aucun outil n'apparaît dans le client

### Symptômes

- Claude Desktop / Cursor / Continue affiche 0 outils
- Pas d'icône 🔌 ou d'entrée « synapse » dans la liste des serveurs MCP

### Solutions

1. **Redémarrez le client complètement** — Cmd+Q sur macOS (pas juste fermer la fenêtre)
2. **Vérifiez l'emplacement du fichier de config** :
   - 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. **Validez le JSON** — collez la config dans <https://jsonlint.com>
4. **Consultez les logs client** pour les erreurs MCP :
   - Claude Desktop : `~/Library/Logs/Claude/mcp.log` (macOS)
   - Cursor : View → Output → MCP
5. **Exécutez le serveur MCP manuellement** pour voir les erreurs de démarrage :
   ```bash
   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
   ```

## Problème : erreur « Mind Key invalid »

### Symptômes

- Les outils apparaissent mais les appels échouent avec « 401 Unauthorized »
- Erreur : "Mind Key fehlt oder ungültig"

### Solutions

1. **Vérifiez le format de la Mind Key** — commence par `mk_`, ~40 caractères
2. **Testez directement** :
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **Vérifiez que la variable d'env est définie** — pour le transport stdio, la variable d'env doit être dans la config du serveur MCP, pas dans votre shell
4. **Obtenez une nouvelle Mind Key** :
   ```bash
   # Se connecter pour obtenir un JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Créer un nouveau mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
   ```

## Problème : npx introuvable

### Symptômes

- Erreur : "npx: command not found"
- Le serveur MCP ne démarre pas

### Solutions

1. **Installez Node.js 18+** :
   - macOS : `brew install node` ou téléchargez depuis <https://nodejs.org>
   - Linux : `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`
   - Windows : téléchargez depuis <https://nodejs.org>
2. **Redémarrez le terminal** après l'installation
3. **Vérifiez** : `node --version && npx --version`

## Problème : SYNAPSE_URL inaccessible

### Symptômes

- Le serveur MCP démarre mais les appels d'outils expirent
- Erreur : "fetch failed" ou "ECONNREFUSED"

### Solutions

1. **Testez la connectivité** :
   ```bash
   curl https://synapse.schaefer.zone/health
   ```
2. **Vérifiez le pare-feu d'entreprise** — peut bloquer le HTTPS sortant
3. **Essayez une URL alternative** :
   - Production : `https://synapse.schaefer.zone`
   - Serveur MCP : `https://synapse-mcp.schaefer.zone`
4. **Pour l'auto-hébergement** : assurez-vous que votre instance Synapse fonctionne et est accessible

## Problème : le serveur MCP plante

### Symptômes

- Le serveur MCP se ferme immédiatement après le démarrage
- Les logs client affichent « MCP server disconnected »

### Solutions

1. **Exécutez manuellement pour voir l'erreur** :
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **Vérifiez les conflits de port** — le serveur MCP utilise le port 13100 par défaut
3. **Nettoyez le cache npx** :
   ```bash
   npx clear-npx-cache
   # ou
   rm -rf ~/.npm/_npx
   ```
4. **Mettez à jour vers la dernière version** :
   ```bash
   npx -y synapse-mcp-api@latest --version
   ```

## Problème : les appels d'outils renvoient 429

### Symptômes

- Erreur : "Rate limit exceeded"

### Solutions

Cela ne devrait pas arriver avec MCP (utilise l'auth par en-tête, sans limite de
débit). Si c'est le cas :

1. **Vérifiez si vous utilisez `?key=` quelque part** — passez à l'auth par en-tête
2. **Vérifiez `SYNAPSE_URL`** — assurez-vous qu'elle pointe vers la bonne instance
3. **Contactez le support** si le problème persiste

## Problème : les outils apparaissent mais ne fonctionnent pas

### Symptômes

- Outils listés dans le client
- Appeler un outil renvoie une erreur ou aucun résultat

### Solutions

1. **Vérifiez le nom de l'outil** — doit être exact (ex. `memory_recall`, pas `memory.recall`)
2. **Vérifiez les arguments** — consultez le schéma d'entrée de l'outil
3. **Testez via API directe** :
   ```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. **Vérifiez la santé de Synapse** :
   ```bash
   curl https://synapse.schaefer.zone/health
   ```

## Obtenir de l'aide

Si aucune des solutions ci-dessus ne résout votre problème :

1. **Consultez les tickets existants** : <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. **Ouvrez un nouveau ticket** avec :
   - Version du serveur MCP (`npx -y synapse-mcp-api@latest --version`)
   - Nom et version du client
   - Système d'exploitation
   - Extraits de logs pertinents
   - Étapes pour reproduire

## Prochaines étapes

- [Configuration Claude Desktop](/docs/mcp/claude-desktop)
- [Configuration Claude Code](/docs/mcp/claude-code)
- [Erreurs API](/docs/api/errors)