OAuth: `InsecureTokenEndpointError` renders as a retryable "Re-authenticate" banner that can never succeed

[cliffhall]

Which client?

Web

The problem

The SDK's assertSecureTokenEndpoint throws InsecureTokenEndpointError when an OAuth token endpoint is plain http: on a host outside its loopback exemption (localhost / 127.0.0.1 / ::1). That string appears nowhere in the Inspector's source, so the error falls through to the generic auth-failure path and the UI renders a "Re-authentication required" banner with a Re-authenticate button.

That button cannot possibly work. The SDK special-cases this error to rethrow rather than fall through to a fresh /authorize redirect — it is a deliberate hard stop, not a transient auth failure. InsecureTokenEndpointError also does not extend OAuthError, precisely so it is not treated as retryable.

So the Inspector presents a terminal configuration error as a retryable auth error. The user clicks Re-authenticate, the same error is thrown again, and nothing in the UI ever says what is actually wrong or what to do about it.

Reported from the outside on modelcontextprotocol/typescript-sdk#2591, where it is the reason the underlying problem was hard to diagnose.

Expected behavior

Recognize the error and surface it as what it is: a configuration problem with a concrete cause and a concrete fix, and no Re-authenticate affordance.

The message should name the offending endpoint, say that OAuth token requests must use TLS, and point at the two things that actually resolve it — use https:, or make the endpoint genuinely loopback (localhost / 127.0.0.1 / ::1). Where a per-server Token URL override exists (#1906), that is the lever to mention.

Notes

• This is independent of Add support for *.localhost domains #1944. Fixing the *.localhost case upstream shrinks how often this fires but does not fix the presentation for every other insecure-endpoint case (host.docker.internal, a LAN hostname, a reverse-proxy name).
• Related: Opt-in OAuth HTTP exception for trusted local development hosts #1911 (closed as not planned — the exemption list is not relaxable from this side), and roadmap §4.8 Connection Doctor, of which this is a small instance.

[cliffhall]

Shipped in #2288 (merged as 219a08e).

The terminal token-endpoint refusal is now classified on every path that can raise it — the connect handshake, authenticate() during connect, the satisfied-challenge connect retry, the post-redirect callback, the command/background path, the deferred tab-visible resume, and the re-auth banner action — all through one shared reporter, so a future path cannot surface the notice while forgetting the banner clear.

What a user sees instead of the dead Re-authenticate button: a non-expiring notice naming the offending endpoint, stating that re-authenticating cannot change it, and giving both remedies — serve the token endpoint over HTTPS, or move it to localhost / 127.0.0.1 / [::1], with the per-server Token URL override in Server Settings → OAuth Settings as the local lever.

Reproducible by hand via oauth-insecure-token-endpoint-http.json, documented in docs/test-servers.md.

⚠️ This changed the reporting, not the outcome. An endpoint outside the SDK's three-literal exemption is still refused; that fix has to land upstream in typescript-sdk#2597.

One finding was declined on scope rather than fixed: with stored tokens present, the SDK transport refreshes inside client.connect(), so the refusal reaches the status-setting catch and statusChange("error") is dispatched before the arm can tear down — briefly reddening the card and pinning the monitoring sidebar, which persists via localStorage. It needs configuration drift to reach (tokens obtained while the endpoint was still usable), the common no-tokens path is clean, and the remedy would change connect-status semantics in core/ across all three clients. The analysis and exact precondition are recorded on #2288 if it is ever seen in practice.