Dépannage
Choisir la prochaine action à partir du message que vous voyez.
Commencez par le message affiché. Ne réinstallez pas tous les talents pour corriger un problème de connexion.
| Ce que vous observez | À vérifier | Prochaine action |
|---|---|---|
| Grace n’apparaît pas dans l’agent IA | Le fichier correspond-il à l’agent IA choisi ? | Reprenez la connexion, puis rechargez MCP. Avec Copilot CLI, vérifiez .github/mcp.json, lancez-le à la racine du dépôt et approuvez la confiance du dossier. |
| Copilot CLI refuse la configuration | .github/mcp.json est-il un JSON valide ? | Corrigez le JSON, puis relancez la commande de branchement : elle s’arrête sans rien modifier tant que le fichier est invalide. |
| Une connexion est demandée | Votre session est-elle active ? | Reprenez l’étape Authentifier et vérifier Grace affichée pour votre assistant, puis autorisez l’accès dans le navigateur. |
La connexion affiche invalid_scope | Le message cite-t-il offline_access, openid, profile ou email ? | Suivez la reprise de connexion ci-dessous. |
| Copilot CLI ne termine pas la connexion interactive | /mcp show grace indique-t-il toujours une authentification requise ? | Suivez la reprise Copilot CLI avant d’utiliser un autre mode d’accès. |
| L’accès est refusé | Bon compte, bonne organisation, organisation approuvée ? | Consultez les permissions. |
| La préparation refuse une sélection vide | L’agent IA a-t-il désigné des talents ? | Faites-lui choisir les identifiants concernés dans le répertoire fourni. |
| Des dépendances manquent | Le diagnostic du projet indique-t-il des prérequis ? | Faites compléter la sélection avant de relancer la préparation. |
| La préparation signale un talent sans règles de revue | S’agit-il d’une absence de règles ou d’une erreur signalée ? | Conservez ses conventions ; l’agent consulte toujours le plan global, sans demander le détail des talents qu’il confirme sans règles. Signalez les erreurs de lecture ou de format à votre équipe ; ne concluez pas à la conformité. |
| Une page ne charge pas | Le problème se reproduit-il après rechargement ? | Réessayez, puis transmettez le message à votre équipe. |
Connexion refusée avec invalid_scope
Le message indique un refus des permissions demandées. Une adresse de retour
localhost ou 127.0.0.1 est normale pour un outil installé sur votre ordinateur :
elle lui rend la main après la connexion à Grace. Ne la remplacez pas par l’adresse de Grace.
- Authentifiez-vous depuis votre outil et autorisez Grace dans le navigateur.
- Si le refus persiste, suivez la réinitialisation propre à cet outil ci-dessous. Une simple déconnexion peut conserver l’ancien enregistrement OAuth.
- Vérifiez dans l’outil que Grace est connecté et que ses outils sont disponibles.
La présence des fichiers de configuration ne prouve pas une connexion. Grace ne peut pas inspecter le cache OAuth de votre ordinateur : un ancien enregistrement est une cause possible, pas un diagnostic automatique.
Choisissez votre outil : Copilot CLI, Copilot dans VS Code, Junie ou Claude Code. Pour un autre outil, reprenez Authentifier et vérifier Grace dans le guide de connexion.
Copilot CLI
À la racine du projet, lancez copilot, acceptez la confiance du dossier si elle est demandée,
puis saisissez dans la session Copilot, pas dans le terminal système :
/mcp auth graceTerminez l’autorisation dans le navigateur, puis contrôlez :
/mcp show graceRésultat attendu : Grace est connecté et ses outils sont disponibles. /mcp auth grace
relance l’authentification ; cette commande ne garantit pas l’effacement de l’ancien client
OAuth. Commandes Copilot CLI.
Dernier recours : mettre de côté le cache OAuth local
Quittez toutes les sessions Copilot CLI avant de continuer. Cette manipulation déplace le dossier OAuth entier : les autres serveurs MCP peuvent aussi demander une reconnexion. La sauvegarde contient des secrets : gardez-la sur votre ordinateur, hors du dépôt, et ne l’envoyez à personne.
GitHub documente mcp-oauth-config comme stockage de secours des jetons, de l’enregistrement
et de la preuve de connexion quand le trousseau système est indisponible. Déplacer ce dossier
ne réinitialise pas le trousseau et ne garantit donc pas une réparation. Si le dossier est
absent ou si l’erreur persiste, arrêtez cette procédure et demandez de l’aide.
Référence du dossier Copilot.
Utilisez le même dossier de configuration que Copilot, dans cet ordre : option --config-dir
si vous l’utilisez, sinon COPILOT_HOME, sinon ~/.copilot. Si l’option est relative, reportez
son chemin absolu depuis le dossier où vous lancez Copilot. Ne remplacez pas le dossier personnel
par $USER, qui est un nom d’utilisateur. Les commandes ci-dessous n’ouvrent aucun fichier secret.
macOS ou Linux — dans le terminal système : renseignez grace_config_override seulement
si vous utilisez --config-dir.
(
grace_config_override=''
grace_config_dir=${grace_config_override:-${COPILOT_HOME:-"$HOME/.copilot"}}
case "$grace_config_dir" in
/*) ;;
*) printf '%s\n' 'Arrêt : indiquez un chemin absolu.' >&2; exit 1 ;;
esac
if [ -L "$grace_config_dir" ] || [ ! -d "$grace_config_dir" ]; then
printf '%s\n' 'Arrêt : dossier de configuration absent, invalide ou symbolique.' >&2; exit 1
fi
grace_cache="$grace_config_dir/mcp-oauth-config"
if [ -L "$grace_cache" ]; then
printf '%s\n' 'Arrêt : le cache est un lien symbolique.' >&2; exit 1
fi
if [ ! -e "$grace_cache" ]; then
printf '%s\n' 'Cache absent : aucun changement. Le trousseau peut être utilisé.'; exit 0
fi
if [ ! -d "$grace_cache" ]; then
printf '%s\n' 'Arrêt : le cache existe mais ne désigne pas un dossier.' >&2; exit 1
fi
grace_backup="$grace_config_dir/mcp-oauth-backup-$(date +%Y%m%d-%H%M%S)"
(umask 077; mkdir "$grace_backup") || {
printf '%s\n' 'Arrêt : sauvegarde existante ou impossible à créer. Rien déplacé.' >&2; exit 1
}
mv "$grace_cache" "$grace_backup/mcp-oauth-config" || exit 1
printf 'Sauvegarde : %s\n' "$grace_backup"
)Windows — dans PowerShell : renseignez $graceConfigOverride seulement si vous utilisez
--config-dir. N’utilisez pas le terminal interactif de Copilot.
& {
$graceConfigOverride = ''
$graceConfigDir = if ($graceConfigOverride) { $graceConfigOverride } elseif ($env:COPILOT_HOME) { $env:COPILOT_HOME } else { Join-Path $HOME '.copilot' }
if (-not [IO.Path]::IsPathRooted($graceConfigDir) -or $graceConfigDir -match '^[A-Za-z]:(?![\\/])|^\\(?!\\)') { throw 'Arrêt : indiquez un chemin absolu.' }
$graceDir = Get-Item -LiteralPath $graceConfigDir -Force -ErrorAction Stop
if (-not $graceDir.PSIsContainer -or ($graceDir.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Arrêt : dossier de configuration invalide ou lié.' }
$graceCache = Join-Path $graceConfigDir 'mcp-oauth-config'
$graceItem = Get-Item -LiteralPath $graceCache -Force -ErrorAction SilentlyContinue
if ($null -eq $graceItem) { Write-Host 'Cache absent : aucun changement. Le trousseau peut être utilisé.'; return }
if (-not $graceItem.PSIsContainer -or ($graceItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Arrêt : le cache est invalide ou lié.' }
$graceBackup = Join-Path $graceConfigDir ('mcp-oauth-backup-' + (Get-Date -Format 'yyyyMMdd-HHmmss'))
if (Test-Path -LiteralPath $graceBackup) { throw 'Arrêt : sauvegarde déjà présente. Rien déplacé.' }
New-Item -ItemType Directory -Path $graceBackup -ErrorAction Stop | Out-Null
Move-Item -LiteralPath $graceCache -Destination (Join-Path $graceBackup 'mcp-oauth-config') -ErrorAction Stop
Write-Host "Sauvegarde : $graceBackup"
}Conservez le chemin de sauvegarde affiché. Relancez Copilot avec les mêmes options et variables,
puis recommencez /mcp auth grace et /mcp show grace. Si la connexion échoue encore, ne
multipliez pas les effacements : transmettez le message et la version de Copilot à votre équipe.
Pour restaurer, quittez de nouveau Copilot. Remplacez le chemin d’exemple par celui affiché. Si Copilot a recréé un cache, les commandes s’arrêtent : sauvegardez d’abord ce nouveau dossier avec la procédure précédente, puis restaurez la sauvegarde initiale. La restauration remet l’ancien état local ; elle ne renouvelle pas les jetons et ne modifie pas le trousseau.
(
grace_backup='/chemin/absolu/mcp-oauth-backup-AAAAMMJJ-HHMMSS'
case "$grace_backup" in /*) ;; *) printf '%s\n' 'Arrêt : chemin absolu requis.' >&2; exit 1 ;; esac
grace_cache="$(dirname "$grace_backup")/mcp-oauth-config"
if [ -L "$grace_backup" ] || [ -L "$grace_backup/mcp-oauth-config" ] || [ ! -d "$grace_backup/mcp-oauth-config" ]; then
printf '%s\n' 'Arrêt : sauvegarde absente, invalide ou symbolique.' >&2; exit 1
fi
if [ -e "$grace_cache" ] || [ -L "$grace_cache" ]; then
printf '%s\n' 'Arrêt : un cache existe déjà. Sauvegardez-le avant de restaurer.' >&2; exit 1
fi
mv "$grace_backup/mcp-oauth-config" "$grace_cache" || exit 1
printf '%s\n' 'Ancien cache restauré.'
)& {
$graceBackup = 'C:\chemin\mcp-oauth-backup-AAAAMMJJ-HHMMSS'
if (-not [IO.Path]::IsPathRooted($graceBackup) -or $graceBackup -match '^[A-Za-z]:(?![\\/])|^\\(?!\\)') { throw 'Arrêt : chemin absolu requis.' }
$graceDir = Get-Item -LiteralPath $graceBackup -Force -ErrorAction Stop
$graceSource = Get-Item -LiteralPath (Join-Path $graceBackup 'mcp-oauth-config') -Force -ErrorAction Stop
if (-not $graceDir.PSIsContainer -or -not $graceSource.PSIsContainer -or ($graceDir.Attributes -band [IO.FileAttributes]::ReparsePoint) -or ($graceSource.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Arrêt : sauvegarde invalide ou liée.' }
$graceCache = Join-Path (Split-Path -Parent $graceBackup) 'mcp-oauth-config'
if (Get-Item -LiteralPath $graceCache -Force -ErrorAction SilentlyContinue) { throw 'Arrêt : un cache existe déjà. Sauvegardez-le avant de restaurer.' }
Move-Item -LiteralPath $graceSource.FullName -Destination $graceCache -ErrorAction Stop
Write-Host 'Ancien cache restauré.'
}Copilot dans VS Code
- Ouvrez la palette de commandes et lancez MCP: List Servers. Sélectionnez Grace, démarrez-le et terminez l’autorisation dans le navigateur.
- Si
invalid_scoperevient, lancez Authentication: Remove Dynamic Authentication Providers dans la palette, puis sélectionnez uniquement Grace. Relancez ensuite sa connexion MCP. - Vérifiez que Grace est démarré dans MCP: List Servers et que ses outils sont disponibles dans Copilot Chat. Procédure VS Code.
Junie
Junie CLI, en mode interactif : lancez junie depuis votre projet, puis saisissez /mcp.
Sélectionnez Grace → Authorize, terminez l’autorisation dans le navigateur et vérifiez
le statut Active. Dans un client ACP, /mcp est une liste en lecture seule : utilisez
le mode interactif de Junie pour ce parcours.
Procédure Junie CLI.
Plugin Junie dans un IDE JetBrains : ouvrez Settings → Tools → Junie → MCP Settings, puis consultez la colonne Status de Grace et le message associé à une erreur. Réglages du plugin Junie.
Ces parcours ne garantissent pas l’effacement d’un ancien enregistrement OAuth. Si le refus persiste, transmettez le message et les versions de Junie et de l’IDE, en précisant CLI, plugin Junie ou AI Chat. Aucune commande de purge de leur cache n’est proposée ici.
Claude Code
Reprenez d’abord l’authentification indiquée dans le guide de connexion du projet. Si le refus
persiste, retirez Grace avec claude mcp remove grace, puis ajoutez-le à nouveau depuis
le guide de connexion. Cette suppression efface aussi
l’authentification enregistrée. Vérifiez ensuite que Grace est connecté et ses outils disponibles.
Procédure Claude Code.
Si votre outil ne propose pas la réinitialisation décrite, demandez de l’aide avec sa version exacte plutôt que de supprimer d’autres données locales.
Demander de l’aide
Indiquez l’action tentée, le message exact, le nom du projet et le moment de l’erreur. Ajoutez une capture cadrée si elle aide à comprendre. Masquez les données privées, les clés et les jetons. Ne transmettez ni mot de passe, ni adresse OAuth complète du navigateur, ni contenu du cache ou de sa sauvegarde.