Dépannage

La plupart des échecs de configuration se répartissent en quatre catégories : la clé API n'atteint pas le serveur, le pont @maguyva/mcp ne démarre pas, le dépôt ne peut pas être résolu, ou le client ne peut pas se connecter du tout. Parcourez la section qui correspond à votre symptôme.

Chaque requête s'authentifie avec votre clé API, envoyée dans un en-tête Authorization: Bearer ou, si un client ne peut pas en définir un, dans un en-tête X-API-Key. Si les appels d'outils sont rejetés :

• 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.

Si votre client utilise le pont @maguyva/mcp, il lance un processus local qui se connecte au serveur distant de Maguyva :

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Si le serveur n'apparaît jamais dans votre client, ou apparaît puis se déconnecte immédiatement :

• 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.

• 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.

• 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.

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é.