chore: migrate to the v2 MCP SDK packages

[lukecotter]

Why

The MCP TypeScript SDK v2 is published, and this server is on v1. Everything that follows the 2026-07-28 revision — MRTR in #93, the caching fields in #94 — needs this swap first, and neither of those issues should own it.

The v2 SDK ships under new package names, which is why the old one looks stale:

@modelcontextprotocol/sdk	1.30.0, still declares LATEST_PROTOCOL_VERSION = '2025-11-25'
@modelcontextprotocol/server	2.0.0, carries 2026-07-28

@modelcontextprotocol/client and @modelcontextprotocol/core are published at 2.0.0 alongside it.

Do

Swap the dependency and move the imports. Nothing else — no behaviour change, no new protocol feature. Those land on top, in #93 and #94.

Five import sites, all of @modelcontextprotocol/sdk:

• src/server.ts — sdk/server/mcp.js, sdk/server/stdio.js
• src/tools/executeAnonymous.ts — sdk/server/mcp.js
• src/policy/orgExecutionPolicy.ts — sdk/server/mcp.js, sdk/client/index.js

McpServer and StdioServerTransport both survive, exported from @modelcontextprotocol/server/stdio, so the stdio entry point keeps its shape.

Try @modelcontextprotocol/codemod first — it ships v1-to-v2 transforms. Read the diff rather than trusting it.

Two things that are already in our favour

• zod is not a problem. @modelcontextprotocol/server@2.0.0 needs zod ^4.2.0 and we are on 4.4.3.
• createRequestStateCodec is exported from the package root. feat: carry the execute_anonymous confirmation over multi round-trip requests #93 requires an integrity-protected requestState binding the confirmed Apex source and the org id. The SDK provides the codec, so that requirement does not need hand-rolled crypto.

Acceptance

• pnpm run build, pnpm test and pnpm run eval all pass with no golden re-recorded. A changed golden means the swap changed a response, which is out of scope for this issue and must be explained before it is accepted.
• The tools/list definition budget is unmoved, for the same reason.
• @modelcontextprotocol/sdk is gone from package.json.

Effort

S–M. Its own commit, before #93, so a regression in the migration is not tangled with a change in the authorization flow.

[lukecotter]

How the v2 packages were verified, 2026-08-04

Recording this because the obvious check says the opposite. @modelcontextprotocol/sdk looks stale, and reading only that is how this work got mis-filed as "blocked on the SDK" in the first place.

The old package is not the new package:

$ npm view @modelcontextprotocol/sdk version dist-tags --json
{ "version": "1.30.0", "dist-tags": { "latest": "1.30.0" } }

$ npm view @modelcontextprotocol/sdk versions --json | tail -3
  "1.29.0",
  "1.30.0"
]

No 2.x is published under that name, and the installed 1.29.0 confirms the era:

$ rg "LATEST_PROTOCOL_VERSION|SUPPORTED_PROTOCOL_VERSIONS" node_modules/@modelcontextprotocol/sdk/dist/esm/types.js
export const LATEST_PROTOCOL_VERSION = '2025-11-25';
export const SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, '2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07'];

The v2 line ships as three new scoped packages, all at 2.0.0 latest:

$ for p in @modelcontextprotocol/server @modelcontextprotocol/client @modelcontextprotocol/core; do npm view "$p" dist-tags --json; done
{ "latest": "2.0.0" }
{ "latest": "2.0.0" }
{ "latest": "2.0.0" }

Against the published @modelcontextprotocol/server@2.0.0 tarball, not the git tag:

$ npm pack @modelcontextprotocol/server@2.0.0 && tar xzf *.tgz
$ rg -o "2026-07-28|2025-11-25" -N package/dist | sort | uniq -c
 117 package/dist/createMcpHandler-CLhGwQTn.d.mts:2026-07-28
  25 package/dist/createMcpHandler-CLhGwQTn.d.mts:2025-11-25
 ...

$ rg -l "InputRequiredResult|inputRequests|requestState" package/dist
package/dist/index.cjs
package/dist/createMcpHandler-CLhGwQTn.d.mts
package/dist/mcp-DXXb3Vv3.mjs
...

$ rg -o "cacheScope|ttlMs" -N package/dist | sort -u
package/dist/createMcpHandler-CLhGwQTn.d.mts:cacheScope
package/dist/createMcpHandler-CLhGwQTn.d.mts:ttlMs
...

So MRTR (#93) and the caching fields (#94) are both in the shipped type surface, and both eras are present in one package.

Entry points and dependencies, from the same tarball:

$ jq -r '.exports | keys[]' package/package.json
.
./_shims
./stdio
./validators/ajv
./validators/cf-worker

$ rg -o "McpServer|StdioServerTransport|createMcpHandler" -N package/dist/stdio.d.mts | sort -u
McpServer
StdioServerTransport
createMcpHandler

$ jq '{dependencies}' package/package.json
{ "dependencies": { "zod": "^4.2.0", "@modelcontextprotocol/core": "2.0.0" } }

createRequestStateCodec is exported from the package root — see #93.

Era fall-back

docs/protocol-versions.md at v2.0.0-beta.1 documents the client side, which corrects the urgency argument in #93:

Point the same options at a 2025-only server and connect() falls back to the initialize handshake on the same connection — one extra round trip, no error.

That applies to clients using versionNegotiation: { mode: 'auto' }. Clients that do not auto-negotiate still hit the compatibility cliff.