docs: plan migration to MCP 2026-07-28 and official SDK v2 - #321
Draft
tomber wants to merge 2 commits into
Draft
Conversation
The 2026-07-28 protocol revision is only reachable through the official
TypeScript SDK v2, which splits @modelcontextprotocol/sdk into
@modelcontextprotocol/{core,server,client,node,express,...}. Only
@solvapay/mcp imports the official SDK, so the internal blast radius is
small, but the peer dependency rename is breaking for every integrator.
Documents the file-level work, the @modelcontextprotocol/ext-apps
blocker (v2 migration is three unmerged upstream PRs), and recommends a
single clean cut with the 0.2.x line deprecated rather than
dual-targeting v1 and v2.
Co-authored-by: Tommy <tommy.berglind@gmail.com>
The MCP 2026-07-28 revision is reachable only through the official SDK v2, which splits `@modelcontextprotocol/sdk` into scoped packages and drops the stateful handshake. `@solvapay/mcp` now builds on `@modelcontextprotocol/core` and `/server`, and `createSolvaPayMcpFetchHandler` takes a per-request `factory` instead of a shared `server`, with `responseMode` replacing the hand-maintained `McpHandlerMode`. 2025-era hosts keep working through the SDK's zero-cost `legacy: 'stateless'` leg. `@modelcontextprotocol/ext-apps` has no v2 build, so its three server-side symbols are vendored and re-exported from `@solvapay/mcp` — merchants writing MCP Apps tools would otherwise have no v2-compatible import. The Express examples lose their session maps and `isInitializeRequest` routing entirely in favour of `toNodeHandler`, which streams SSE and forwards `req.auth` as `authInfo`. Two latent typing bugs surfaced and are fixed: `Parameters<registerTool>` resolved to v2's *deprecated* raw-shape overload, and `InferHandlerArgs` collapsed raw-shape schemas to `Record<string, unknown>` so merchant `registerPayable` handlers saw `unknown` args. Fixing both removed three casts and an `as any`. BREAKING CHANGE: the `@modelcontextprotocol/sdk` peer is replaced by `@modelcontextprotocol/core` + `/server` (^2.0.0), `zod` requires ^4.2.0, `engines.node` is >=20, and `createSolvaPayMcpFetchHandler`'s `server` and `mode` options are replaced by `factory` and `responseMode`. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds
.cursor/plans/mcp_2026_07_28_sdk_v2_migration.plan.md— a migration plan for the MCP2026-07-28protocol revision and the official TypeScript SDK v2.Planning only. No source changes.
Headline finding: the 2026-07-28 revision is only reachable through SDK v2, which replaces the single
@modelcontextprotocol/sdkpackage with a scope of split packages (@modelcontextprotocol/core,/server,/client,/node,/express, …). Published v11.29.xtops out at protocol2025-11-25, so there is no incremental path.Recommendation: single clean cut to v2, no dual-targeting. v1 and v2 objects cannot cross (
instanceofand nominal types do not survive the boundary), so supporting both means two parallel implementations of the handler, tool registration and server builder selected at build time. We are pre-revenue on these packages,@solvapay/mcpis0.2.8, and integrators who cannot move keep installing the v1 peer under its own name. Deprecate0.2.x, ship0.3.0.Scheduling constraint is upstream, not us.
@modelcontextprotocol/ext-apps@1.7.5(released four days ago) still peer-depends on@modelcontextprotocol/sdk@^1.29.0; its v2 migration is three competing unmerged PRs (#710, #719, #720) with an unresolved architectural disagreement. We use exactly three symbols from it (registerAppTool,registerAppResource,RESOURCE_MIME_TYPE, ~40 lines of real logic upstream), so vendoring is the recommended hedge.Type of Change
Related Issues
N/A
Changes Made
@solvapay/mcp,@solvapay/mcp-coreand@solvapay/server, with code references to the specific call sites that break@solvapay/mcpimports the official SDK) is what keeps the internal blast radius to ~15 filescreateMcpHandler's per-request server factory deletes the shared-server mutex inpackages/mcp/src/fetch/handler.ts, andMcpRequestContext.requestInforetires the private_requestHandlersreach-in inpackages/mcp-core/src/hideToolsByAudience.tshideToolsByAudience'sgetClientVersion()fallback stops working on the modern era, becauseinitializenever runs therecreateMcpHandler's defaultlegacy: 'stateless'so 2025-era hosts keep working at the protocol layer rather than in our package matrix'sse-stateful'default, ChatGPT connector behaviour, unaudited_metaconventions)Changeset
Testing
2.0.0-beta.5manifests and the SDK's owndocs/migration/guides, and confirmed every cited line number against the working treeChecklist
Additional Notes
Written against SDK
2.0.0-beta.5(published 2026-07-21) and the spec release candidate. The final spec publishes 2026-07-28, so the stable2.0.0is imminent but not out yet — the plan's Phase 1 spike pins the beta exactly to absorb any remaining churn.