MCPClientManager: mid-session OAuth re-authorization (insufficient_scope step-up) is never surfaced, and its callback is dropped as stale #2658

What happens

An MCP server connected through MCPClientManager (via agent.addMcpServer()) is ready. A tool call then needs a scope the grant lacks, and the server answers 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="...". A 401 whose token refresh fails behaves the same way.

The SDK transport handles the challenge correctly. It runs auth(), builds a new authorization URL (granted scopes plus the challenged ones), passes it to the provider (authProvider.authUrl), and throws UnauthorizedError.

MCPClientManager only turns that into authenticating plus authUrl at connect time (connectToServer → persistAuthContinuation). Mid-session, callTool() lets the error through:

1. The URL is never shown. The connection stays ready, auth_url is not saved, and the caller gets a plain UnauthorizedError.
2. The callback is dropped. If the user opens the URL anyway (it is on the provider), handleCallbackRequest() finds the connection in an auth-accepted state (ready). It treats the callback as a stale popup, consumes the state and returns success without exchanging the code. The new scopes are never saved, so the retry fails the same way.

Real case: the Cloudflare API MCP server (mcp.cloudflare.com) granted with a Minimal or Read-only template. The first write tool call hits this.

Repro

A fake OAuth MCP server (protected-resource metadata, AS metadata, DCR, token endpoint) passed as transport.fetch to a real MCPClientManager in a Durable Object:

1. registerServer + connectToServer → authenticating. Callback with a base-scope code → ready.
2. callTool on a tool that needs workers_scripts:write → the server returns 403 insufficient_scope.
3. Expected: something the app can show (the new authUrl), and a callback that completes the flow. Actual: UnauthorizedError: Unauthorized, connection still ready, auth_url null. A callback for the provider's new URL is ignored as stale.

Full test: https://github.com/cloudflare/agents/pull/TBD (src/tests/mcp/mid-session-reauth.test.ts).

Workarounds in the wild

• The repo's own conformance client patches this in test code: requestReauth() in packages/agents/conformance/worker.ts sets conn.connectionState = AUTHENTICATING by hand after an unauthorized tool call.
• Dodo (an agent app on agents) wraps callTool the same way, plus a call to the private persistAuthContinuation().

Proposed fix

In callTool() (and readResource() / getPrompt()): on an unauthorized error where the provider now holds a new authUrl, move the connection to authenticating, call persistAuthContinuation(), fire onServerStateChanged, and throw a typed MCPAuthorizationRequiredError { serverId, authUrl, clientId } (with the original error as cause, so isUnauthorized() checks still match). The existing callback path then works unchanged. PR to follow.