claude-code - 💡(How to fix) Fix Connectors authenticated on claude.ai aren't surfaced in an already-running Claude Code session — silent inconsistency

Summary

The Claude Code CLI builds its MCP tool catalogue once at session start. When a user authenticates a Connector on claude.ai (the web app) during a live Claude Code session, the CLI does not surface the connector's tools, and gives no indication to the user that a restart is required to pick them up. The two surfaces share branding, auth UI, and connector taxonomy, but the CLI silently ignores mid-session auth-state changes made on the web.

Reproduction

1. Open Claude Code in a terminal and start a session.
2. In a browser, go to claude.ai → Settings → Connectors → authenticate a connector (e.g. Gmail) with write permissions.
3. Verify on claude.ai that the connector's tools are listed and enabled (e.g. "Creates a new draft email").
4. In the same CLI session, ask Claude Code to use one of the connector's tools (e.g. "draft an email").

Expected

The CLI either: (a) refreshes the MCP tool catalogue on demand and surfaces the newly-authenticated connector's tools, or (b) tells the user explicitly: "You've authenticated <X> on claude.ai. Quit and relaunch Claude Code for these tools to surface in this session."

Actual

• The CLI's deferred-tool registry contains only the auth-handshake stubs for the connector (e.g. mcp__claude_ai_Gmail__authenticate, mcp__claude_ai_Gmail__complete_authentication), not the action tools.
• Running /mcp shows a different auth flow (CLI-side MCP servers) and gives no hint that claude.ai connectors are a separate, session-frozen catalogue.
• The model, given the available tools, has no way to deduce that the missing tools exist on claude.ai's side and would surface after a restart. It will typically tell the user the capability isn't available — which is wrong; it's available, just not in this session.
• The user's mental model ("I authenticated this once on Anthropic-branded surface X, it should work on Anthropic-branded surface Y") is correct. The implementation doesn't honour it.

Why this matters

Two failure modes compound:

1. Surface coherence: claude.ai and Claude Code share the Connector concept, branding, and OAuth flow. A connector authenticated on one surface is, from the user's POV, authenticated for "Claude." The CLI session-start-only catalogue silently breaks that contract.
2. Discoverability of the recovery path: even after a model figures out the tools aren't loaded, there is no canonical "tool not loaded — here's how to load it" instruction surfaced. The user (and the model) have to deduce the "quit and relaunch" workaround.

I hit this today trying to use Gmail draft tools from a Claude Code session. After authenticating Gmail on claude.ai, the CLI surfaced only the auth-handshake stubs. The fix — quit and relaunch Claude Code — was not surfaced by the CLI, by /mcp, or by the model. I had to deduce it from the absence of the expected tools.

Suggested fix (in order of preference)

1. Refresh on demand: when a model attempts to invoke an unloaded mcp__claude_ai_* tool, or when the user runs /mcp (or a new /connectors subcommand), check the claude.ai connector-auth state and refresh the local catalogue if it has changed.
2. Surface the inconsistency: if (1) is too expensive, detect the auth-state delta at session start and at user-visible moments and tell the user: "<X> was authenticated on claude.ai since this session started — restart to use it."
3. At minimum, document it: when the CLI's catalogue contains only auth-handshake stubs for a known claude.ai connector, return a tool-result message clearly stating: "These are stubs only. Authenticate on claude.ai and restart Claude Code to surface the action tools." Models can then relay the recovery path to the user.

Cluster

Adjacent to but distinct from the seven model-behaviour reports I've filed (#56351, #56979, #57836, #58040, #58041, plus dup-bot-closed #56972, #56973). This is a product/surface-coherence issue, not a model-behaviour pattern.