| name | mcp-token-expired |
| description | What to do when a native claude.ai MCP connector (Slack, Calendar, Notion, Google Drive, Gmail — mcp__claude_ai_* or an equivalent connector) returns an authentication error (invalid_auth_token, not_authed, token_expired, auth_failed…): visual alert, guided reconnection, fallback without blocking. Load it AS SOON AS such an error appears. |
| version | 1.0.0 |
Expired MCP token — visual alert + reconnection
As soon as a tool of a native claude.ai connector (Slack, Gmail, Calendar, Notion, Google Drive)
returns an authentication error (invalid_auth_token, not_authed, token_expired,
auth_failed…), run the procedure below.
⚠️ Exception: a connector that is unavailable by design
Some connectors may be unavailable by design — not because of an expired token, but because an
org policy or a provider restriction blocks them for this account. This is not a token to
refresh: do NOT show the alert below and do NOT run the reconnection. Treat the connector as an
unavailable source by default: use the fallback, briefly note " unavailable
(org/provider restriction)", and continue without blocking.
Procedure (real authentication error)
-
Immediately show this alert block (as-is, emojis included):
🚨🚨🚨 MCP TOKEN EXPIRED 🚨🚨🚨
⚠️ Connector: <name> (mcp__claude_ai_<...>)
⚠️ Error: <error code>
🔌 Impact: <what becomes unavailable> → fallback used.
👉 TO RECONNECT: type /mcp → select <connector> → Re-authenticate
(browser OAuth flow, ~20 s, and everything works again)
🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨
-
Push /mcp in the terminal as the first attempt. If the token is simply expired and
/mcp offers a re-authentication, this is the fastest path.
-
If /mcp shows connected but the call still fails with invalid_auth_token
→ the downstream token is stale despite the "connected" status; a /mcp will not
regenerate it (it believes it is already connected). Real fix: Disconnect then Reconnect
the connector on claude.ai (open "https://claude.ai/settings/connectors"). On reconnect,
explicitly authorize the right account / workspace (the SSO or identity this connector
expects) — otherwise the connector stays "connected" but on an invalid token.
-
Continue with the fallback without blocking (e.g. an alternative MCP connector, or a
channel/timestamp search for Slack — see the Sourcing rule in CLAUDE.md). Do not stop and
wait for the reconnection.
Pitfalls ruled out in practice
- A
connected state in /mcp or on the connectors page does not imply a valid downstream token.
- Rule out an account mismatch (CLI and browser on the same identity) before concluding the
token is expired.
- Claude cannot trigger the OAuth handshake itself (interactive command, URL not exposed,
security restriction by design) — pushing the user toward
/mcp then Disconnect/Reconnect is
the most it can do.
