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 modelcontextprotocol#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 #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 #2858).
• @modelcontextprotocol/client: tests 804/804, typecheck, lint, prettier all clean.

---

Generated by Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: ac7a7ef

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/core	Patch
@modelcontextprotocol/server	Patch
@modelcontextprotocol/server-legacy	Patch
@modelcontextprotocol/codemod	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: ac7a7ef

[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 modelcontextprotocol#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.