# Dépannage

Canonical source: https://maguyva.ai/fr/docs/troubleshooting

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Corrigez les échecs courants de configuration de Maguyva : problèmes de clé API, soucis avec le pont @maguyva/mcp, recherches de dépôt, et erreurs de connexion.

### Problèmes de clé API

- Vérifiez que votre clé commence par le préfixe mgv_.
- Vérifiez que vous avez remplacé le placeholder mgv_xxxx des exemples de config par votre vraie clé depuis app.maguyva.ai.
- Si votre config lit la clé depuis MAGUYVA_API_KEY, confirmez que la variable est définie dans l'environnement depuis lequel votre client se lance réellement. Les exports shell ajoutés à ~/.zshrc ou ~/.bashrc ne s'appliquent qu'après le rechargement du shell, et les applications GUI peuvent ne pas en hériter du tout. En cas de doute, écrivez la clé directement dans la config : dans l'en-tête Authorization d'une config distante native (Bearer suivi de votre clé), ou dans le bloc env d'une config utilisant le pont @maguyva/mcp.
- Assurez-vous que la clé n'a pas expiré ni été révoquée.

### Problèmes de pont @maguyva/mcp

- Vérifiez que npx est disponible dans votre PATH -- le pont a besoin d'une installation Node.js fonctionnelle. Lancez npx -y @maguyva/mcp --help dans un terminal pour confirmer qu'il peut démarrer.
- Vérifiez la syntaxe de la configuration MCP de votre client -- un fichier JSON malformé échoue silencieusement chez certains clients.
- Beaucoup de clients n'ont pas du tout besoin du pont. Claude Code utilise le plugin Maguyva (/plugin install maguyva@maguyva), et Cursor, VS Code, Devin Desktop et Zed se connectent au serveur distant nativement avec un en-tête Bearer (Zed via context_servers). Le pont sert aux clients qui ne peuvent pas envoyer cet en-tête depuis leur config, comme Claude Desktop, dont le claude_desktop_config.json ne lance que des serveurs locaux. Les connecteurs personnalisés de Claude Desktop peuvent envoyer un en-tête de requête authorization, mais les en-têtes de requête sont en bêta pour un nombre limité d'organisations.

### Dépôt introuvable

- Vérifiez que le dépôt est connecté et indexé dans app.maguyva.ai.
- Vérifiez le format : "owner/repo" cible la branche par défaut, "owner/repo:branch" cible une branche spécifique (par ex. "owner/repository:develop").
- Assurez-vous que votre compte a accès au dépôt.
- Utilisez repository_context(action="info", repository="...") pour vérifier la résolution du dépôt ; n’omettez le paramètre de dépôt que lorsque votre client MCP fournit une valeur par défaut pour la requête ou lorsque la clé permet d’accéder à un seul dépôt.

### Problèmes de connexion MCP

- Testez la connectivité à https://maguyva.tools/mcp depuis votre machine -- les proxys d'entreprise et pare-feux sont les coupables habituels.
- Vérifiez que votre jeton API est valide et non expiré.
- Revérifiez la config de votre client par rapport au Guide d'installation -- l'emplacement et la forme du fichier de config diffèrent selon le client.

### Vérifiez le correctif

Après toute modification, demandez à votre agent « Quels dépôts ai-je connectés ? » -- cela vérifie la connexion de bout en bout. Posez ensuite une vraie question sur votre dépôt ; vous devriez voir des réponses avec chemins de fichiers et numéros de ligne depuis votre dépôt connecté.