[DOCS] MCP OAuth docs omit re-authentication behavior after refresh token expiry

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

OAuth refresh failure handling and re-authentication for remote MCP servers.

Current Documentation

The MCP OAuth tips currently say:

Authentication tokens are stored securely and refreshed automatically Use "Clear authentication" in the /mcp menu to revoke access

The troubleshooting page separately says:

If Claude Code prompts you to log in again after a session, your OAuth token may have expired. Run /login to re-authenticate.

No documentation currently explains what happens when a remote MCP server's refresh token expires, when Claude must prompt for MCP re-authentication, or how that recovery flow differs from main Claude Code login.

What's Wrong or Missing?

Release v2.1.74 says Claude Code now correctly prompts for re-authentication when MCP OAuth refresh fails after refresh-token expiry, including OAuth servers that report errors via HTTP 200 (for example Slack).

Current docs promise automatic refresh but do not explain the user-visible fallback path when refresh is no longer possible. Users may incorrectly try /login instead of re-authenticating the affected MCP connection through /mcp.

Suggested Improvement

Add a short troubleshooting subsection covering:

1. When automatic refresh is attempted versus when re-authentication is required.
2. How the MCP re-authentication prompt appears to users.
3. How to recover through /mcp, including clearing auth or reconnecting a server.
4. A note that some providers may return OAuth errors through HTTP 200 responses.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 650-653 | OAuth docs promise automatic refresh and mention clearing auth, but not re-auth flow after refresh expiry |
| https://code.claude.com/docs/en/troubleshooting | 654-658 | Generic expired-token guidance points to /login, not MCP-specific re-authentication |

Total scope: 2 pages affected

Source: Release v2.1.74

• Fixed MCP OAuth refresh never prompting for re-auth after the refresh token expires, for OAuth servers that return errors with HTTP 200 (e.g. Slack)