Repository navigation
Track migration to MCP spec 2026-07-28 (stateless, MRTR, deprecated Sampling) #245
Description
Summary
The MCP spec released a new revision on 2026-07-28 (announced at https://blog.modelcontextprotocol.io/posts/2026-07-28/) that moves from the stateful bidirectional protocol to a stateless request/response model. Key changes relevant to us:
- The
initialize/initializedhandshake and session IDs are eliminated; each request is self-describing. - Server-initiated elicitation is replaced by "Multi Round-Trip Requests" (MRTR).
- Sampling is deprecated.
- Roots and Logging are also deprecated.
- Header-based routing (
Mcp-Method,Mcp-Name), cacheable list results, tasks moved to an official extensions framework. - Security: RFC 9207 issuer validation required, shift from Dynamic Client Registration toward Client ID Metadata Documents (CIMD).
- Deprecations get a 12-month minimum window; legacy HTTP+SSE transport gets a year-long offramp. No fire drill, but not indefinite either.
As of this issue, @modelcontextprotocol/sdk on npm is still on the 1.x line (1.30.0 latest) — there is no separate 2.0.0 package. The new spec appears to be supported via 1.x releases, not a major SDK version bump.
Why this needs a dedicated pass, not an incidental bump
This directly affects features we've shipped recently in this repo:
directions_tool's route-selection elicitation andsearch_and_geocode_tool's disambiguation elicitation are both built onserver.elicitInput(...)— the exact mechanism MRTR replaces.ground_location_tool's grounding-strategy detection is built onserver.createMessage(...)(Sampling) — deprecated outright.
Migrating means redesigning these three UX features against whatever MRTR's actual API surface turns out to be, not just bumping a dependency version.
What to check before starting
- Confirm real client support for MRTR (Claude Desktop, Claude Code, VS Code Copilot) — no point redesigning against a mechanism clients can't use yet.
- Read the SDK's actual migration guide/changelog for the TypeScript SDK version(s) that implement 2026-07-28 support.
- Check
hosted-mcp-server's OAuth flow for any Dynamic Client Registration dependency, given the spec's shift toward CIMD. - Decide whether
mcp-devkit-serverandmcp-docs-serverneed the same migration (devkit also uses elicitation per its own patterns; docs-server does not use elicitation/sampling as far as known — verify).
Non-goals for now
- No urgency given the 12-month deprecation window.
- The routine SDK dependency bump (
1.29.0→1.30.0) is handled separately and does not itself adopt the new spec — see the corresponding PR.
Activity
mattpodwysocki commentedon Aug 5, 2026
Correction/clarification: the "2.0" isn't a future release of `@modelcontextprotocol/sdk` — that package is being retired entirely. Per https://blog.modelcontextprotocol.io/posts/sdk-betas-2026-07-28/, TypeScript v2 splits it into separate focused packages (`@modelcontextprotocol/server`, `@modelcontextprotocol/client`), currently beta-only (`npm install @modelcontextprotocol/server@beta`), no stable release yet, with a dedicated codemod (`npx @modelcontextprotocol/codemod@beta v1-to-v2 .`) to help migrate.
So this migration is two layers, not one:
Given it's beta with no stable release and a provided codemod (a strong signal the API surface actually changed meaningfully, not just moved), this reinforces: no urgency, worth revisiting once v2 stabilizes.
chore: bump @modelcontextprotocol/sdk to 1.30.0 (#246)
mattpodwysocki commentedon Oct 21, 2026
Update (2026-10-21): some of the above is out of date, and there are more reasons to move now.
What changed
@modelcontextprotocol/server,/clientand/coreare at 2.3.1 (Oct 5), no longer beta. The codemod is at 2.3.1 too:npx @modelcontextprotocol/codemod v1-to-v2 .@modelcontextprotocol/ext-apps2.x has the v2 packages as peer dependencies. We're on ext-apps 1.x, so staying on v1 means no more MCP Apps updates forrender_map_tool.installSkills()at@modelcontextprotocol/server/ext/skills, and it targetsmain(v2) with no v1 backport mentioned. feat: serve skills over the MCP Skills extension (SEP-2640) #295 serves skills on v1 with hand-written handlers for now. Once we're on v2 and #2818 lands,installSkillsTobecomes a thin wrapper over the SDK's.Also in scope
patches/patches the v1 SDK so output schema validation logs a warning instead of failing the tool call. It needs redoing on v2, or dropping if v2 has an option for it.srcandtestimport@modelcontextprotocol/sdk/..., mostlytypes.js,server/mcp.jsandshared/protocol.js.@modelcontextprotocol/sdk^1.30.0 and imports our tools, so it has to move in the same release or SDK types won't line up across the package boundary.Proposed order
elicitInput(directions route selection, search disambiguation) and replacing Sampling inground_location_tool. This waits on MRTR support in the Claude clients.Step 1 is mostly mechanical, and step 2 is the redesign, so I'd keep them as separate PRs under this issue.
mattpodwysocki commentedon Oct 21, 2026
SDK v2 PRs are all up:
Release order: merge and release the four server packages, then bump all the pins in hosted together. Hosted can't run a mix: a v1 package registers fine on a v2 server but its tools read the token from the old spot, so calls go out without the user's token. Hosted#142 adds a test for exactly that, and it stays red until the pins move.
For clients nothing changes yet. Everything still negotiates 2025-11-25. Adopting the 2026-07-28 revision is still to do under this issue.
feat!: move to MCP TypeScript SDK v2 (#296)
test: fix all test type errors and typecheck tests in CI (#298)