OAuth: isLoopbackHost rejects *.localhost subdomains, breaking host-based local dev (InsecureTokenEndpointError)

[solirpa]

What happened?

Summary

assertSecureTokenEndpoint exempts only the exact hostnames localhost, 127.0.0.1, ::1 and [::1]. Subdomains under the reserved .localhost TLD — e.g. http://tenant.example.localhost:3300 — are treated as public non-TLS endpoints and rejected, even though every layer below (RFC 6761, the browser's secure-context rules, the OS resolver) already treats them as loopback.

This makes SEP-2207 unusable for anyone whose local server is host-based multi-tenant, which is a common setup: the tenant is selected from the Host header, and session cookies are scoped to that host, so http://localhost:PORT is not an equivalent substitute.

Current behavior

Refusing to send credentials to non-https token endpoint
'http://tenant.example.localhost:3300/api/oauth/token'.
OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).

packages/client (as shipped in dist/index.mjs):

/** Loopback hosts exempt from the in-transit `https:` requirement (RFC 8252 §7.3). */
function isLoopbackHost(hostname) {
  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
}

function assertSecureTokenEndpoint(tokenEndpoint) {
  const url = new URL(String(tokenEndpoint));
  if (url.protocol !== "https:" && !isLoopbackHost(url.hostname)) throw new InsecureTokenEndpointError(url.href);
  return url;
}

In MCP Inspector this surfaces as a "Re-authentication required" banner with a Re-authenticate button that cannot possibly work — by design, since InsecureTokenEndpointError deliberately does not extend OAuthError and is rethrown rather than retried. The UI presents a config error as a retryable auth error.

What did you expect?

Why *.localhost should be exempt

RFC 6761 §6.3 reserves localhost. and any name ending in .localhost., with the same "resolves to the loopback interface" semantics. foo.localhost is loopback by specification, not by convention.
W3C Secure Contexts classifies an origin as potentially trustworthy when its host is localhost or ends in .localhost. Browsers already grant http://tenant.example.localhost:3300 secure-context privileges — the SDK is stricter than the browser it runs in.
Resolvers agree: macOS mDNSResponder, systemd-resolved, and Chrome/Firefox all send *.localhost to 127.0.0.1.
Not publicly registrable: .localhost is reserved, so unlike a generic suffix check this cannot be spoofed by acquiring a real domain. The residual risk (a hostile local resolver pointing evil.localhost elsewhere) applies equally to bare localhost, which is already exempt.
Also worth noting: SDK 1.x had no equivalent assertion, so setups like this worked before. The assertion itself is a clear improvement — the issue is only that the exemption list is narrower than the loopback definition it cites.

Proposed fix

function isLoopbackHost(hostname: string): boolean {
  return (
    hostname === "localhost" ||
    hostname.endsWith(".localhost") ||
    hostname === "127.0.0.1" ||
    hostname === "[::1]" ||
    hostname === "::1"
  );
}

Happy to open a PR (with tests) if the direction is acceptable.

Code to reproduce

Serve an MCP endpoint over plain HTTP on a *.localhost host, e.g. http://tenant.example.localhost:3300/api/mcp.
Advertise OAuth metadata derived from the request Host, so token_endpoint is http://tenant.example.localhost:3300/api/oauth/token.
Connect with Inspector 2.0 and start the OAuth flow → InsecureTokenEndpointError before any token request is sent.
Switching the same server to http://localhost:3300 passes the check, confirming the hostname comparison is the only difference.

SDK version

@modelcontextprotocol/client@2.0.0-beta.5（via @modelcontextprotocol/inspector@2.0.0）

Area

Auth