Implement MCP 2026-07-28 by felixweinberger · Pull Request #2286 · modelcontextprotocol/typescript-sdk

felixweinberger · 2026-06-12T15:13:18Z

Full implementation of the MCP 2026-07-28 specification revision on SDK v2. See the spec changelog for the protocol changes and the RC announcement for context.

This PR collects ~65 reviewed chunk PRs from the v2-2026-07-28 integration branch (#2281 through #2374). Each was reviewed and CI-gated individually before landing on the integration branch.

SEPs implemented

Stateless protocol

SEP-2575 / SEP-2567: no initialize handshake, no Mcp-Session-Id; protocol version, client identity and capabilities carried in _meta on every request; server/discover for up-front version selection; ping, logging/setLevel, SSE resumability removed
SEP-1865: subscriptions/listen long-lived stream replaces the GET endpoint and resources/subscribe/unsubscribe
SEP-2577 / SEP-2596 / SEP-991: @deprecated sweep on the roots/sampling/logging runtime APIs and type surface

Multi-round-trip requests

SEP-2322: InputRequiredResult (resultType: "input_required") replaces server-initiated roots/list/sampling/createMessage/elicitation/create; all results carry resultType

Transport

SEP-2243: Mcp-Method/Mcp-Name standard request headers on Streamable HTTP POSTs; x-mcp-header parameter mirroring
SEP-2549: ttlMs/cacheScope on list/read results; client-side response cache
SEP-414: OpenTelemetry trace-context _meta keys (traceparent/tracestate/baggage)

Schema

SEP-1613 / SEP-2106: JSON Schema 2020-12 posture; inputSchema/outputSchema accept any 2020-12 keywords; structuredContent accepts any JSON value; default validator is Ajv2020

Authorization

SEP-2468: RFC 9207 iss validation in finishAuth()
SEP-837 / SEP-2207: DCR application_type and registration metadata defaults
SEP-2352: per-authorization-server credential isolation (issuer-stamped tokens/client info)
SEP-835: resolved scope applied consistently to DCR and the authorization URL
SEP-2350: scope step-up on 403 insufficient_scope (union with challenged scopes)

Removed

SEP-2663: experimental tasks removed from core (now an official extension; SDK extension support tracked separately)

Backward compatibility

The SDK continues to interoperate with 2025-era peers. versionNegotiation controls which era the client speaks; createMcpHandler serves both eras from one server.

Migration

npx @modelcontextprotocol/codemod v1-to-v2 handles the mechanical renames
docs/migration/upgrade-to-v2.md covers what the codemod can't
docs/migration/support-2026-07-28.md covers adopting the 2026 wire surface once on v2

Breaking Changes

This is a major-version release (v1 → v2). See the migration guide; every change carries a changeset.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

changeset-bot · 2026-06-12T15:13:29Z

🦋 Changeset detected

Latest commit: f4c3ff0

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

This PR includes changesets to release 9 packages

Name	Type
@modelcontextprotocol/client	Major
@modelcontextprotocol/server	Major
@modelcontextprotocol/core-internal	Major
@modelcontextprotocol/server-legacy	Minor
@modelcontextprotocol/codemod	Patch
@modelcontextprotocol/node	Major
@modelcontextprotocol/express	Major
@modelcontextprotocol/fastify	Major
@modelcontextprotocol/hono	Major

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 · 2026-06-12T15:15:08Z

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/codemod

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

@modelcontextprotocol/core

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

@modelcontextprotocol/server

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

@modelcontextprotocol/server-legacy

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: f4c3ff0

Mirrors the v1.x-2026-07-28 arrangement: pull_request triggers are unfiltered (PRs targeting the branch already get CI); this adds the branch to the push filters so post-merge state runs CI too.

… the stdio env safelist (#2281)

…op stale task artifacts (#2290)

…evision generation (#2291)

…us (#2292)

…to ctx.mcpReq (#2293)

…2295)

… version lists (#2302)

…2303)

…igin validation middleware (#2304)

…ort; dual-era examples (#2305)

…nts, and the error status matrix (#2306)

…and missing envelope fields (#2311)

…streaming, and stamping scenarios (#2309)

felixweinberger changed the title ~~[draft tally] v2-2026-07-28 integration branch vs main~~[draft tally] Implement stateless in v2-2026-07-28 integration branch - Running TallyJun 12, 2026

felixweinberger changed the title ~~[draft tally] Implement stateless in v2-2026-07-28 integration branch - Running Tally~~[draft tally] Implement statelessJun 12, 2026

felixweinberger force-pushed the v2-2026-07-28 branch from 71f7307 to 6c4c871Compare June 15, 2026 15:40

github-advanced-securityBot found potential problems Jun 16, 2026
View reviewed changes

Comment threadtest/conformance/src/everythingServer.ts Dismissed

github-advanced-securityBot found potential problems Jun 19, 2026
View reviewed changes

Comment thread.github/workflows/examples.yml Fixed

github-advanced-securityBot found potential problems Jun 19, 2026
View reviewed changes

Comment threadexamples/bearer-auth/server.ts Fixed
Comment threadexamples/oauth-client-credentials/server.ts Fixed
Comment threadexamples/oauth/server.ts Fixed
Comment threadexamples/legacy-routing/server.ts Dismissed
Comment threadexamples/oauth/server.ts Dismissed

felixweinberger changed the title ~~[draft tally] Implement stateless~~[draft tally] Implement 2026-07-28Jun 22, 2026

felixweinberger changed the title ~~[draft tally] Implement 2026-07-28~~[draft tally] Implement MCP 2026-07-28Jun 22, 2026

github-advanced-securityBot found potential problems Jun 23, 2026
View reviewed changes

Comment threadexamples/bearer-auth/server.ts Fixed
Comment threadexamples/oauth-client-credentials/server.ts Fixed
Comment threadexamples/oauth/server.ts Fixed

github-advanced-securityBot found potential problems Jun 24, 2026
View reviewed changes

Comment threadexamples/scoped-tools/server.ts Dismissed

felixweinbergerand others added 18 commits June 24, 2026 13:28

ci: run workflows on pushes to the v2-2026-07-28 integration branch
7386246
Mirrors the v1.x-2026-07-28 arrangement: pull_request triggers are unfiltered (PRs targeting the branch already get CI); this adds the branch to the push filters so post-merge state runs CI too.

test: pin schema boundaries, error-code tables, package topology, and…
287c7bf
… the stdio env safelist (#2281)

ci: remove duplicated branch entry in the push filter
73f1370

build: committed API reports per public package with a CI gate (#2285)
eb78af4

fix(codemod): flag removed task options instead of migrating them; dr…
92c7ead
…op stale task artifacts (#2290)

chore(core): repin 2026-07-28 spec reference types; freeze released-r…
f614044
…evision generation (#2291)

test: wire-safety nets — cross-bundle error pin and spec example corp…
b864054
…us (#2292)

feat(core)!: hide wire-only members from the public types; lift them …
8b30ec3
…to ctx.mcpReq (#2293)

build: remove the committed API reports and their CI gate (#2299)
9ef3b7a

feat(core)!: per-era wire codec interface (#2294)
7f87e31

feat(core): the 2026-07-28 era codec; registry and schema CI oracles (#…
2210872
…2295)

feat(client): opt-in 2026-07-28 version negotiation; era-aware server…
eca9f3b
… version lists (#2302)

feat(server): per-request serving core and inbound validation ladder (#…
8bb58a1
…2303)

feat(server): createMcpHandler entry point, legacy slot model, and or…
e481fb1
…igin validation middleware (#2304)

feat(server): opt-in stdio dual-era serving via ServerOptions.eraSupp…
7ed2809
…ort; dual-era examples (#2305)

feat(server): complete the stateless call — result stamping, cache hi…
2914991
…nts, and the error status matrix (#2306)

fix(core): pin the modern-path rejection codes for header mismatches …
5e10345
…and missing envelope fields (#2311)

test(e2e): dual-era serving coverage — entry, stdio, sessionful BYO, …
b31dc1e
…streaming, and stamping scenarios (#2309)

felixweinberger requested a review from mattzcarey June 26, 2026 12:44

felixweinberger changed the title ~~[draft tally] Implement MCP 2026-07-28~~Implement MCP 2026-07-28Jun 26, 2026

mattzcarey approved these changes Jun 26, 2026
View reviewed changes

claudeBot reviewed Jun 26, 2026
View reviewed changes

Comment threadpackages/client/src/client/authErrors.ts
Comment threadpackages/client/src/client/auth.ts
Comment threadpackages/client/src/client/auth.ts

felixweinberger merged commit 1823aae into mainJun 26, 2026
36 checks passed

felixweinberger deleted the v2-2026-07-28 branch June 26, 2026 13:01

pablopupo mentioned this pull request Jul 2, 2026
fix(client): fire onerror only once when the standalone GET stream fails #2418
Open
6 tasks

wille mentioned this pull request Jul 6, 2026
Support RFC 9207 issuer identification (iss parameter) wille/mcp-oauth-server#4
Merged

mcp-claudeBot mentioned this pull request Jul 9, 2026
Step-up authorization (403 insufficient_scope) dead-ends with SdkHttpError when a refresh_token is present #2255
Open

khandrew1 mentioned this pull request Jul 10, 2026
v2: modern-era Client drops inbound extension-method requests registered via setRequestHandler #2478
Closed

evdbogaard mentioned this pull request Jul 17, 2026
Mid-session re-auth after refresh-token expiry dead-ends: send() gets "REDIRECT" and throws UnauthorizedError without ever exchanging the new code #2510
Open

he-yufeng mentioned this pull request Jul 27, 2026
fix: replay request SSE responses after disconnect #2207
Closed

ondraulehla mentioned this pull request Jul 27, 2026
InMemoryEventStore: standalone-stream resume broken by getStreamIdFromEventId split #2560
Open

This was referenced Jul 30, 2026
fix(server): settle in-flight JSON-mode requests on transport close #2584
Draft
Streamable HTTP: JSON-response-mode stream mappings never complete their lifecycle #2559
Open
fix(server): settle in-flight JSON-mode requests on transport close (v1.x) #2588
Draft

claudeBot mentioned this pull request Aug 27, 2026
docs(client): correct the registerClient deprecation citation to spec PR #2858 #2729
Open

Navigation Menu

Uh oh!

Implement MCP 2026-07-28 - #2286

Implement MCP 2026-07-28#2286
felixweinberger merged 66 commits into
mainfrom
v2-2026-07-28

felixweinberger commented Jun 12, 2026•
edited
Loading

Uh oh!

changeset-botBot commented Jun 12, 2026•
edited
Loading

Uh oh!

pkg-pr-newBot commented Jun 12, 2026•
edited
Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

felixweinberger commented Jun 12, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

SEPs implemented

Stateless protocol

Multi-round-trip requests

Transport

Schema

Authorization

Removed

Backward compatibility

Migration

Breaking Changes

Types of changes

Checklist

Uh oh!

changeset-botBot commented Jun 12, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-newBot commented Jun 12, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

felixweinberger commented Jun 12, 2026•
edited
Loading

changeset-botBot commented Jun 12, 2026•
edited
Loading

pkg-pr-newBot commented Jun 12, 2026•
edited
Loading