chore(mcp): adopt MCP spec 2026-07-28 and TypeScript SDK v2

[zachdunn]

MCP spec 2026-07-28 shipped alongside the stable v2 TypeScript SDK (@modelcontextprotocol/server@2.0.0, @modelcontextprotocol/client@2.0.0); the monolithic @modelcontextprotocol/sdk is retired at v1. This tracks adopting it across our MCP surface. Sibling work in buildinternet/sunny: #773, Phase-1 PR #774.

Design doc: docs/superpowers/specs/2026-07-29-mcp-sdk-v2-design.md.

Where we stand

The headline breaking change costs us little. Protocol-level sessions are gone and MCP is stateless — each request carries its protocol version and client capabilities in reserved _meta keys. workers/mcp binds no Durable Objects, so the session state its current transport holds is already per-isolate and best-effort. Nothing durable depends on it. We use none of the deprecated features (Roots, Sampling, Logging, HTTP+SSE transport).

Our migration differs from sunny's in one structural way. Sunny hand-wires the SDK's own transport, so its PR is a direct SDK swap. We serve MCP through agents/mcp (the Cloudflare Agents SDK), which already did this migration upstream:

• agents@0.20.1 moves the MCP SDK from a hard dependency to peers on both v1 @modelcontextprotocol/sdk@1.30.0 and v2 @modelcontextprotocol/server@2.0.0 + /client@2.0.0.
• agents/mcp's createMcpHandler is now the stateless v2 handler taking an McpServerFactory. The sessionful SDK-v1 handler we use today (agents@0.17.3) is renamed createLegacyMcpHandler.

So Phase 1 is an agents bump plus a call-site change, not a transport rewrite. It also means the legacy leg sunny had to hand-wire (a second WebStandardStreamableHTTPServerTransport with enableJsonResponse: true, to stop 2025-era clients silently receiving SSE) is a single responseMode: "json" option for us.

