Adopt Protocol Revision 2026-07-28

Purpose and Scope

Use this page when your project already uses the v2 split packages and you need to move a client, server, or host integration onto the 2026-07-28 protocol revision. This is not the same task as upgrading from the old monolithic package. The migration index separates those paths: package-surface migration starts with the v1-to-v2 guide and codemod, while protocol-era adoption is an architectural change involving negotiation, serving entry points, request envelopes, and wire compatibility choices. Start here only after imports, packages, and basic v2 construction already work in your application.

Sources: docs/migration/support-2026-07-28.md, docs/migration/index.md

The key constraint is explicit opt in. The support guide states that hand-constructed client and server objects keep speaking the 2025-era protocol by default. That default protects existing v2 code from accidentally placing a new revision on the wire. Adoption therefore requires a deliberate change at the connection or serving boundary, followed by review of behavior that differs by era. Treat this as a compatibility rollout: decide which peers can speak the modern era, which peers still require fallback, and which parts of your application read fields that were present only in earlier alpha wire shapes.

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

Relevant Source Files

• docs/migration/support-2026-07-28.md — Main migration guide for speaking the 2026-07-28 protocol revision from v2 code, including client negotiation, serving entry points, request state, auth, wire codecs, subscriptions, headers, cache behavior, and deprecated task vocabulary.
• docs/migration/index.md — Migration landing page that tells readers whether to start with the v1-to-v2 upgrade path or the 2026-07-28 adoption guide, and clarifies that protocol adoption is not codemod-automatable.
• docs/migration/upgrade-to-v2.md — Companion upgrade path for projects still on the old package surface before they attempt protocol-era adoption.
• docs/.vitepress/theme/index.ts — v2 documentation site theme entry that mounts the shared VitePress layout and banner for the current docs site.
• docs/v1/.vitepress/theme/index.ts — v1 documentation site theme entry that shares styling with the v2 site while preserving a separate v1 docs surface.
• docs/_meta/CONVENTIONS.md — Documentation authoring conventions that define the intended reader-facing style, structure, and migration-guide discipline.

Core Primitives

The migration guide names a small set of primitives you should recognize before editing code. A protocol revision is the wire-era spoken during connection setup and message exchange. Version negotiation is the client-side choice that probes, pins, or falls back between eras. A serving entry point is the server-side boundary that decides which protocol era an incoming connection can use. A per-request metadata envelope carries request information without relying on older per-session assumptions. Per-era wire codecs keep translation rules isolated so modern and legacy payloads do not leak into the same public application model.

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

The migration index lists the concrete adoption surface as per-request metadata envelopes, modern handler creation, stdio serving, version negotiation, multi-round-trip requests, and per-era wire codecs. That list is useful because it separates mechanical package migration from behavior migration. A codemod can rename imports and adjust many v1 APIs, but it cannot decide whether a host should probe for modern support, reject older peers, preserve fallback, or change server request state handling. Make those decisions at application boundaries where transport behavior, authentication context, and host compatibility are visible.

Sources: docs/migration/index.md

Client-Side Adoption Flow

On the client side, adoption starts with the connection handshake. The support guide says the default connection path performs the same 2025 initialize handshake as earlier behavior. To negotiate the modern era, pass version negotiation options when constructing the client. Automatic negotiation probes the server, uses the modern era when it recognizes support, and falls back to the 2025-era handshake when fallback remains allowed. Pinning the 2026-07-28 revision removes fallback, so connection fails against a peer that only supports the older era. Use pinning for controlled deployments and automatic negotiation for mixed fleets.

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

const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  { versionNegotiation: { mode: 'auto' } }
);
 
await client.connect(transport);
client.getProtocolEra(); // 'modern' | 'legacy'

The supported protocol version list shapes the automatic path. If your options contain modern entries, those entries become the candidates for the probe. If the list also contains a pre-2026 revision, the client can fall back when the probe does not positively identify a modern peer. If the list is modern-only, the same uncertainty becomes a connection failure rather than a silent downgrade. This distinction matters during staged rollout because an overly narrow supported list can turn a compatibility probe into an outage for older servers, while an overly broad list can hide that some traffic still uses the legacy era.

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

