MCP 2026-07-28: Six Breaking Changes and the New MCP Apps Primitive

The 2026-07-28 MCP Release Candidate is locked. The final spec ships in 24 days — July 28 — and it is the largest revision to the Model Context Protocol since launch. If you run an MCP server in production, six things will break. If you've been waiting for a first-class way to ship interactive UIs from your tools, the wait is over: MCP Apps is now in the spec.

This post covers what changed, why it matters, what breaks, and the exact steps to migrate before the final spec lands.

Why this release is different

Every prior MCP release added capabilities on top of the original session-oriented design. The 2026-07-28 spec removes the session entirely and reorganizes the protocol around three new principles: every request is self-contained, tools can declare UIs, and extensions ship independently of the core spec.

The protocol spec has shipped steadily since launch but always carried an uncomfortable tension: the session model was a good fit for stdio and long-lived desktop connections, and a bad fit for HTTP, edge functions, and anything behind a load balancer. The stateless core resolves that tension for good.

Sessions are gone

The initialize /initialized handshake is gone. Mcp-Session-Id is gone. The protocol-level session is gone. Client metadata — capabilities, protocol version, trace context — now travels in a _meta field on every request.

// OLD — capabilities cached in session state
const caps = server.session?.clientCapabilities;
const version = server.session?.protocolVersion;

// NEW — read from request _meta (stateless)
const caps = request.params._meta?.clientCapabilities ?? [];
const version = request.params._meta?.protocolVersion ?? "2024-11-05";

The immediate infrastructure consequence: you no longer need Redis session stores, sticky sessions in your load balancer, or deep packet inspection at the gateway. Any server instance can handle any request. Round-robin just works.

Application-level state still exists — it just has to be explicit now. Tools return handles (a basket_id, a task_handle) and clients pass them back as arguments on subsequent calls. State is visible in the payload, not hidden in a session.

MCP Apps: the new interactive UI primitive

MCP Apps (SEP-1865) is the headline new feature. Tools can now declare interactive HTML interfaces that hosts render in sandboxed iframes. The spec makes this a first-class primitive rather than a workaround, and wires it directly into the existing JSON-RPC audit path.

The design is deliberately conservative. Tools declare their UI templates ahead of time — the host can prefetch, cache, and security-review them before anything runs. When the UI fires an action, it goes through the same consent and permission flow as a direct tool call. There is no new attack surface; there is a new rendering layer on top of the existing one.

{
  "name": "deploy_preview",
  "description": "Deploy a preview environment and open it in a browser.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "branch": { "type": "string" }
    },
    "required": ["branch"]
  },
  "ui": {
    "template": "deploy-preview-ui",
    "entrypoint": "index.html",
    "sandbox": ["allow-scripts", "allow-same-origin"]
  }
}

The iframe communicates back to the host over the same JSON-RPC base protocol: a button click that calls tools/call goes through identical consent mechanics as a direct agent invocation. This is the first spec-blessed way to ship configuration forms, data previews, and approval workflows inside a host without bespoke integrations.

The six breaking changes

Not all changes are additive. These six will cause failures in production servers that don't update before July 28:

1. Sessions eliminated

Any code reading from server.session or storing per-client state in session objects will break. Migrate session reads to request.params._meta.

2. New required HTTP headers

Every HTTP request must include Mcp-Method (the JSON-RPC method, e.g. tools/call) and Mcp-Name (the named operation within that method). Servers in the final spec reject requests where header values contradict the body. MCP-Protocol-Version: 2026-07-28 is also required.

3. Error code change

Missing-resource errors move from the MCP-custom -32002 to the JSON-RPC standard -32602 (Invalid Params). Any client or server matching on the literal -32002 value needs updating.

4. Tool list caching formalized

tools/list responses can now carry ttlMs and cacheScope in their _meta. Clients that previously assumed tool lists were always fresh need to respect these new directives.

5. W3C Trace Context propagation required

The spec now mandates how traceparent headers propagate through MCP calls. Servers must extract the trace context from request.params._meta.traceContext.traceparent and pass it to their observability layer.

