Troubleshooting
Choose the next action based on the message you see.
Start with the message shown. Do not reinstall all talents to fix a connection problem.
| What you see | What to check | Next action |
|---|---|---|
| Grace does not appear in your AI agent | Does the file match your chosen AI agent? | Repeat the connection steps, then reload MCP. With Copilot CLI, check .github/mcp.json, launch it from the repository root, and approve the folder as trusted. |
| Copilot CLI rejects the configuration | Is .github/mcp.json valid JSON? | Fix the JSON, then rerun the connection command: it stops without changing anything while the file is invalid. |
| You are asked to sign in | Is your session active? | Repeat the Authenticate and verify Grace step shown for your assistant, then authorize access in the browser. |
Sign-in reports invalid_scope | Does the message mention offline_access, openid, profile, or email? | Follow the sign-in recovery steps below. |
| Copilot CLI does not finish the interactive connection | Does /mcp show grace still say authentication is required? | Follow Copilot CLI recovery before using another access method. |
| Access is denied | Right account, right organization, organization approved? | See permissions. |
| Preparation rejects an empty selection | Has the AI agent designated any talents? | Ask it to choose the relevant identifiers from the provided directory. |
| Dependencies are missing | Does the project diagnostic show missing prerequisites? | Ask someone authorized to complete the selection before preparing again. |
| Preparation flags a talent without review rules | Is it an absence of rules, or a reported error? | Keep applying its conventions; the agent still consults the global plan without requesting details for talents it confirms have no rules. Report read or format errors to your team; do not conclude that the work is compliant. |
| A page does not load | Does the problem persist after refreshing? | Try again, then share the message with your team. |
Sign-in rejected with invalid_scope
This message means the requested permissions were refused. A localhost or
127.0.0.1 return address is normal for an application installed on your computer:
it hands control back to the application after signing in to Grace. Do not replace
it with Grace's address.
- Sign in from your application and authorize Grace in the browser.
- If the refusal persists, follow the application-specific reset instructions below. Signing out alone may preserve the old OAuth registration.
- Verify in the application that Grace is connected and its tools are available.
Configuration files alone do not prove that you are connected. Grace cannot inspect your computer's OAuth cache: an old registration is a possible cause, not an automatic diagnosis.
Choose your application: Copilot CLI, Copilot in VS Code, Junie, or Claude Code. For other applications, repeat Authenticate and verify Grace in the connection guide.
Copilot CLI
From the project root, launch copilot, approve folder trust if prompted, then
enter this command inside the Copilot session, not in your system terminal:
/mcp auth graceComplete authorization in your browser, then check:
/mcp show graceExpected result: Grace is connected and its tools are available. /mcp auth grace
restarts authentication; it does not guarantee that an old OAuth client
registration was cleared. Copilot CLI commands.
Last resort: move the local OAuth cache aside
Quit every Copilot CLI session before continuing. This moves the entire OAuth directory: other MCP servers may also require you to sign in again. The backup contains secrets. Keep it on your computer, outside the repository, and do not send it to anyone.
GitHub documents mcp-oauth-config as fallback storage for tokens, registrations,
and connection proofs when the system keychain is unavailable. Moving that
directory does not reset the keychain and therefore cannot guarantee a fix.
If the directory is absent or the error persists, stop and
ask for help.
Copilot configuration reference.
Use the same configuration directory as Copilot, in this order: --config-dir
if you use it, otherwise COPILOT_HOME, otherwise ~/.copilot. If the option
is relative, provide its absolute path from the directory where you launch
Copilot. Do not substitute $USER for the home directory: it is a username.
These commands do not open any secret files.
macOS or Linux — in the system terminal: set grace_config_override only
if you use --config-dir.
(
grace_config_override=''
grace_config_dir=${grace_config_override:-${COPILOT_HOME:-"$HOME/.copilot"}}
case "$grace_config_dir" in
/*) ;;
*) printf '%s\n' 'Stop: supply an absolute path.' >&2; exit 1 ;;
esac
if [ -L "$grace_config_dir" ] || [ ! -d "$grace_config_dir" ]; then
printf '%s\n' 'Stop: configuration directory is absent, invalid, or a symbolic link.' >&2; exit 1
fi
grace_cache="$grace_config_dir/mcp-oauth-config"
if [ -L "$grace_cache" ]; then
printf '%s\n' 'Stop: the cache is a symbolic link.' >&2; exit 1
fi
if [ ! -e "$grace_cache" ]; then
printf '%s\n' 'Cache absent: no change. The keychain may be in use.'; exit 0
fi
if [ ! -d "$grace_cache" ]; then
printf '%s\n' 'Stop: the cache exists but is not a directory.' >&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' 'Stop: backup already exists or cannot be created. Nothing moved.' >&2; exit 1
}
mv "$grace_cache" "$grace_backup/mcp-oauth-config" || exit 1
printf 'Backup: %s\n' "$grace_backup"
)Windows — in PowerShell: set $graceConfigOverride only if you use
--config-dir. Do not use the interactive Copilot terminal.
& {
$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 'Stop: supply an absolute path.' }
$graceDir = Get-Item -LiteralPath $graceConfigDir -Force -ErrorAction Stop
if (-not $graceDir.PSIsContainer -or ($graceDir.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Stop: configuration directory is invalid or linked.' }
$graceCache = Join-Path $graceConfigDir 'mcp-oauth-config'
$graceItem = Get-Item -LiteralPath $graceCache -Force -ErrorAction SilentlyContinue
if ($null -eq $graceItem) { Write-Host 'Cache absent: no change. The keychain may be in use.'; return }
if (-not $graceItem.PSIsContainer -or ($graceItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Stop: the cache is invalid or linked.' }
$graceBackup = Join-Path $graceConfigDir ('mcp-oauth-backup-' + (Get-Date -Format 'yyyyMMdd-HHmmss'))
if (Test-Path -LiteralPath $graceBackup) { throw 'Stop: backup already exists. Nothing moved.' }
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 "Backup: $graceBackup"
}Keep the displayed backup path. Restart Copilot with the same options and
environment variables, then repeat /mcp auth grace and /mcp show grace.
If the connection still fails, do not keep deleting files: share the error
message and Copilot version with your team.
To restore, quit Copilot again and replace the example path with the one displayed earlier. If Copilot has created a new cache, these commands stop: back up that new directory first using the preceding procedure, then restore the original backup. Restoring reinstates the previous local state; it does not refresh tokens or modify the keychain.
(
grace_backup='/absolute/path/mcp-oauth-backup-YYYYMMDD-HHMMSS'
case "$grace_backup" in /*) ;; *) printf '%s\n' 'Stop: an absolute path is required.' >&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' 'Stop: backup is absent, invalid, or a symbolic link.' >&2; exit 1
fi
if [ -e "$grace_cache" ] || [ -L "$grace_cache" ]; then
printf '%s\n' 'Stop: a cache already exists. Back it up before restoring.' >&2; exit 1
fi
mv "$grace_backup/mcp-oauth-config" "$grace_cache" || exit 1
printf '%s\n' 'Previous cache restored.'
)& {
$graceBackup = 'C:\absolute\path\mcp-oauth-backup-YYYYMMDD-HHMMSS'
if (-not [IO.Path]::IsPathRooted($graceBackup) -or $graceBackup -match '^[A-Za-z]:(?![\\/])|^\\(?!\\)') { throw 'Stop: an absolute path is required.' }
$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 'Stop: backup is invalid or linked.' }
$graceCache = Join-Path (Split-Path -Parent $graceBackup) 'mcp-oauth-config'
if (Get-Item -LiteralPath $graceCache -Force -ErrorAction SilentlyContinue) { throw 'Stop: a cache already exists. Back it up before restoring.' }
Move-Item -LiteralPath $graceSource.FullName -Destination $graceCache -ErrorAction Stop
Write-Host 'Previous cache restored.'
}Copilot in VS Code
- Open the command palette and run MCP: List Servers. Select Grace, start it, and complete browser authorization.
- If
invalid_scopeappears again, run Authentication: Remove Dynamic Authentication Providers in the palette and select only Grace. Then reconnect its MCP server. - Confirm Grace is running in MCP: List Servers and its tools are available in Copilot Chat. VS Code instructions.
Junie
Junie CLI in interactive mode: launch junie from your project and enter
/mcp. Select Grace → Authorize, finish authorization in your browser,
and verify the Active status. In an ACP client, /mcp is a read-only list:
use Junie's interactive mode for this flow.
Junie CLI instructions.
Junie plugin in a JetBrains IDE: open Settings → Tools → Junie → MCP Settings, then inspect Grace's Status column and any associated error. Junie plugin settings.
These flows do not guarantee that an old OAuth registration is cleared. If access is still refused, share the error and the Junie and IDE versions, specifying CLI, Junie plugin, or AI Chat. No cache purge command is provided here.
Claude Code
First retry the authentication shown in your project's connection guide.
If the refusal persists, remove Grace with claude mcp remove grace, then
add it again using the connection guide.
This also clears the saved authentication. Confirm that Grace is connected
and its tools are available.
Claude Code instructions.
If your application has no reset option described here, ask for help with its exact version instead of deleting other local data.
Ask for help
Include the action you tried, the exact message, the project name, and when the error happened. Add a cropped screenshot if it helps. Redact private data, keys, and tokens. Do not share your password, the complete browser OAuth return URL, or the contents of the cache or its backup.