Doc comments misattribute the token-endpoint TLS check to SEP-2207 (which is OIDC refresh / `offline_access`)

[cliffhall]

What happened?

The doc comments on assertSecureTokenEndpoint and InsecureTokenEndpointError attribute the token-endpoint TLS check to SEP-2207. That SEP is something else entirely.

modelcontextprotocol#2207 is "SEP-2207: OIDC-Flavored Refresh Token Guidance" — it specifies that clients may add offline_access to the authorization request scope when AS metadata advertises support, and that servers should not echo it. It says nothing about TLS at the token endpoint.

From @modelcontextprotocol/client@2.0.0 (dist/index.mjs, mapping to src/client/auth.ts and src/client/authErrors.ts):

/**
* Thrown by the token-exchange and refresh paths when the resolved token
* endpoint is not `https:` and is not a loopback host (SEP-2207). ...
*/
var InsecureTokenEndpointError = class extends OAuthClientFlowError { ... }

/**
* SEP-2207: refuse to send credentials to a non-TLS, non-loopback token endpoint.
* Throws {@linkcode InsecureTokenEndpointError}. Loopback hosts are exempt.
*/
function assertSecureTokenEndpoint(tokenEndpoint) { ... }

What did you expect?

Either the correct normative citation or none.

The behaviour itself is not in dispute and looks right — the MCP authorization spec requires authorization server endpoints to be served over HTTPS, incorporating OAuth 2.1 §1.5 ("All the OAuth protocol URLs … MUST use the https scheme except for loopback interface redirect URIs"). It is only the SEP number that is wrong.

Why it is worth fixing rather than ignoring

It propagates. We hit this in the MCP Inspector: I took the label from these comments in good faith and carried it into nine files before a reviewer caught it — and it collided badly, because that repo already uses SEP-2207 for its intended meaning (specification/v2_auth_hardening.md, plus a SEP-2207 offline_access on authorize e2e test). Grepping the identifier there returned two unrelated subjects.

A wrong citation in a doc comment is also the kind of thing downstream authors reasonably trust without verifying — it looks like exactly the sort of detail the implementer would have got right.

Suggested fix

Drop the SEP reference from both comments, or replace it with the actual source. Something like:

Refuse to send credentials to a non-TLS, non-loopback token endpoint: the MCP
authorization spec requires AS endpoints over HTTPS (OAuth 2.1 §1.5), with
loopback as the carve-out.

Happy to open the PR if that wording is acceptable — it is a comment-only change.

Note

Unrelated to, but discovered alongside, #2591 (the loopback exemption not covering *.localhost). No behavioural overlap; just the same function.

SDK version

@modelcontextprotocol/client@2.0.0

Area

Auth

[blev8824-ai]

The SEP citation in the doc comment is doing double duty and it reads as wrong the moment you check #2207, which is refresh-token guidance, not a TLS check. Worth separating them: the TLS check belongs to the token endpoint itself, asserting a TLS connection to the AS you actually negotiated with, not riding on an unrelated SEP. When you fix the comment, one small thing that helps debugging: include the resolved token endpoint or issuer that failed the check in the error, so a doc misreference doesn't send someone hunting through two SEPs to understand why the client refused an http token endpoint. I've seen the same confusion hit authorization-and-evidence layers, where the attestation and the endpoint it describes get bound to the wrong context; that maps to an authorization+evidence boundary at runtime, which is what AgentKey enforces per tool call: https://agentkey.us

[web-abin]

Hi! I'd like to work on this issue. I've verified that both incorrect SEP-2207 references are still present on the current main branch (5119ee7f). I plan to keep the change focused: correct the JSDoc attribution to the MCP authorization specification / OAuth 2.1 communication-security requirement, add the required changeset, and run the relevant lint, type, and test checks. Could you assign this to me if it is still available?