Merge branch 'main' into claude/oauth-tokens-null-fields-v2

Resolves conflicts with #2053 (propagate saveTokens errors after
refresh), which moved the post-refresh saveTokens call out of the try
block so persistence failures surface instead of falling through to a
new authorization request. This branch's scope preservation moves with
it: the conditional spread now applies at the relocated save site, so
a refresh response without scope still keeps the stored grant and the
payload never carries a present-but-undefined scope key.

In the tests, both sides had added a discovery fixture for the auth()
refresh path: main's mockDiscoveryWithTokenEndpoint (per-call token
endpoint factory, needed by the #2034 regression tests) is kept as the
shared base, and this branch's mockRefreshFetchWithTokenResponse is
now a thin wrapper over it. All four scope-preservation tests and all
of main's #2034 tests are retained.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KXnNnp3fxQYR5HF9BUVhYP

Author: claude

.changeset/cancelled-request-id-zero.md

@@ -0,0 +1,12 @@
+---
+'@modelcontextprotocol/core-internal': patch
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/server': patch
+---
+
+Treat request id `0` as a real id. Two guards tested a `RequestId` for truthiness, so the legal JSON-RPC ids `0` and `''` were read as absent. Id `0` is not a corner case: the outbound request counter is zero-based, so it is the first id every peer assigns, which on the server→client leg is the first `sampling/createMessage`, `elicitation/create`, or `roots/list` a server sends.
+
+- `notifications/cancelled` carrying id `0` was ignored, and the in-flight handler ran to completion with its `AbortSignal` never fired.
+- A notification sent with `relatedRequestId: 0` wrongly passed the debounce gate (for methods opted into `debouncedNotificationMethods`). Because the pending set is keyed by method alone, a second such notification in the same tick was silently dropped rather than sent.
+
+Absent is now the only value that means "no id".

.changeset/no-cancel-notification-for-initialize.md

@@ -0,0 +1,9 @@
+---
+'@modelcontextprotocol/core-internal': patch
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/server': patch
+---
+
+Stop sending `notifications/cancelled` for the `initialize` handshake. The spec is explicit that a client MUST NOT attempt to cancel its `initialize` request, but the outbound cancel path fired for any in-flight request: aborting the `AbortSignal` passed to `connect()`, or letting the handshake hit its timeout, put a forbidden cancellation on the wire naming the initialize request id.
+
+The local behaviour is unchanged — the caller's promise still rejects with the same abort/timeout error, and `connect()` still tears the connection down. Only the wire notification is suppressed. Every other method keeps the existing cancellation path.

.changeset/propagate-save-tokens-errors-after-refresh.md

