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 mcp-remote 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.

Problèmes de clé API#

Chaque requête s'authentifie avec votre clé API, envoyée dans un en-tête Authorization: Bearer. 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 les hériter du tout. En cas de doute, placez la clé dans le bloc env de la config.
• Assurez-vous que la clé n'a pas expiré ni été révoquée.

Problèmes de pont mcp-remote#

La plupart des configs client documentées lancent un processus de pont local qui transmet le trafic MCP stdio vers le serveur distant :

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

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 mcp-remote --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, Windsurf et Zed se connectent au serveur distant nativement avec un en-tête Bearer (Zed via context_servers). Le pont ne sert qu'aux clients sans support natif des en-têtes distants, comme les connecteurs OAuth-only de Claude Desktop.

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