Probe behavior is intentionally conservative. The guide describes fallback when the probe does not positively recognize modern support, while still surfacing infrastructure failures such as network outages as typed connection errors. Timeouts depend on the transport rather than being treated as a single abstract failure mode. That means you should test the exact transports you deploy, especially stdio and HTTP, before changing defaults for production hosts. The important operational rule is to log the negotiated era after connection, then use those observations to decide when a fleet can move from automatic negotiation to a pinned modern revision.

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

Server-Side Adoption Flow

On the server side, choose the serving entry point that speaks the modern revision instead of assuming that an existing server object changes era automatically. The support guide frames serving the 2026-07-28 revision as an explicit migration path and points to protocol-version documentation for the full entry-point reference. The migration index calls out modern handler creation and stdio serving as part of this path. In practice, that means reviewing every place your application exposes MCP traffic, not only the business logic that registers tools, resources, or prompts.

Sources: docs/migration/support-2026-07-28.md, docs/migration/index.md

Server adoption also requires reviewing state assumptions. The support guide highlights replacement of per-session state with request state, auth changes for the 2026-07-28 era, and per-request metadata envelopes. Those topics belong together because modern requests can carry context differently from earlier code that cached wire or session details. Keep authorization context, request metadata, and handler-local state scoped to the request that needs them. Avoid reading wire-only envelope members directly from application code; the guide explicitly calls out earlier v2 alpha code that did this and treats it as a migration concern.

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

Compatibility Checklist

Use this checklist as a release gate rather than a reading list. First, confirm that the project uses v2 packages. Second, decide whether clients should probe or pin. Third, update server serving boundaries. Fourth, audit direct reads of wire-only members, task vocabulary, subscription behavior, cache fields, and headers called out by the guide contents. Fifth, run mixed-era tests so modern clients meet older servers, older clients meet modern-capable servers where supported, and infrastructure failures remain visible. This sequence reduces the risk that a successful local handshake hides an incompatible production peer.

Sources: docs/migration/support-2026-07-28.md, docs/migration/index.md

Documentation and Release Signals

The repository keeps v1 and v2 documentation surfaces separate while sharing VitePress styling. The current docs theme extends the default VitePress theme and adds a banner at the top of the layout. The v1 theme performs the same layout extension but imports shared custom styling from the v2 docs tree. For migration readers, that split reinforces an important product signal: v1 package migration and v2 protocol-era adoption are different tracks, even when their documentation sites share visual infrastructure. Use the migration landing page to choose the correct track before changing runtime behavior.

Sources: docs/.vitepress/theme/index.ts, docs/v1/.vitepress/theme/index.ts, docs/migration/index.md

The documentation conventions file is also relevant because it explains how the project wants migration pages to read: direct, task-oriented, and grounded in observable behavior. For this adoption path, that style maps to practical engineering work. Prefer small edits that expose what changed, such as enabling negotiation, logging the negotiated era, and replacing request state assumptions. Avoid broad rewrites that combine package migration, protocol adoption, and application feature changes in one pull request. Keeping those concerns separate makes failures easier to attribute and makes rollback safer when a peer cannot yet speak the modern era.

Sources: docs/_meta/CONVENTIONS.md, docs/migration/support-2026-07-28.md

Next Steps

If your project still imports the old monolithic package, start with the upgrade guide and codemod before adopting this protocol revision. If your project already uses the split packages, open the support guide and work through the client, server, auth, wire-codec, subscription, header, cache, and task-vocabulary sections against your actual transports. For production rollouts, begin with automatic negotiation where mixed peers exist, record the negotiated era, and pin the modern revision only after your compatibility evidence is strong. Then use the protocol-versions, serving, client-connect, and troubleshooting pages for deeper operational detail.

Sources: docs/migration/index.md, docs/migration/support-2026-07-28.md