Migrating to MCP 2026-07-28: An Interface Checklist

Treat an MCP protocol migration as an interface release, not a package update. Inventory the clients and protocol versions in use, compare normative changes, update the official SDK, rerun contract and authority tests, validate each named client, and keep the previous version available until evidence supports cutover.

Begin with the deployed truth

Record:

server SDK and exact version,
protocol versions actually negotiated,
transport and session mode,
OAuth metadata and supported client-registration path,
tool and resource catalog,
clients and models used in production,
and the last accepted compatibility report.

The Permadyn operations lab currently uses the stable TypeScript SDK version recorded in its package lock. The release report records the negotiated protocol version; the site does not claim 2026-07-28 compatibility until that path is exercised by the deployed server and named clients.

That distinction matters. A current specification link is not compatibility evidence.

Read the normative diff

Review the official release notes and specification sections relevant to your surface:

Lifecycle and version negotiation
Streamable HTTP behavior
Authorization and protected-resource discovery
Tool input, output, and annotations
Resources and MCP Apps UI metadata
Error semantics and capability negotiation
Security guidance

Map each change to code, tests, documentation, client validation, or “not applicable” with a reason.

Update the adapter without moving domain rules

Protocol upgrades should rarely rewrite core product authority. Case versions, permissions, confirmation binding, idempotency, and audit records belong in the domain service.

domain service and policy
        ↑ stable contract
MCP adapter vCurrent ── MCP adapter vNext
        ↑                         ↑
current clients             migration clients

Keeping the adapter thin allows both versions to exercise the same product rules during transition.

Re-run the release matrix

At minimum, test:

initialize and protocol negotiation,
unauthenticated discovery and OAuth challenge,
authorization-code flow with PKCE,
tool catalog equality or reviewed diff,
every declared input and output schema,
UI resource discovery and rendering,
read-only and write-scope behavior,
preview and explicit confirmation,
stale, replay, and idempotency handling,
latency and error recovery,
and the complete golden workflow in each claimed client.

Include one independent MCP client that does not rely on platform-specific UI. This distinguishes protocol compatibility from a single host’s integration behavior.

Roll out with evidence

Prefer a staged release:

Run offline and local contract tests.
Exercise a non-production synthetic tenant.
Validate named clients against the candidate endpoint.
Compare reports with the accepted release.
Route limited production traffic if the workflow permits it.
Monitor errors, latency, auth failures, and outcome changes.
Retire the old path only after the rollback window closes.

If one client lags the protocol, document the supported intersection or maintain a compatibility adapter. Do not quietly downgrade security or remove confirmation to preserve a marketing claim.

Document exactly what is supported

A precise compatibility statement names the server release, protocol version, authentication mode, client version, tool surface, and test date. “Works with MCP” is too broad to operate.

Watch authorization during migration

Protocol and authorization changes often arrive near one another, but they should be tested independently. Verify that an unauthenticated MCP request still returns the correct protected-resource challenge. Follow that metadata to the intended authorization server. Confirm that resource indicators, audience validation, PKCE, redirect URI matching, scope consent, expiry, and token replay behavior remain intact.

Run the workflow with a read-only token as well as a read-write token. A catalog may be visible while individual operations enforce different scopes, or the catalog itself may be filtered by authorization policy. Record the intended behavior so clients do not mistake a permission change for a missing tool.

Do not solve a migration problem by forwarding the MCP bearer token to a downstream product API. A token issued for the MCP resource has that audience. If the adapter needs another credential, design that exchange explicitly and test the second trust boundary.

Keep the rollback useful

A rollback path is only useful if the old server can still understand the product state created during the candidate period. Avoid migrations that write a new irreversible state shape before the server and clients are accepted. Where state changes are necessary, use forward-compatible fields, versioned records, or a reversible data migration.

Keep the previous contract report next to the candidate report. When a regression appears, this makes it possible to distinguish a protocol change from an unrelated model, prompt, API, or data change.

Claim boundary

This is a migration framework, not evidence that the current Permadyn demo already supports a future protocol version. The live reference and Interface CI report are the sources of compatibility truth; claims will change only after those tests pass.