MCP July 2026 Changes: How to Migrate to TypeScript SDK v2

The MCP specification dated 2026-07-28 is a major shift toward a stateless request/response core.

📑Table of Contents

1. Change map at a glance
2. What actually changed in MCP 2026-07-28
3. TypeScript SDK v2: try path and compatibility caveats
4. Cross-check from C# and infrastructure vendors
5. Migration checklist and next actions
6. FAQ
7. Key takeaways

Key moves

• Retire initialize / initialized and Mcp-Session-Id
• Carry protocol version and capabilities in per-request _meta
• Ship server/discover, Multi Round-Trip Requests (MRTR), and Mcp-Method / Mcp-Name headers
• Add cacheable list/read hints (ttlMs / cacheScope), authorization hardening, and a minimum 12-month deprecation window

What this article covers

Differential value

The differential value is not a single-source news paraphrase. This article cross-checks the official MCP blog and changelog, the TypeScript SDK v2 monorepo, Cloudflare Agents SDK notes, Microsoft’s C# SDK v2.0 announcement, and independent coverage into a migration decision matrix: separate breaking transport changes (fix now) from time-boxed deprecations (plan inside the 12-month window), and decide whether to adopt TypeScript SDK v2 server/client packages now or after regression.

Reader next action

Reader next action: run the migration checklist—cut initialize and session dependencies, adopt TypeScript SDK v2 server and client packages, implement discover and MRTR, then plan deprecated feature removal inside the 12-month window.

Learning outcomes

---

Change map at a glance

Sessions, handshake, and capability probe

Area	Typical pre-2026-07-28	2026-07-28	Ops note
Sessions	Streamable HTTP after initialize with Mcp-Session-Id; sticky often assumed	Protocol-level session / Mcp-Session-Id removed	Pass app state via server-minted handles in tool args
Handshake	initialize / initialized	Removed; version/capabilities on every request _meta	Clients must rebuild request assembly
Capability probe	Mostly negotiated at init	server/discover (changelog: MUST)	Plan legacy initialize fallback for older peers

Interactive tools and routing

Area	Typical pre-2026-07-28	2026-07-28	Ops note
Interactive tools	Server-initiated input on long-lived sessions	MRTR: resultType: input_required then retry with inputResponses	Continuity moves into the payload
Routing	Often requires reading JSON-RPC body	Mcp-Method / Mcp-Name (optional Mcp-Param-*)	LB/WAF can route without deep packet inspection

Cache, auth, and legacy features

Area	Typical pre-2026-07-28	2026-07-28	Ops note
Caching	Weak guidance for lists	ttlMs / cacheScope	Edge/CDN list caching becomes designable
Auth	DCR-heavy paths still common	Issuer validation; DCR deprecated toward CIMD; credential issuer binding	Schedule client work inside the 12-month window
Tasks / legacy	Tasks closer to core; older HTTP+SSE	Tasks moved to extension; Roots/Sampling/Logging and old HTTP+SSE deprecated ≥12 months	Plan removals; do not treat every deprecation as day-zero delete

TypeScript and reference implementations

Area	Typical pre-2026-07-28	2026-07-28	Ops note
TypeScript	Monolithic v1.x common	v2 split @modelcontextprotocol/server / client; v1 kept ≥6 months for bugfix/security	Framework middleware for Express/Fastify/Hono/Node HTTP
Reference impls	Sticky / Durable Object-heavy patterns	Workers can expose tools without transport sessions	McpAgent described as feature-frozen / deprecated

Sources

Sources (as of July 2026):

Official and SDK sources

