fix(core): start OAuth on a modern/auto-era connect (#1805)

[rinormaloku]

Closes #1805

Connecting to an OAuth-protected HTTP server with Protocol Era = Auto or Modern never started the authorization flow. The same server authorized fine on Legacy, and the user saw a red toast instead of the OAuth redirect:

Failed to connect to "<server>": Version negotiation probe failed: Interactive auth recovery required

Root cause

Era auto/modern sends the SDK's server/discover negotiation probe before anything else, so the probe — not initialize — is where authorization first surfaces. Its classifier reports whatever the transport threw as SdkError(ERA_NEGOTIATION_FAILED), keeping the real error at data.cause. That buried both connect-time auth signals:

• Remote path (web). The backend always sets interceptAuthChallenges: true, so a 401 becomes AuthChallengeError → auth_challenge → RemoteClientTransport rejects with AuthRecoveryRequiredError (carrying the authorization URL). Wrapped, it no longer matched err instanceof AuthRecoveryRequiredError in App.tsx, and isUnauthorizedError() couldn't see it either (no status/code). It also flipped connection status to error, which isConnectAuthRecoveryError exists to prevent.
• Direct path (CLI/TUI). No stored tokens means no authProvider, so no interception, so the 401 reached the SDK as a raw SdkHttpError. The classifier ignores the HTTP status — it only looks for a JSON-RPC error body — and verdicts "not a modern server"; pin mode then rethrew that with the 401 discarded entirely: no status, not even a cause.

Reproduced against a live dual-era server answering 401 on both initialize and server/discover:

era	error out of client.connect()	recovery matched?
legacy	AuthRecoveryRequiredError	✅ redirect
auto	SdkError / ERA_NEGOTIATION_FAILED	❌ generic toast
modern (pin)	SdkError / ERA_NEGOTIATION_FAILED	❌ generic toast

core/auth/utils.ts already anticipated this wrapper shape but only walked the chain for UnauthorizedError — not the two typed errors the Inspector's own paths produce.

Not caused by the 2026-07-28 authorization SEPs (SEP-2468 iss, SEP-837 application_type, SEP-2352 issuer binding, DCR deprecated in favour of CIMD): legacy-era authorization against the same server worked.

Changes

• core/auth/challenge.ts — findNestedAuthError() walks cause / data.cause for a nested AuthRecoveryRequiredError / AuthChallengeError. Deliberately not gated on the SDK's error code or message, so it survives SDK rewording.
• core/mcp/inspectorClient.ts — connect() unwraps the client.connect() rejection at the earliest point: ahead of withDirectAuthRecovery (whose isAuthChallengeError check is shallow), the outer status guard, and every client's connect-error handling. Web, CLI, and TUI are all fixed with no client-side change.
• core/mcp/inspectorClient.ts — on the direct path, enable interceptAuthChallenges for the probing eras even with no stored tokens, so the 401 becomes a typed AuthChallengeError that survives the probe as data.cause instead of being silently reclassified.

After the fix, against the same live server: auto and modern reject with AuthRecoveryRequiredError carrying a real authorization URL.

Tests

• clients/web/src/test/core/auth/challenge.test.ts — 8 cases over the walk (both link names, multi-level, already-typed, absent, non-object/null data, cyclic chain).
• clients/web/src/test/core/mcp/inspectorClient-era-probe-auth.test.ts — connect() surfaces each typed error on auto/modern, leaves a non-auth probe failure untouched, and keeps the legacy baseline; plus probesProtocolEra().
• clients/web/src/test/integration/mcp/inspectorClient-modern-era-oauth.test.ts — live modern-era server behind requireAuth: connect() rejects with a recoverable auth error (not a negotiation failure) on both probing eras, and connects reporting the modern era once authorization completes.

Each half of the fix is load-bearing — reverting either one fails the new integration tests. npm run ci is green (4,714 tests; per-file ≥90 coverage gate passed).

Follow-ups (not in this PR)

• Upstream SDK: classifyHttpError should treat HTTP 401/403 on the probe as auth-required rather than absence of modern evidence, and pin mode should not drop the status.
• A separate callback-leg failure exists on this path: when a pending authorization has no recorded discovery state, the SDK's SEP-2352 binding check throws AuthorizationServerMismatchError ("discoveryState was not available on the callback leg") and the Inspector dead-ends instead of restarting authorization. Clearing OAuth state works around it. Needs its own issue.

🤖 Generated with Claude Code

https://claude.ai/code/session_013SNjAqoEhUVVkr3UStR6om

[cliffhall]

Amended — I originally asked for the authProvider || guard to be dropped so interception was unconditional. Withdrawn; see the reasoning below. The requested change is now smaller.

Verified this end to end (details in #1805) — the diagnosis is right, both halves of the fix are load-bearing, and I found no regressions across web (4728), TUI (282) and CLI (304).

The two halves have different lifespans

Worth separating, because it drives what I'm asking for:

• findNestedAuthError() is the permanent fix. The reported failure is the remote/web path, where the transport rejects with our own AuthRecoveryRequiredError. The SDK doesn't know that type, so it wraps it — but it preserves it at data.cause. Nothing was destroyed; we simply matched with a top-level instanceof and never walked the chain, even though core/auth/utils.ts already walks those exact two links for UnauthorizedError. That's our bug and this is the correct fix for it.
• interceptAuthChallenges on the probing eras is a workaround. It exists only because of an SDK defect: on the direct path with no authProvider, classifyHttpError never reads the HTTP status, and pin mode then rethrows with the 401 annihilated — no status, no cause. That one genuinely cannot be recovered client-side. Filed upstream as server/discover probe classifier discards HTTP 401/403, and pin mode drops the cause typescript-sdk#2561, tracked here as [Blocked upstream] SDK probe classifier should treat 401/403 as auth-required, and pin mode must not drop the status #1807.

Requested: mark the workaround as removable

Keep the (transportOptions.authProvider || this.probesProtocolEra()) guard exactly as you wrote it — scoping it to the probing eras is right, precisely because it's temporary. Please just make its lifespan explicit in the comment, so whoever picks up #1807 knows this block is the thing to delete rather than having to re-derive it:

// WORKAROUND (#1807, upstream modelcontextprotocol/typescript-sdk#2561):
// remove this clause once the SDK classifies a probe 401/403 as auth-required.

That's the whole ask. Two notes on why I'm no longer pushing for the unconditional version: making it unconditional widens the surface of the code we intend to delete, and the era-scoped form is self-documenting about which connects need the compensation. The behavioral asymmetry it creates is real — on the direct path with no stored tokens, legacy rejects with a raw SdkHttpError 401 while auto/modern run discovery + DCR and reject with AuthRecoveryRequiredError (I confirmed both against a live composable server) — but that asymmetry is a faithful reflection of the upstream gap, and it disappears when #2561 lands. Encoding it in a comment beats encoding it in a wider blast radius.

Not blocking

• The unwrap is in the right place (earliest point, ahead of withDirectAuthRecovery and the outer status guard) and is correctly not gated on the SDK's error code or message. Good call — I read the beta.5 source, and the wrapper text is the only other thing you could have keyed off, and it would rot.
• Please swap the prose follow-up bullets in the PR body for [Blocked upstream] SDK probe classifier should treat 401/403 as auth-required, and pin mode must not drop the status #1807 and OAuth callback leg dead-ends when discovery state is missing (AuthorizationServerMismatchError) #1808 so the trail survives.

Before merge

CI hasn't run on this yet (external contributor — needs maintainer approval to trigger workflows). It needs to go green on the full ci chain, in particular the per-file ≥90 coverage gate, which I did not run locally.

[cliffhall]

Superseded by #1809, which carries your commit unchanged (authorship preserved), rebased onto current v2/main, plus the one requested comment change marking the era-probe interception as a removable workaround (#1807 / modelcontextprotocol/typescript-sdk#2561).

I ran the full npm run ci chain locally on that branch — green end to end, including the per-file ≥90 coverage gate that hadn't been exercised here. Follow-ups are now filed as #1807 and #1808 and linked from the PR body.

Thanks for the thorough diagnosis and tests — closing this in favour of #1809.