Already compatible, verified against the v2 type surface: ResourceTemplate + its complete maps (slug-completion.ts), completable() on prompt args, tool annotations, and _meta — which is what carries the MCP Apps UI ui.resourceUri and the ui.csp resourceDomains allowlist (#1230). resultType is a wire-only discriminator, stripped from the handler-facing types, so tool callbacks are unaffected.

Mechanical churn: ~19 raw-shape inputSchema: { … } sites across mcp-agent.ts, follows-tools.ts, whats-changed-tool.ts become z.object(…), and withPagination() returns an object schema. Raw shapes still work via a deprecated overload, so this is de-risking rather than a blocker.

Side benefit: the zod: ~4.3.6 pin in workers/mcp exists only because SDK v1 nested its own copy (#1367). v2 declares zod ^4.2.0, so the pin should be droppable.

Plan

• Phase 1 — SDK v2 migration. ✅ Shipped in feat(mcp): adopt MCP 2026-07-28 via the v2 TypeScript SDK #2190 (merged 2026-07-29). Bump agents ^0.17.3 → ^0.20.1, drop the direct @modelcontextprotocol/sdk dep, add @modelcontextprotocol/server@^2.0.0 (+ /client for tests). Switch workers/mcp/src/index.ts to the stateless createMcpHandler(factory) with route, responseMode: "json", and explicit allowedOriginHostnames (the 0.20 wrapper does its own Host/Origin validation and custom domains are not covered by default). Set ttlMs: 3_600_000 / cacheScope: "private" cache hints on tools/list, prompts/list, resources/templates/list — static per deploy but auth-gated. Wrap tool/prompt schemas in z.object. Migrate tests/mcp-test-helpers.ts and the five suites on it to the v2 client; add modern-envelope (_meta + Mcp-Method/Mcp-Name) and legacy-initialize tests driving the real fetch handler. Refresh the carved-out workers/mcp/bun.lock. Update docs/architecture/mcp.md and workers/mcp/server.json.
• Phase 2 — auth: better-auth 1.7 + CIMD. DCR is deprecated in favor of Client ID Metadata Documents. better-auth implemented CIMD in better-auth/better-auth#9159, shipping in 1.7.0 — so this is gated on our own 1.6.23 → 1.7 upgrade, not on upstream. Bigger lift here than in sunny: we run api-key, passkey, stripe, oauth-provider, and organization plugins across workers/api and web. DCR stays spec-valid through the deprecation window. Own issue.
• Phase 3 — workers/mcp/ui + hardening. @modelcontextprotocol/ext-apps ^1.7.3 → 1.7.5 and its own SDK copy; regenerate the committed release-feed bundle (separate carved-out build with its own lockfile). The server-side _meta contract is unchanged, so the UI keeps working untouched during Phase 1. Consider Mcp-Method-based rate-limit rules now that the method is a header and needs no body parsing.

Not in scope

subscriptions/listen — that is #346, a real feature request, not a migration item. No feature flag: this is a dependency migration with no runtime toggle worth the permanent registry entry.

[zachdunn]

Phase 1 shipped — #2190, merged 2026-07-29 (303faf1e)

mcp.releases.sh now speaks MCP 2026-07-28 via @modelcontextprotocol/server@2.0.0 through agents@0.20.1's stateless createMcpHandler. Deploy is automatic.

Two findings worth carrying into Phase 2/3, because both contradict what this issue originally assumed:

1. Legacy MCP replies are SSE-framed, not plain JSON — and always were. The design claimed responseMode: "json" would preserve "today's plain-JSON replies," making sunny's hand-wired second transport leg unnecessary for us. Both halves were wrong:

• responseMode: "json" reaches only the 2026-07-28 leg. The SDK's legacy fallback constructs its own transport without enableJsonResponse.
• agents@0.17.3 — what we replaced — returned Content-Type: text/event-stream on every response path (dist/mcp/index.js 255, 334, 454, 476, 485).

So legacy clients have always received SSE from this worker, nothing regressed, and no legacy transport was hand-wired. docs/architecture/mcp.md#transport is the authoritative account; the spec and plan carry dated in-place corrections rather than retroactive rewrites.

The general lesson for the remaining phases: sunny is reliable prior art for what to do and unreliable for what our current state is. Three separate claims in the design were wrong in the same direction, all from assuming sunny's pre-migration behaviour matched ours.

2. Version authority in workers/mcp is a three-way, not two-way, relationship. server.json (registry metadata) must match the version in createServer's McpServer constructor (mcp-agent.ts) — that is what clients see on connect. workers/mcp/package.json is inert (private: true, never published) and has drifted behind deliberately. Documented in mcp.md; bump the first two together and leave the third alone.

Correction to the PR description: it stated this also closes #1367. It does not — #1367 was already closed on 2026-06-08. The zod pin was relaxed here (~4.3.6 → ^4.4.3, installing 4.4.3, no dual-zod type split), so the underlying concern is resolved, but the issue link was wrong.

Carried follow-ups (non-blocking, from review)

• allowedOriginHostnames omits the portless worktree-prefixed local form (<branch>.mcp.releases.localhost). Browser-origin MCP clients in a worktree get rejected; non-browser clients send no Origin and are unaffected. Local dev only.
• parseSseJsonRpc in workers/mcp/test/protocol.test.ts reads only the first data: line and does not strip CRLF — fine against current SDK behaviour, fragile if a keep-alive frame ever precedes the payload.
• Cache-hint coverage asserts tools/list only; a typo in the prompts/list or resources/templates/list key would silently no-op that hint. All three share one constant, so the blast radius is small.
• Relaxing the zod pin left four nested private zod@4.3.6 copies under the MCP SDK subpackages. Measured cost ~3 KiB gzipped (the bundler dedupes), and they exist with the pin restored too. Revisit only if a future zod major moves on either side.

Verification gap

The live bun run mcp:inspect:local run against a real MCP client was not performed — it is an interactive browser UI. Compensating evidence: workers/mcp/test/protocol.test.ts drives the real index.ts fetch handler for both wire eras, and the worker bundles clean (wrangler deploy --dry-run, 5115.86 KiB / gzip 1282.61 KiB). Worth doing opportunistically now that this is live.

Phases 2 and 3 remain open as described above.