• MCP Blog (2026-07-28)
• spec changelog
• TypeScript SDK
• Cloudflare Agents SDK changelog
• Microsoft.NET Blog (C# SDK v2.0)

Independent coverage

• GIGAZINE
• InfoWorld
• TechTarget Japan

---

What actually changed in MCP 2026-07-28

The core story is operational: stop depending on a long-lived protocol session to keep MCP traffic healthy under load balancing. The official blog frames a stateless core that can round-robin requests to any healthy instance.

Removed

• initialize / initialized (SEP-2575)
• Mcp-Session-Id and protocol sessions (SEP-2567)
• Implicit cross-call protocol state—use explicit server-minted handles in tool arguments instead

How older deployments typically looked:

• Initialize, then stamp Mcp-Session-Id on every request and prefer sticky routing (Microsoft’s C# SDK write-up contrasts this with the new per-request metadata model)
• Enterprise fleets move away from sticky pinning toward horizontally scaled fleets behind a load balancer (TechTarget Japan)

Added or strengthened

• server/discover for capability probing (changelog language: MUST)
• MRTR: required resultType of complete or input_required; clients retry the original call with inputResponses (SEP-2322)
• Routing headers on Streamable HTTP: Mcp-Method / Mcp-Name (SEP-2243)
• Cache hints on list/read: ttlMs / cacheScope (SEP-2549)
• Authorization: issuer validation (RFC 9207 family), DCR deprecated toward CIMD, credential issuer binding
• Tasks relocated to the io.modelcontextprotocol/tasks extension (SEP-2663)

How to read the deprecation policy

Roots, Sampling, Logging, legacy HTTP+SSE, and DCR enter a formal deprecation registry with a minimum 12-month window (SEP-2596).

Practical two-step approach:

1. Cut session/initialize dependencies first
2. Schedule deprecated feature removal inside the window rather than treating every deprecation as an emergency delete

Independent coverage context

Independent coverage (including GIGAZINE) notes same-day Tier-1 SDK support across TypeScript, Python, Go, and C#. Mentions of GitHub MCP Server “early” support or Claude product rollouts are reporting context, not a product matrix—verify each product’s own release notes.

---

TypeScript SDK v2: try path and compatibility caveats

New work vs existing v1

For new work, design on v2 (@modelcontextprotocol/server and @modelcontextprotocol/client).

• Existing v1: the official README states at least six months of bugfix/security maintenance
• Safer path: regress in a non-sensitive environment before production cutover

Package layout and docs

The modelcontextprotocol/typescript-sdk main branch is the v2 line implementing 2026-07-28.

• Thin middleware packages for Express, Fastify, Hono, and Node HTTP
• Schemas follow Standard Schema (including Zod v4)
• Docs are split between v2 and v1 URLs

Suggested try order

1. Switch dependencies to the split v2 package names
2. Remove initialize handshake code; verify per-request _meta and server/discover
3. Confirm Mcp-Method / Mcp-Name are present on tool-call paths (middleware or custom HTTP)
4. Rewrite interactive tools that need user input onto MRTR (input_required)
5. Move state previously keyed by session ID into handles or an external store
6. During the v1 coexistence window, run regression covering list caching and OAuth issuer checks

Cloudflare Agents SDK v0.20.0 notes

Cloudflare’s 2026-07-27 changelog independently describes Agents SDK v0.20.0 adopting the 2026-07-28-era client/server packages:

• Workers can serve tools/prompts/resources/elicitation without MCP transport sessions or Durable Objects for that path
• Clients using @modelcontextprotocol/client probe with server/discover, then fall back to legacy initialize on the same connection when needed
• Servers use a factory + createMcpHandler pattern to isolate a server per request
• McpAgent is described as feature-frozen / deprecated, with guidance for dual legacy routes and isLegacyRequest

TypeScript / Cloudflare sources

Sources (July 2026):

• TypeScript SDK repository
• Cloudflare changelog

---

Cross-check from C# and infrastructure vendors

If you only read the TypeScript packaging change, you might miss the infrastructure thesis. Microsoft’s MCP C# SDK v2.0 and Cloudflare’s sessionless Workers pattern tell the same story in different stacks.

Microsoft MCP C# SDK v2.0

The.NET Blog states HTTP transport defaults to Stateless = true.

Key points:

• Drops handshake and session headers; carries version/capabilities per request
• MRTR is a headline feature so interactive flows no longer require long-lived sessions
• SEP-2243 headers let ordinary LB/WAF layers route without reading the JSON-RPC body
• Backward-compatible where possible, while recommending stateless as the forward-compatible default

Independent coverage (InfoWorld)

InfoWorld independently reports the same trio:

• Stateless-by-default transport
• Standardized routing headers on tools/call
• MRTR for interactive tools without durable sessions

It also flags end-to-end authn/z and OAuth/OIDC alignment as the next focus area.

Source

Comparison for adoption decisions

Stack comparison table

Lens	TypeScript SDK v2	C# SDK v2.0	Cloudflare Agents SDK
Primary audience	Node / edge TS	.NET servers	Workers operators
Packaging	server/client split	Official MCP C# SDK v2	Agents SDK v0.20.0 + MCP packages
Stateless default	2026-07-28 implementation	Stateless=true default	Sessionless Workers pattern
Migration assist	v1 maintained ≥6 months	Backward compatibility emphasized	discover → legacy initialize; dual routes
Infra win	Middleware set	Header-based LB/WAF	Horizontal scale without DO sessions

Sources for this section

Sources (July 2026):

• Microsoft.NET Blog
• InfoWorld
• Cloudflare changelog
• MCP Blog

---

Migration checklist and next actions

These are the actionable next steps. Run the migration checklist before production traffic: cut initialize and session dependencies, adopt TypeScript SDK v2 server and client packages, implement discover and MRTR, then plan deprecated feature removal inside the 12-month window.

Practical checklist

Protocol and transport

• ✓ Inventoried clients/servers for initialize or Mcp-Session-Id dependencies
• ✓ Revisited sticky-session / shared session-DB load-balancer assumptions (remove or replace with handles)
• ✓ Implemented server/discover and decided legacy initialize fallback policy for older peers
• ✓ Redesigned interactive tools around MRTR input_required
• ✓ Ensured HTTP paths emit Mcp-Method / Mcp-Name (SDK middleware or custom)

Cache, auth, and language SDKs

• ✓ Decided whether list/read ttlMs / cacheScope change your cache topology
• ✓ Checked OAuth issuer validation and DCR usage; set a CIMD migration deadline
• ✓ Catalogued Roots/Sampling/Logging / legacy HTTP+SSE usage and wrote a 12-month removal plan
• ✓ For TypeScript: planned cutover to @modelcontextprotocol/server / client plus v1 coexistence regression
• ✓ Ran integrated tests for discover, MRTR, headers, and auth in a non-sensitive environment

Priority bands

1. Now: cut session/initialize coupling, emit routing headers, MRTR-enable interactive tools
2. Planned (12-month window): remove deprecated features, DCR→CIMD, retire legacy transports
3. Product follow: re-check Claude products and GitHub MCP Server on their official channels—press “rolling out” language is not a schedule

⚠️ Protocol-level sticky requirements fade; application consistency does not automatically disappear. If business state must be coherent across calls, make it explicit with handles or an external store.

---

FAQ

Q1. Is MCP 2026-07-28 a breaking change?

Yes for anything that assumed initialize plus protocol sessions/sticky routing. Deprecations such as Roots/Sampling/Logging still get a minimum 12-month window (official changelog/blog).

Q2. Should TypeScript projects jump to v2 immediately?

New work should target v2. Existing v1 has at least six months of bugfix/security support per the README—regress first, then cut over.

Q3. Is server/discover mandatory?

The official changelog marks it MUST. Clients should implement discover, and may keep a legacy initialize fallback for older peers (as Cloudflare documents).

Q4. What is MRTR versus older elicitation patterns?

The server returns input_required; the client retries the same call with inputResponses. Continuity lives in the payload rather than a long-lived session (official docs / Microsoft).

Q5. Are sticky sessions obsolete?

Protocol session-ID routing is no longer the design center. Keep sticky only if your app still needs instance affinity; prefer explicit handles/stores for app state (changelog / TechTarget Japan).

Q6. What should auth migrations check first?

Issuer validation, remaining DCR dependency, CIMD timeline, and credential issuer binding (official blog).

Q7. Are Claude products and GitHub MCP Server already fully on 2026-07-28?

Independent reports mention early GitHub MCP Server work and staggered product adoption. Treat those as hints and verify each product’s release notes.

---

Key takeaways

• 2026-07-28 is a stateless core change set: no initialize/session ID, plus discover, MRTR, routing headers, cacheable lists, harder auth, and a formal 12-month deprecation window.
• Differential value: official blog/changelog plus TypeScript SDK v2, Cloudflare sessionless Workers, and Microsoft C# SDK v2.0 form a multi-source migration decision matrix—not a single-article paraphrase.
• Next action: run the migration checklist—cut initialize and session dependencies, adopt TypeScript SDK v2 server and client packages, implement discover and MRTR, then plan deprecated feature removal inside the 12-month window.

Related reading

Related reading on agent harnesses and token efficiency: