fix(client): deduplicate concurrent OAuth refreshes

[CharlesMcMillan]

Summary

Prevent overlapping OAuth refresh calls from redeeming the same rotating refresh token. Equivalent calls sharing a provider share one pending result; calls with different auth options are serialized and execute their own discovery and validation. Authorization-code exchanges and forced reauthorization remain distinct operations.

Hosts sharing credentials across processes can implement the optional withAuthTransaction provider hook. It wraps the complete auth operation, including error recovery and persistence, so hosts can release ownership in one finally instead of inferring completion from individual provider callbacks. No lock spans browser consent.

The client decoder also treats error_description: null as omitted, preserving an authorization server's invalid_grant classification. The public OAuth schema stays strict.

Fixes #1760. Replaces #1813. Adapter integration: nicobailon/pi-mcp-adapter#528.

Verification

• 906 client tests pass, including 23 transaction/parser tests and joining an already-running refresh.
• Client check/build and workspace typecheck/lint pass.
• The optional hook is exercised by a six-process adapter integration test using single-use rotating fake tokens; production credentials are not used.
• Local E2E protocol timeout errors also reproduce at baseline 5119ee7f; published CI is checked separately for each PR head.

Follow-up

The unrelated sse-retry conformance warning is tracked in modelcontextprotocol/conformance#500 and should not block this OAuth fix. The proposed follow-up adds bounded client-suite concurrency, runs timing-sensitive SSE checks outside the concurrent pool, preserves the harness's suite and expected-failure logic, and saves detailed artifacts on failure. Once that support is released, the SDK can update its pinned conformance package in a separate PR.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3b205e7

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

[CharlesMcMillan]

@claude review

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/codemod

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

@modelcontextprotocol/core

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

@modelcontextprotocol/server

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

@modelcontextprotocol/server-legacy

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: 3b205e7

[CharlesMcMillan]

@claude review

[CharlesMcMillan]

Current head 3b205e7 has one failing check: client-conformance reports sse-retry as 2 passes plus a timing warning. The isolated scenario passes locally (503 ms reconnect vs 500 ms target), while the auth scenarios pass in CI. I cannot rerun the failed job with contributor permissions (GitHub requires repository admin rights). Could a maintainer rerun job 101554954460 / run 34058603161? No test suppression or unrelated SSE changes are included.

[CharlesMcMillan]

Filed modelcontextprotocol/conformance#500 for the unrelated SSE timing warning. The follow-up will bound client-suite concurrency and isolate timing-sensitive scenarios without weakening the SSE check or adding it to expected failures. I added the link and plan to this PR description; it should not block the OAuth change.