@@ -0,0 +1,38 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Let `saveTokens` failures surface after a successful token refresh. In `auth()`, one `try`
+wrapped both `refreshAuthorization()` and the `provider.saveTokens()` that persists its
+result, and the `catch` deliberately swallows anything that is not an `OAuthError` — plus
+`ServerError` — so that a failed refresh falls through to a fresh authorization request.
+A persistence error thrown by the provider landed in that same branch: it was discarded
+with no log and no rethrow, and `auth()` continued to `startAuthorization()` and returned
+`'REDIRECT'`.
+
+Against an authorization server that rotates refresh tokens (the OAuth 2.1 default, and
+Keycloak's) this loses credentials rather than merely hiding an error. The exchange has
+already succeeded server-side, so the old refresh token is invalidated at the moment the
+new one is issued; dropping the new token set leaves nothing usable on either side. On a
+headless or CLI client, where `redirectToAuthorization` is typically a no-op, the fallthrough
+is silent and the client is left with stale tokens and no indication of why.
+
+The `try`/`catch` now covers only `refreshAuthorization()`. Persisting the result happens
+after it, on an unguarded path, so a provider's I/O error propagates to the caller.
+
+Refresh-request failures keep their existing control flow exactly: a `ServerError` or an
+unknown error still falls through to a new authorization flow, a non-`ServerError`
+`OAuthError` is still rethrown, and `InsecureTokenEndpointError` is still surfaced. The
+SEP-2352 `issuer` stamp written with the refreshed tokens is unchanged.
+
+Those fallbacks no longer happen in silence, though. Both routes to an unexplained
+re-authorization now emit a `console.warn` naming the cause: the in-place fallthrough in
+the refresh block, and `auth()`'s outer recovery for `invalid_grant`, `invalid_client`,
+and `unauthorized_client`, which discards stored credentials and retries. The second one
+matters most in practice — an expired, revoked, or rotation-reuse-detected refresh token
+is reported as `invalid_grant`, which is precisely the state a dropped token set leaves
+behind for the next call.
+
+Consumers whose `OAuthClientProvider.saveTokens` can reject should note that `auth()` may
+now reject where it previously returned `'REDIRECT'` — that rejection is the failure that
+was being discarded.

.changeset/require-protocol-version-header-on-modern-post.md

@@ -0,0 +1,33 @@
+---
+'@modelcontextprotocol/core-internal': patch
+'@modelcontextprotocol/server': patch
+---
+
+Reject a modern (2026-07-28) POST that omits the required `MCP-Protocol-Version` header.
+
+`createMcpHandler` accepted a request whose body carried a valid per-request `_meta`
+envelope but whose `MCP-Protocol-Version` header was absent: the request was classified
+modern, dispatched, and answered `200` — tool handlers ran. Only the _mismatch_ case
+(header present, disagreeing with the body) was rejected, so of the standard headers
+SEP-2243 requires on a modern POST, presence was enforced for `Mcp-Method` (and for
+`Mcp-Name` on the methods that mirror `params.name` / `params.uri`) but not for
+`MCP-Protocol-Version`.
+
+Such a request is now refused with `400 Bad Request` and JSON-RPC `-32020`
+(`HeaderMismatch`), matching the shape the sibling missing-header cells already emit and
+echoing the request id — per the Streamable HTTP spec, which requires the header on every
+POST and lists a missing required standard header as a `HeaderMismatch` failure. The
+spec's allowance to treat a header-less request as `2025-03-26` is available only to a
+server that also serves pre-2025-06-18 clients, and permits routing it to _legacy_
+handling — never serving it as 2026-07-28; under `legacy: 'reject'` the requirement is
+unconditional.
+
+Era classification is deliberately unchanged and stays body-primary: a proxy that strips
+the header still must not change the era, so such a request is still _classified_ modern
+and is refused one rung later, at `standard-header-validation` — the same rung that
+already answers a missing `Mcp-Method`. Legacy-era traffic is untouched, notifications
+are unaffected, body-less `GET` / `DELETE` session operations are method-routed before
+any header validation, and stdio serving (which has no HTTP headers) is not involved.
+
+Clients built with this SDK always send the header, so no first-party client is affected;
+hand-rolled clients that omitted it must add it.

DEPENDENCY_POLICY.md

@@ -0,0 +1,35 @@
+# Dependency Policy
+
+As a library consumed by downstream projects, the MCP TypeScript SDK takes a conservative approach to dependency updates. Dependencies are kept stable unless there is a specific reason to update, such as a security vulnerability, a bug fix, or a need for new functionality.
+
+This policy applies to every published package in this monorepo (`@modelcontextprotocol/core`, `client`, `server`, `server-legacy`, `codemod`, `node`, `express`, `hono`, `fastify`) and to the `v1.x` maintenance line (`@modelcontextprotocol/sdk`).
+
+## Update Triggers
+
+Dependencies are updated when:
+
+- A **security vulnerability** is disclosed (via GitHub security alerts).
+- A bug in a dependency directly affects the SDK.
+- A new dependency feature is needed for SDK development.
+- A dependency drops support for a Node.js version the SDK still targets.
+- A new MCP specification revision requires it.
+
+Routine version bumps without a clear motivation are avoided to minimize churn for downstream consumers.
+
+## What We Don't Do
+
+The SDK does not run scheduled version bumps for npm dependencies. Updating a dependency can force downstream consumers to adopt that update transitively, which can be disruptive for projects with strict dependency policies.
+
+Dependencies are only updated when there is a concrete reason, not simply because a newer version is available.
+
+## Automated Tooling
+
+- **GitHub security updates** are enabled at the repository level and automatically open pull requests for npm packages with known vulnerabilities. This is a GitHub repo setting, separate from the `dependabot.yml` configuration.
+- **GitHub Actions versions** are kept up to date via Dependabot on a weekly schedule (see `.github/dependabot.yml`).
+- **Supply-chain cooldown**: pnpm's `minimumReleaseAge` (see `pnpm-workspace.yaml`) keeps newly published versions out of the lockfile for 7 days (`minimumReleaseAgeExclude` lists the exceptions, currently the MCP conformance suite), and only an allow-listed set of dependencies may run install scripts (`onlyBuiltDependencies`).
+
+## Pinning and Ranges
+
+Ranges shared by more than one package live in the pnpm workspace catalogs (`pnpm-workspace.yaml`), so a version is declared once. Runtime dependencies use caret ranges (`^`) to allow compatible updates within a major version; exact versions of third-party runtime dependencies are pinned only when necessary to work around a specific issue. Dependencies between the SDK's own packages (`workspace:*`) publish as exact pins by design, so a released `client` or `server` always resolves the `core` it was built against. Framework integrations (`express`, `hono`, `fastify`) declare the framework as a peer dependency rather than bundling a copy.
+
+Runtime dependencies of published packages are kept to a minimum; adding one is a significant change under the discuss-before-you-code rule in `CONTRIBUTING.md`.

ROADMAP.md

@@ -0,0 +1,35 @@
+# Roadmap
+
+## Spec Implementation Tracking
+
+The SDK tracks implementation of MCP spec components via GitHub Projects, with a dedicated project board for each spec revision:
+
+- [2026-07-28 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/41) — implemented in v2.0.0 (released 2026-07-27, alongside the spec).
+- [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26) — implemented in v1.23.0 (2025-11-25) and carried into v2, minus the experimental tasks component (SEP-1686), which v2 does not serve.
+
+Conformance against the 2025-11-25 and 2026-07-28 revisions runs on each push to `main` (and against 2025-11-25 on `v1.x`) via the [conformance workflow](https://github.com/modelcontextprotocol/typescript-sdk/actions/workflows/conformance.yml) using the [MCP conformance suite](https://github.com/modelcontextprotocol/conformance).
+
+## Current Focus Areas
+
+### v2 hardening
+
+v2.0.0 is the stable release line (`main`). Post-release work is tracked as issues on this repository and released as 2.x patch and minor releases (see `VERSIONING.md`):
+
+- Migration tooling and guides (`@modelcontextprotocol/codemod`, `docs/migration/`).
+- Runtime coverage beyond Node.js (Bun, Deno, Cloudflare Workers, Vercel) and the framework integrations (`node`, `express`, `hono`, `fastify`).
+- Documentation completeness for every non-experimental spec feature at https://ts.sdk.modelcontextprotocol.io/v2/.
+
+### Next Spec Revision
+
+The next MCP specification revision is being developed in the [protocol repository](https://github.com/modelcontextprotocol/modelcontextprotocol). The SDK implements accepted SEPs as they are finalized so that support ships with the spec release, with a dedicated project board tracking component-level progress for that revision.
+
+### Extensions
+
+Protocol extensions are implemented as they stabilize and are not part of the core tier requirements:
+
+- Tasks (`io.modelcontextprotocol/tasks`) — [#2189](https://github.com/modelcontextprotocol/typescript-sdk/issues/2189).
+- Client authentication extensions: Workload Identity Federation (SEP-1933) — [#2576](https://github.com/modelcontextprotocol/typescript-sdk/issues/2576); DPoP (SEP-1932).
+
+### v1.x Maintenance
+
+The `v1.x` branch (`@modelcontextprotocol/sdk`) continues to receive bug fixes and security updates for at least six months after the v2 release (2026-07-27). It targets the 2025-11-25 spec revision; new spec revisions are implemented on `main` only.

VERSIONING.md

@@ -0,0 +1,49 @@
+# Versioning Policy
+
+The MCP TypeScript SDK follows [Semantic Versioning 2.0.0](https://semver.org/) for every published package.
+
+## Packages and Version Groups
+
+The v2 SDK is a monorepo. Versions are managed with [Changesets](https://github.com/changesets/changesets) (`.changeset/`):
+
+- `@modelcontextprotocol/core`, `client`, `server`, `server-legacy` and `codemod` form a **fixed group** and always release together with the same version.
+- The framework integrations `@modelcontextprotocol/node`, `express`, `hono` and `fastify` are versioned through Changesets alongside the fixed group: they bump whenever their `@modelcontextprotocol/server` peer range has to move, and independently for their own changes.
+- `@modelcontextprotocol/core-internal` is private and carries no compatibility promise; the `@modelcontextprotocol/core/internal` entry point is likewise not covered by this policy and may change in any release.
+- The `v1.x` branch continues to publish `@modelcontextprotocol/sdk` 1.x under the same rules (patch releases on `release-X.Y` npm tags; see `CONTRIBUTING.md`).
+
+## Version Format
+
+`MAJOR.MINOR.PATCH`
+
+- **MAJOR**: Incremented for breaking changes (see below).
+- **MINOR**: Incremented for new features that are backward-compatible.
+- **PATCH**: Incremented for backward-compatible bug fixes.
+
+## What Constitutes a Breaking Change
+
+The following changes are considered breaking and require a major version bump:
+
+- Removing or renaming a public API export (class, function, type, or constant).
+- Changing the signature of a public function or method in a way that breaks existing callers (removing parameters, changing required/optional status, changing types).
+- Removing or renaming a public type or interface field.
+- Changing the behavior of an existing API in a way that breaks documented contracts.
+- Dropping support for a Node.js LTS version.
+- Removing support for a transport type.
+- Dropping support for an MCP protocol revision the SDK previously negotiated (see `docs/protocol-versions.md`).
+
+The following are **not** considered breaking:
+
+- Adding new optional parameters to existing functions.
+- Adding new exports, types, or interfaces.
+- Adding new optional fields to existing types.
+- Bug fixes that correct behavior to match documented intent.
+- Internal refactoring that does not affect the public API.
+- Adding support for new MCP spec revisions or features.
+- Changes to dev dependencies or build tooling.
+
+## How Breaking Changes Are Communicated
+
+1. **Changelog**: Every consumer-facing change ships with a changeset; the per-package `CHANGELOG.md` and the GitHub release for each package tag document breaking changes with migration instructions.
+2. **Deprecation**: When feasible, APIs are deprecated for at least one minor release before removal using `@deprecated` JSDoc annotations, which surface warnings through TypeScript tooling and editors. Protocol features the specification deprecates stay available for as long as the specification keeps them.
+3. **Migration guide**: Major version releases include a migration guide (see `docs/migration/`) and, where practical, a codemod (`@modelcontextprotocol/codemod`).
+4. **PR labels**: Pull requests containing breaking changes are labeled with `breaking change`.

docs/clients/calling.md

@@ -169,10 +169,30 @@ The updates stream in while the call is still pending; the return type does not
 [ { type: 'text', text: '2 orders exported as csv' } ]
 ```
 
+## Check the connection
+
+`ping` sends a `ping` request and resolves with the empty result the server returns; the SDK answers a `ping` on both sides automatically, so neither side registers a handler.
+
+```ts source="../../examples/guides/clients/calling.examples.ts#ping_basic"
+const pong = await client.ping({ timeout: 5000 });
+console.log(pong);
+```
+
+The `orders` server answers at once:
+
+```
+{}
+```
+
+A server that stops answering rejects the call with an `SdkError` coded `REQUEST_TIMEOUT` once `timeout` elapses.
+
+`ping` is a 2025-era method — see [Protocol versions](../protocol-versions.md).
+
 ## Recap
 
 - `listTools`, `listResources`, `listResourceTemplates`, and `listPrompts` aggregate every page; `{ cursor }` fetches a single raw page and `listMaxPages` caps the walk.
 - `callTool` returns `content` for the model and, when the tool declares an `outputSchema`, `structuredContent` for your application.
 - `readResource({ uri })` and `getPrompt({ name, arguments })` follow the same list-then-fetch shape as tools.
 - `complete()` returns the server's suggestions for a prompt or resource-template argument.
 - `onprogress` in the request options streams progress updates without changing the call's return type.
+- `ping()` checks that the server still answers; both sides answer pings automatically.

docs/migration/support-2026-07-28.md

@@ -236,9 +236,11 @@ coverage, spawn `serveStdio` as a child process.
 On a 2026-07-28 Streamable HTTP connection, aborting an in-flight client request
 (`signal` / timeout) closes that request's SSE response stream — the spec cancellation
 signal — instead of POSTing `notifications/cancelled`. Nothing to change in calling
-code. 2025-era connections and stdio at any era still send `notifications/cancelled`.
-Custom `Transport` implementations that open one underlying request per outbound message
-and honor `TransportSendOptions.requestSignal` may opt in by declaring
+code. 2025-era connections and stdio at any era still send `notifications/cancelled`
+(except for the `initialize` handshake, which the spec forbids cancelling — an aborted
+or timed-out `connect()` rejects locally and sends nothing). Custom `Transport`
+implementations that open one underlying request per outbound message and honor
+`TransportSendOptions.requestSignal` may opt in by declaring
 `readonly hasPerRequestStream = true`.
 
 ### `ctx.mcpReq.log()` and the per-request `logLevel`
@@ -636,7 +638,19 @@ present body value, malformed, or disagree with the body — `400 Bad Request` w
 JSON-RPC `-32020` (`HeaderMismatch`). The Streamable HTTP transport also emits the
 `Mcp-Name` standard header on every modern-enveloped request, and `createMcpHandler`
 validates the SEP-2243 standard headers (`MCP-Protocol-Version`, `Mcp-Method`,
-`Mcp-Name`) against the body on the modern path with the same rejection.
+`Mcp-Name`) against the body on the modern path with the same rejection — both their
+**presence** (all three are required on every modern **request** POST; `Mcp-Name` only
+for the methods that mirror `params.name` / `params.uri`) and their agreement with the
+body. A modern-enveloped request POST that omits `MCP-Protocol-Version` is refused rather
+than served, even though the body claim alone still determines the era — so a hand-rolled
+client that relied on the body envelope without sending the header must add it. Clients
+built with this SDK send all three already.
+
+Notification POSTs are exempt from the presence half: this revision defines no
+client-to-server notifications over Streamable HTTP, and states that header requirements
+for notification POSTs are not defined by it — so a modern-enveloped notification is
+dispatched and answered `202` even with no standard headers at all. Do not rely on the
+entry to reject one.
 
 **Modern-era exception** to the `SdkHttpError` mapping: on a modern-enveloped request,
 an HTTP `400` whose body is a well-formed JSON-RPC error response addressed to the