docs(client): correct the registerClient deprecation citation to spec PR #2858

[claude]

Requested by Claude watching v2 issues · Slack thread

Fixes #2719

Problem

The @deprecated JSDoc on registerClient attributes the Dynamic Client Registration deprecation to SEP-2577. Per the 2026-07-28 changelog, SEP-2577 deprecates Roots, Sampling, and Logging; DCR was deprecated via spec PR modelcontextprotocol#2858 in favor of Client ID Metadata Documents (SEP-991). The notice surfaces in editor hovers and tsc deprecation warnings, so the crossed identifiers propagate (the reporter cited SEP-2577 in an internal compliance document before checking the primary source).

Changes

• packages/client/src/client/auth.ts — the @deprecated notice now cites spec PR fix(spec): freeze 2026-07-28 release references #2858 (and notes SEP-2577 is the separate roots/sampling/logging deprecation). It also addresses the issue's two smaller notes, both verified against the source:
  • names the earliest possible removal date (2027-07-28) implied by the feature lifecycle policy's minimum twelve-month window (SEP-2596), which is more actionable than the relative window alone;
  • clarifies where the CIMD gate lives: the client_id_metadata_document_supported check is in the built-in auth() flow (authInternal, packages/client/src/client/auth.ts:1251) — registerClient called directly always sends the registration request. The previous "the SDK already gates on this for you" read as though registerClient itself short-circuits.
• docs/migration/upgrade-to-v2.md — the registerClient bullet sits under the "Deprecated in v2 (SEP-2577)" heading; it now states the distinct provenance (spec PR fix(spec): freeze 2026-07-28 release references #2858) and why it is grouped there (the @deprecated annotations landed in the same sweep, Implement MCP 2026-07-28 #2286).
• Changeset: patch for @modelcontextprotocol/client (the JSDoc ships in the published .d.ts); documentation only, no runtime behavior change.

Verification

• Spec changelog checked at modelcontextprotocol/modelcontextprotocol HEAD (d8fdc88): Deprecated item 1 = Roots/Sampling/Logging (SEP-2577); item 4 = DCR (PR fix(spec): freeze 2026-07-28 release references #2858).
• @modelcontextprotocol/client: tests 804/804, typecheck, lint, prettier all clean.

---

Generated by Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 95abc13

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@modelcontextprotocol/client	Patch
@modelcontextprotocol/codemod	Patch
@modelcontextprotocol/core	Patch
@modelcontextprotocol/server-legacy	Patch
@modelcontextprotocol/server	Patch
@modelcontextprotocol/core-internal	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@2729

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@2729

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@2729

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@2729

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@2729

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@2729

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@2729

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@2729

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@2729

commit: 95abc13

[claude]

LGTM — docs-only change, and the latest commit addresses the precondition I flagged in the previous round.

What was reviewed:

• Checked the updated registerClient JSDoc against the auth() gate at auth.ts:1251-1283 — the "capability advertised AND clientMetadataUrl supplied" wording now matches shouldUseUrlBasedClientId exactly, and the note that direct registerClient calls never gate is accurate.
• Checked the changeset and migration-guide prose against the diff — claims (annotation-only, no runtime change, patch bump) all hold; the 2027-07-28 earliest-removal date is consistent with 2026-07-28 + twelve months.
• The spec-PR #2858 citation itself is an external reference I could not fetch this run; a wrong citation would be a prose nit only, with no code impact.

Extended reasoning...

Overview

The PR range covers two commits, all documentation: a new changeset (.changeset/dcr-deprecation-citation.md), a citation correction in docs/migration/upgrade-to-v2.md, and a rewritten @ deprecated JSDoc block on registerClient in packages/client/src/client/auth.ts (lines 2359-2372). No executable code changes anywhere in the diff — only comment and markdown text. The second commit (ac7a7ef) responds directly to the inline nit I posted on the prior version, adding the provider.clientMetadataUrl precondition to the description of when the built-in auth() flow skips registration.

Security risks

None. The diff touches an auth module but modifies only a JSDoc comment; no runtime behavior, control flow, credential handling, or export surface changes. I verified the JSDoc claims against the actual gating logic in auth() (auth.ts:1251-1283): shouldUseUrlBasedClientId = supportsUrlBasedClientId && clientMetadataUrl, matching the new prose exactly, and registerClient itself indeed performs no capability gating.

Level of scrutiny

Low-to-moderate. Per the repo's review conventions, added changeset text and inline comments must be read against the implementation in the same diff — I did that, and every code-facing claim (annotation-only, gating semantics, patch-level bump, no runtime change) is backed by the code. The one claim I could not independently confirm is the external citation that the DCR deprecation landed via spec PR #2858 rather than SEP-2577 (network access to verify was unavailable this run); if wrong it would be a prose citation nit with zero code impact, and the whole point of this PR is that the author researched and corrected exactly that citation.

Other factors

The bug-hunting rounds completed with no findings, and my sole prior-round comment was addressed by the newest commit — the timeline shows no outstanding third-party objections (only changeset-bot and pkg-pr-new automation). Docs-only changes fall squarely in the "comment updates" category the approval guidelines list as approvable, and the deprecation-window arithmetic (2026-07-28 + twelve months = 2027-07-28) is internally consistent.

[claude]

LGTM — the follow-up commit adds the clientMetadataUrl precondition, so the JSDoc now matches the auth() behavior, and the rest is a doc-only citation fix.

What was reviewed:

• The new gating sentence against auth() at packages/client/src/client/auth.ts:1304-1318 — it takes the CIMD branch only when client_id_metadata_document_supported === true and provider.clientMetadataUrl is set, otherwise falls through to registerClient; registerClient itself has no such check.
• The SEP-2577 reattribution against the repo's other docs (docs/clients/roots.md, docs/servers/sampling.md, logging-progress-cancellation.md), which all tie SEP-2577 to roots/sampling/logging, consistent with the correction. The spec PR #2858 / SEP-2596 numbers were not fetched from the spec site in this run.
• The patch changeset for a doc-only JSDoc change matches the precedent in .changeset/correct-token-endpoint-tls-citation.md (#2768).

Extended reasoning...

The diff touches only a JSDoc @ deprecated block on registerClient in packages/client/src/client/auth.ts, one bullet in docs/migration/upgrade-to-v2.md, and a new patch changeset (+20/-6); no runtime code changes, so no auth or security behavior is affected despite the file being auth code. The one inline nit from the prior run (missing clientMetadataUrl precondition) was addressed in commit ac7a7ef and the wording now matches the shouldUseUrlBasedClientId logic in auth(). The bug hunt ran dry, the changeset bump follows an existing repo precedent for doc-only citation fixes, and CODEOWNERS is only a repo-wide default owner, so a small comment-only correction does not need a human pass.