6. Three primitives deprecated

Roots, Sampling, and Logging are marked deprecated and moved to optional extensions. They still work — the deprecation window is 12 months — but the spec recommends tool parameters and resource URIs over Roots, direct LLM provider integration over Sampling, and stderr / OpenTelemetry over Logging.

Migration checklist

Run these in order. The security patch comes first regardless of everything else.

## Phase 1 — Security patch (do this first)
- [ ] Upgrade SDK: TypeScript >= 1.12.1, Python >= 1.8.0
      (patches April 2026 stdio RCE in older versions)

## Phase 2 — Stateless core
- [ ] Remove initialize/initialized handshake code
- [ ] Migrate all server.session reads → request.params._meta
- [ ] Remove Mcp-Session-Id header handling
- [ ] Remove sticky-session config from load balancer
- [ ] Wire W3C Trace Context from _meta.traceContext.traceparent

## Phase 3 — HTTP headers + error codes
- [ ] Add Mcp-Method and Mcp-Name headers to all HTTP responses
- [ ] Set MCP-Protocol-Version: 2026-07-28 on all responses
- [ ] Replace hardcoded -32002 with -32602 in error handlers

## Phase 4 — Caching
- [ ] Add ttlMs + cacheScope to tools/list responses
- [ ] Add ttlMs + cacheScope to read-only tool results
- [ ] Skip cache metadata on non-idempotent (write) tools

## Phase 5 — Schema upgrade
- [ ] Add $schema: "https://json-schema.org/draft/2020-12/schema" to all tool inputSchema
- [ ] Replace oneOf workarounds with if/then/else conditionals
- [ ] Add outputSchema declarations to all tools

## Phase 6 — Validate
- [ ] Run conformance suite against updated server
- [ ] Smoke test: request with _meta passes
- [ ] Smoke test: request without _meta still works (backwards compat)

The MCP Server Upgrade skill on skills-hub.ai automates phases 2–5 for TypeScript and Python servers. It reads your server, applies the changes above, and verifies backwards compatibility.

SDK betas and the conformance suite

Beta releases for the four Tier 1 SDKs are already live. Install them now to test against your server before the final spec locks.

# TypeScript
npm install @modelcontextprotocol/sdk@rc

# Python
pip install mcp==rc

# Go
go get github.com/modelcontextprotocol/go-sdk@rc

# C#
dotnet add package ModelContextProtocol --version *-rc*

The conformance suite validates all Standards Track SEPs against matching scenarios. Unlike previous spec versions where compliance was self-assessed, the 2026-07-28 spec requires a passing conformance run before any extension can reach Final status. Run it against your server:

npx @modelcontextprotocol/conformance run --server http://localhost:3000/mcp
# Reports pass/fail per-SEP with remediation guidance

What's next

After July 28 the three deprecated primitives — Roots, Sampling, Logging — begin their 12-month removal window. The governance policy (Active → Deprecated → Removed with 12-month minimums between phases) is now formally documented, so this is the last time a removal will come as a surprise.

The extensions framework is the more interesting medium-term story. New capabilities now ship as opt-in extensions with independent versioning before optionally entering the core spec. MCP Apps itself shipped this way — as SEP-1865 — before landing in the spec. Expect a wave of extension proposals from tool builders who were previously blocked by the slow core-spec update cadence.

If you maintain an MCP server, the migration window is open now. The SDK betas are live, the conformance suite is available, and July 28 is 24 days away. Start with the security patch and work down the checklist. The stateless migration is the largest single change, but it's also the one that pays the most dividends: simpler infrastructure, standard load balancing, and a server that's finally architected for the cloud it was always deployed in.

# Install the skill that guides you through building MCP Apps UIs
npx @skills-hub-ai/cli install mcp-apps-builder

# Or migrate your existing server automatically
npx @skills-hub-ai/cli install mcp-server-upgrade

Browse the integration skills on skills-hub.ai for the full MCP tooling catalog, or read the stateless protocol upgrade deep dive for the architectural reasoning behind the session removal.