Skip to main content
All posts

MCP TypeScript SDK v2 Migration Guide for MCP Apps (November 2026)

Abe Wheeler
MCP AppsMCP App FrameworkMCP App TestingChatGPT AppsChatGPT App FrameworkChatGPT App TestingClaude ConnectorsClaude Connector FrameworkClaude Connector TestingMCP TypeScript SDKMCP SDK v2ext-apps 2TypeScriptMigration
MCP TypeScript SDK v2 splits server, client, schema, and runtime adapters while keeping the MCP App view protocol separate.

MCP TypeScript SDK v2 splits server, client, schema, and runtime adapters while keeping the MCP App view protocol separate.

The MCP TypeScript SDK v2 changes the server code under an MCP App. The single @modelcontextprotocol/sdk package becomes a set of smaller packages, Node.js 20 becomes the minimum, some registration APIs change, and transport imports move.

When this guide first ran in July, you could move the server to v2 and leave the MCP Apps SDK on 1.x. That is no longer the right plan. @modelcontextprotocol/ext-apps 2.x now peers on the v2 packages, so the server SDK and the MCP Apps SDK move together. The good news is that the bridge between your view and ChatGPT, Claude, or another host did not change on the wire, so most view code needs only small edits.

TL;DR: Run the official codemod (--dry-run first), then review its work. Upgrade @modelcontextprotocol/ext-apps to 2.x in the same change, move to Zod 4.2+, update handler context (extra.mcpReq.signal) and error checks (ProtocolError, SdkError), and pick the right transport for your runtime. Ship the SDK upgrade on the 2025 wire protocol first. Adopt the 2026-07-28 protocol with createMcpHandler as a separate release, keeping the legacy fallback on until every host you support has moved.

Current Versions (November 2026)

These are the versions I checked on npm on November 12, 2026:

PackageVersionNotes
@modelcontextprotocol/server2.4.0McpServer, web-standard transport, createMcpHandler
@modelcontextprotocol/client2.4.0Client, and the Protocol class MCP App views extend
@modelcontextprotocol/core2.4.0Zod protocol schemas
@modelcontextprotocol/node2.1.2NodeStreamableHTTPServerTransport, toNodeHandler
@modelcontextprotocol/express2.0.2createMcpExpressApp, auth and host validation middleware
@modelcontextprotocol/codemod2.4.0v1-to-v2 migration
@modelcontextprotocol/ext-apps2.0.4Peers on client, core, and server ^2.0.0, plus zod@^4.2.0
@modelcontextprotocol/sdk1.32.2Still maintained for v1 users

If you are reading this later, run npm view <package> version peerDependencies before you pin anything. The peer ranges are what decide whether two packages can share a project.

Why MCP App Migrations Need More Than a Type-Check

A plain MCP server can pass a tool test when tools/list and tools/call work. An MCP App has more linked pieces:

  1. The tool descriptor must point to the right ui:// resource.
  2. The resource must return HTML with text/html;profile=mcp-app.
  3. The tool result must contain the data shape the view expects.
  4. The host must send that input and result through the app bridge.
  5. App-only tool calls, links, display modes, files, and other host features must still work.

A codemod can update an import. It cannot tell whether a ChatGPT App now opens with a blank iframe or whether a Claude Connector lost its app-only refresh action because callServerTool started rejecting instead of returning isError.

Treat the migration as three contracts:

ContractWhat changesHow to verify it
TypeScript SDK APIPackages, imports, handler context, schemas, errorsType-check and unit tests
MCP server protocolTools, resources, transport, version negotiationProtocol and conformance tests
MCP App runtimeResource rendering, tool data, bridge errors, host actionsLocal host replicas and live smoke tests

This split also makes failures easier to place. If resources/read returns the wrong MIME type, debug the server contract. If the resource is valid but a display-mode button fails, debug the app-to-host bridge.

Start With a Reversible Baseline

The official v2 migration guide tells you to run the codemod at the package root because it also updates package.json, tests, scripts, and fixtures.

Before that, capture the current behavior:

node --version
pnpm typecheck
pnpm test
git status --short

Use Node.js 20 or newer, in local dev and in every CI image. Commit the current state or create a named stash, then save responses for:

  • tools/list
  • resources/list, if the server lists UI resources
  • resources/read for each linked ui:// URI
  • One successful and one failed tools/call per UI tool
  • One call to a tool name that does not exist
  • App-only tool discovery and calls

That unknown-tool call matters more than it looks, because its behavior changes in v2 (more on that below). Do not compare raw JSON snapshots without thought. Package upgrades can change harmless ordering or capability details. Assert the fields that form your app contract: names, schemas, _meta.ui, resource MIME types, tool result content, structuredContent, and error state.

Run the Official Codemod

Preview first, from the package that owns the MCP dependency:

npx @modelcontextprotocol/codemod@latest v1-to-v2 . --dry-run
npx @modelcontextprotocol/codemod@latest v1-to-v2 .

Then find every marker and remaining v1 import:

rg '@mcp-codemod-error|@modelcontextprotocol/sdk' .

The codemod handles fixed rewrites, including:

  • v1 import paths to the new packages
  • .tool(), .prompt(), and .resource() to registration methods
  • raw Zod shapes to schema objects in common cases
  • request handler context renames
  • many renamed errors and protocol types
  • dependency changes in the nearest package.json

It cannot decide which runtime transport you need, repair custom dependency injection, choose error-handling behavior, or update every monorepo package. It also does not touch @modelcontextprotocol/ext-apps code. I checked the 2.4.0 codemod source, and it has no ext-apps transforms, so callbacks you pass to registerAppTool and handlers you register on App are yours to update by hand.

In a pnpm workspace, check each member that imports MCP packages:

rg -l '@modelcontextprotocol/(sdk|server|client|core|node|express|hono|fastify|ext-apps)' \
  --glob 'package.json' \
  --glob '*.{ts,tsx,js,jsx,mjs,cjs}'

Each package should declare what its own shipped code imports. Avoid relying on an accidental root-level hoist.

Understand the v2 Package Split

The old package handled server, client, protocol schemas, and runtime adapters. v2 separates those jobs, and ext-apps 2.x sits on top of the split packages:

Package after migrationUse it for
@modelcontextprotocol/serverMcpServer, server types, web-standard transport, createMcpHandler
@modelcontextprotocol/server/stdioStdioServerTransport and serveStdio
@modelcontextprotocol/clientMCP client code, client transports, the base Protocol class
@modelcontextprotocol/corePublic Zod protocol schema constants
@modelcontextprotocol/nodeNode HTTP transport, toNodeHandler, toWebRequest
@modelcontextprotocol/expresscreateMcpExpressApp, bearer auth, Origin and Host validation
@modelcontextprotocol/honoHono integration
@modelcontextprotocol/fastifyFastify integration
@modelcontextprotocol/ext-appsMCP App view-to-host communication (App)
@modelcontextprotocol/ext-apps/reactReact hooks for views
@modelcontextprotocol/ext-apps/serverregisterAppTool, registerAppResource, RESOURCE_MIME_TYPE

A typical Node-based MCP App server changes these imports:

// v1
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

// v2
import { McpServer } from '@modelcontextprotocol/server';
import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';

The MCP App helpers keep their import path, and in 2.x their types accept the v2 McpServer:

import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from '@modelcontextprotocol/ext-apps/server';

The app view also stays on the MCP Apps package:

import { App } from '@modelcontextprotocol/ext-apps';
// or React hooks from '@modelcontextprotocol/ext-apps/react'

The server SDK speaks MCP between the host and your backend. The app SDK speaks the MCP Apps bridge between the sandboxed view and the host. In 2.x the app SDK reuses the v2 client’s Protocol class for that bridge, which is why the two upgrades are now linked.

Upgrade ext-apps to 2.x in the Same Change

@modelcontextprotocol/ext-apps 1.7.5 declared @modelcontextprotocol/sdk v1 as a peer. ext-apps 2.0.4 declares @modelcontextprotocol/client, core, and server at ^2.0.0 instead. The ext-apps migration guide says the two SDK generations share no classes or types, so a v1 McpError or Client cannot be passed into v2 code. If you keep ext-apps 1.x next to a v2 server, registerAppTool will not accept your McpServer without a cast, and a cast here hides a real mismatch.

Install by role:

# View or host code
pnpm add @modelcontextprotocol/ext-apps @modelcontextprotocol/client zod@^4.2.0

# MCP server code with HTTP
pnpm add @modelcontextprotocol/ext-apps @modelcontextprotocol/client \
  @modelcontextprotocol/server @modelcontextprotocol/node zod@^4.2.0

pnpm remove @modelcontextprotocol/sdk

@modelcontextprotocol/core is a required peer, but client already depends on it. @modelcontextprotocol/server is only needed when you import ext-apps/server. If you load the view from a CDN through ext-apps/app-with-deps or ext-apps/react-with-deps, you install nothing extra, though the official guide notes those bundles are about 25% larger than in 1.x.

After the install, confirm that no v1 copy is left:

pnpm why @modelcontextprotocol/sdk

An empty result is what you want. If something still pulls in v1, find that dependency before you ship, because two copies of the MCP types in one bundle make error checks like instanceof fail in confusing ways.

What Stays the Same

The bridge on the wire did not change. The ui/* messages between a view and its host are byte-identical between ext-apps 1.x and 2.x, so a 2.x view runs in a 1.x host and a 2.x host renders 1.x views. You do not need to wait for ChatGPT or Claude to update anything before you ship.

These APIs are also unchanged: the App and AppBridge constructors, the on* setters, addEventListener, callServerTool, readServerResource, registerAppResource, the React hooks, and _meta.ui.resourceUri handling. The published type files now resolve under moduleResolution: NodeNext or Node16 without workarounds.

Zod 4.2 and Standard JSON Schema

ext-apps 2.x drops Zod 3. Tool schemas must implement Standard JSON Schema (~standard.jsonSchema), which Zod 4.2+, ArkType, and Valibot do. Zod 4.0 and 4.1 do not expose that property, so they are rejected too.

Raw Zod shapes still work with registerAppTool but are deprecated. Wrap them now:

// Deprecated in ext-apps 2.x
inputSchema: { city: z.string() },

// Preferred
inputSchema: z.object({ city: z.string().min(1) }),

If you share schemas between the server and the view for end-to-end types, upgrade Zod in both packages at the same time.

Update Handler Context and Errors

These changes apply to McpServer handlers, registerAppTool callbacks, and app.registerTool callbacks inside a view:

v1v2
extra.signalextra.mcpReq.signal
extra.requestIdextra.mcpReq.id
extra.authInfoextra.http?.authInfo
extra.sessionIdextra.sessionId (unchanged)
McpError with numeric codeProtocolError for remote JSON-RPC errors
Timeout or closed connection as McpErrorSdkError with "REQUEST_TIMEOUT" or "CONNECTION_CLOSED"

A cancellable tool callback looks like this after the migration:

registerAppTool(
  server,
  'show-weather',
  {
    title: 'Show Weather',
    description: 'Show the current weather for a city',
    inputSchema: z.object({ city: z.string().min(1) }),
    outputSchema: z.object({ city: z.string(), temperatureC: z.number() }),
    _meta: { ui: { resourceUri: 'ui://weather/view.html' } },
  },
  async ({ city }, extra) => {
    const user = extra.http?.authInfo?.clientId;
    const weather = await getWeather(city, {
      signal: extra.mcpReq.signal,
      user,
    });

    return {
      content: [{ type: 'text', text: `Showing weather for ${city}.` }],
      structuredContent: weather,
    };
  },
);

If your server reads auth from extra.authInfo, this is the change most likely to fail quietly. TypeScript catches the rename, but code that uses any or optional chaining on the old path just sees undefined and treats the user as anonymous. Search for it on purpose:

rg 'extra\.(signal|requestId|authInfo)|McpError|instanceof McpError' src

Custom request handlers on App or AppBridge now take method names. app.setRequestHandler(SomeRequestSchema, handler) becomes app.setRequestHandler('some/method', { params: SomeParamsSchema }, (params, ctx) => ...). The old schema-first form still works as a deprecated overload that logs a one-time warning, and it will be removed in ext-apps 3.0. Registering your own handler for notifications/progress or notifications/cancelled now throws, because the base Protocol owns them. Use addEventListener or the SDK’s progress callbacks instead.

Error Behavior Your View Will See

Views often branch on error shape, so check this table against your error handling code. These are the host-side differences the official guide lists when a 2.x host answers a view:

Situation1.x behavior2.x behavior
Handler throws resource not founderror.code: -32002error.code: -32602
Invalid params on a ui/* request-32603 with a Zod issue dump-32602 Invalid params for <method>: ...
Error message textMCP error -32602: ... prefixPlain message
tools/call to an unknown tool through a 2.x McpServerResolves with result.isError: trueJSON-RPC error -32602, so callServerTool rejects

The last row is the one that breaks apps. If your view calls an app-only tool and only checks result.isError, a renamed or missing tool now throws instead. Wrap app-initiated calls so a rejection becomes the same error state the view already shows:

try {
  const result = await app.callServerTool({ name: 'refresh-weather', arguments: { city } });
  if (result.isError) return showError(result);
  render(result.structuredContent);
} catch (error) {
  showError({ message: error instanceof Error ? error.message : 'Request failed' });
}

Also drop any string matching on the MCP error N: prefix. A resource-not-found reply that carries data.uri now arrives as ResourceNotFoundError, a ProtocolError subclass with a .uri getter. The MCP App error handling guide covers the full set of states a view should handle.

Choose the Transport by Runtime

The v2 codemod cannot know where your server runs. For the first release, keep the 2025-era wire protocol and pick the transport that matches your runtime.

Use NodeStreamableHTTPServerTransport from @modelcontextprotocol/node when the handler receives Node’s IncomingMessage and ServerResponse objects:

import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';

const transport = new NodeStreamableHTTPServerTransport({
  sessionIdGenerator: undefined,
});

await server.connect(transport);
await transport.handleRequest(req, res, req.body);

If you hand-wrote Express routing in v1, createMcpExpressApp from @modelcontextprotocol/express now gives you the app instead. It turns on Host and Origin validation automatically for localhost binds, and takes allowedHosts and allowedOrigins lists when you bind to 0.0.0.0 in production. It peers on express.

Use WebStandardStreamableHTTPServerTransport from @modelcontextprotocol/server when the runtime gives you a web-standard Request and expects a Response. That is the usual fit for Cloudflare Workers, Deno, and Bun.

If you use stdio, import StdioServerTransport from @modelcontextprotocol/server/stdio. The v2 package root stays runtime-neutral, so it does not export the stdio transport.

Retest request body parsing, session behavior, CORS, Origin validation, authentication middleware, and close handling. A transport that compiles can still behave differently at the HTTP boundary.

Keep the UI Resource Contract Stable

The host learns about an MCP App through tool metadata, then reads the linked resource. That path should not change during an SDK migration:

tools/list
  -> _meta.ui.resourceUri
resources/read
  -> text/html;profile=mcp-app
tools/call
  -> content + structuredContent
host
  -> render view and deliver tool result

For every UI tool, add a conformance test that:

  1. Finds the tool in tools/list.
  2. Reads _meta.ui.resourceUri.
  3. Calls resources/read with that URI.
  4. Asserts RESOURCE_MIME_TYPE.
  5. Checks that the HTML includes the built entry script or bundled app.
  6. Calls the tool and validates its result against the view’s expected type.

Also check the details a broad server migration can miss:

  • _meta.ui.visibility still exposes app-only tools to the app and hides them from the model.
  • outputSchema matches structuredContent. In the regenerated ext-apps 2.x schema, structuredContent on a tool-result notification can be any JSON value, not only an object, so if your view assumed an object, validate that at the boundary.
  • content still gives non-UI hosts a useful text fallback.
  • Error results set isError and use a shape the view handles.

This catches the most expensive migration failures before a browser opens.

Adopt the 2026-07-28 Protocol Separately

SDK v2 and the 2026-07-28 protocol are related, but they are not the same migration.

The official protocol version guide says a hand-constructed Client, Server, or McpServer keeps 2025-era behavior. Upgrading packages does not switch the wire format.

The modern protocol changes several server assumptions:

  • server/discover replaces the legacy initialization flow.
  • Each request carries a _meta envelope with protocol, client, and capability information.
  • Server-to-client interaction uses multi-round-trip results.
  • subscriptions/listen replaces free-floating change notifications.
  • Closing the response stream handles cancellation over Streamable HTTP.

On HTTP, you opt in with createMcpHandler. It takes a factory that builds a server per request, serves 2026-07-28 traffic, and by default falls back to stateless serving for 2025-era clients:

import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
import { toNodeHandler } from '@modelcontextprotocol/node';

function buildServer() {
  const server = new McpServer({ name: 'weather-app', version: '2.1.0' });
  registerWeatherTools(server); // registerAppTool + registerAppResource
  return server;
}

const handler = createMcpHandler(buildServer); // legacy: 'stateless' by default

// Workers, Deno, Bun: export default { fetch: handler.fetch }
// Express, Fastify, node:http:
app.all('/mcp', toNodeHandler(handler));

Two details from the SDK’s type docs are easy to miss. First, createMcpHandler does no Origin or Host validation itself, so on a fetch-native runtime you put originValidationResponse and hostHeaderValidationResponse in front of it. Second, if you have a sessionful legacy deployment you want to keep, isLegacyRequest(request) runs the same routing decision the handler uses, so you can send 2025 traffic to your existing transport and the rest to a strict modern handler created with legacy: 'reject'.

On stdio, the modern entry point is serveStdio from @modelcontextprotocol/server/stdio.

Changing the SDK and the protocol at once makes failures hard to place. Use two releases:

  1. Move to v2 packages and ext-apps 2.x on the legacy protocol.
  2. Switch to createMcpHandler with the default legacy fallback, then test both eras.

Only set legacy: 'reject' after the ChatGPT, Claude, and other host versions you support speak 2026-07-28. Host updates do not all arrive on the same day, and a strict endpoint turns a slow host into a broken app.

Test the MCP App Across Three Layers

After the code compiles, test the contracts in order.

1. Server and protocol tests

Assert:

  • Tool names, descriptions, input schemas, and output schemas
  • _meta.ui.resourceUri and visibility
  • Resource URI, MIME type, and HTML body
  • Successful, empty, invalid, cancelled, and error tool results
  • The unknown-tool response, now a -32602 JSON-RPC error
  • Authentication, including that extra.http?.authInfo is populated
  • Legacy and modern protocol paths, if both are enabled

2. Rendered MCP App tests

Render each tool state in the host runtimes you support. Check:

  • Initial tool input before a result arrives
  • Loading, success, empty, error, and cancelled views
  • An app-only tool call that rejects, not just one that returns isError
  • Light and dark themes
  • Inline and expanded display modes
  • sendMessage, updateModelContext, links, and file actions used by the app
  • Resize, teardown, and repeated tool calls

The sunpeak MCP App Inspector can run these states against replicated ChatGPT and Claude runtimes without paid host accounts or model credits. sunpeak 0.20.96 itself runs on @modelcontextprotocol/server 2.4 and ext-apps 2.0.4, and it works with any MCP server, so you can point it at the server you just migrated:

npx sunpeak inspect --server http://localhost:3000/mcp

For CI, scaffold tests against an existing server:

npx sunpeak test init --server http://localhost:3000/mcp
pnpm test

Use deterministic fixtures for tool input and output so the SDK migration diff does not get mixed with model variance. If you already have regression tests, run them unchanged against the migrated server before you touch any test code. A test you edited during the migration can no longer prove the behavior stayed the same.

3. Live host smoke tests

Keep a small live matrix after local tests pass:

  • One ChatGPT tool call that renders and completes an app action
  • One Claude tool call that renders the same resource
  • Authentication, if the production server requires it
  • One host-specific capability the app depends on

Live tests catch rollout and host integration issues. They should confirm the smaller local suite, not replace it.

A Safe Rollout Order

Use this order for an MCP App that already has users:

  1. Record the v1 server and rendered app behavior, including the unknown-tool and error cases.
  2. Upgrade Node.js and CI images to Node 20.
  3. Run the codemod with --dry-run, then for real, and clear every action marker.
  4. Upgrade ext-apps to 2.x and Zod to 4.2+, and remove @modelcontextprotocol/sdk.
  5. Update handler context, error checks, and app-initiated tool call handling by hand.
  6. Keep the 2025-era transport.
  7. Pass type-checks, unit tests, and protocol conformance tests.
  8. Pass local ChatGPT and Claude runtime tests.
  9. Deploy to a staging URL and run live smoke tests, then ship.
  10. In a later release, switch to createMcpHandler with the legacy fallback on.
  11. Set legacy: 'reject' only when every supported host speaks 2026-07-28.

The package migration is complete when the app contract still works, not when the last v1 import disappears.

sunpeak keeps that contract visible during the change. Its MCP App testing framework runs protocol, E2E, and visual checks across replicated host states, so you can migrate the server without manually reopening every tool result in every host. If you are starting a new app instead of migrating one, the MCP App framework already ships on the v2 SDK and ext-apps 2.x.

Get Started

Documentation →
npx sunpeak new

Further Reading

Frequently Asked Questions

How do I migrate an MCP App from the MCP TypeScript SDK v1 to v2?

Upgrade to Node.js 20 or newer and record your current tool, resource, and rendered app behavior. Run npx @modelcontextprotocol/codemod@latest v1-to-v2 . from the package root (add --dry-run first to preview), clear every @mcp-codemod-error marker, then upgrade @modelcontextprotocol/ext-apps to 2.x in the same change because ext-apps 2.x peers on the v2 packages and 1.x peers on v1. Move to Zod 4.2 or newer, update handler context and error checks, type-check, and run protocol plus rendered UI tests. Adopt the 2026-07-28 protocol in a separate release.

What replaces @modelcontextprotocol/sdk in v2?

@modelcontextprotocol/server contains McpServer, the web-standard transport, and createMcpHandler. @modelcontextprotocol/client contains the client and the Protocol class that MCP App views extend. @modelcontextprotocol/core contains the Zod protocol schemas. Runtime adapters live in @modelcontextprotocol/node, @modelcontextprotocol/express, @modelcontextprotocol/hono, and @modelcontextprotocol/fastify. As of November 2026 the server, client, and core packages are at 2.4.0. Install only the packages each workspace imports.

Do I need to upgrade @modelcontextprotocol/ext-apps when I move to MCP TypeScript SDK v2?

Yes. @modelcontextprotocol/ext-apps 2.x declares @modelcontextprotocol/client, core, and server ^2.0.0 as peers, while 1.x declared @modelcontextprotocol/sdk v1. The two SDK generations share no classes or types, so mixing ext-apps 1.x server helpers with a v2 McpServer causes type errors. Upgrade both together. The current release is ext-apps 2.0.4.

Does ext-apps 2.x break MCP App views running in ChatGPT or Claude?

No. The ui/* messages between the view and the host are byte-identical between ext-apps 1.x and 2.x, so a 2.x view runs in a 1.x host and a 2.x host renders 1.x views. The breaking changes are in TypeScript APIs and dependencies. A few error responses do change: invalid params now return -32602, resource-not-found returns -32602 instead of -32002, error messages drop the "MCP error N:" prefix, and calling an unknown tool through a 2.x McpServer makes callServerTool reject instead of resolving with isError.

Does upgrading to MCP TypeScript SDK v2 enable the 2026-07-28 protocol automatically?

No. A hand-built Client, Server, or McpServer connected to a transport keeps 2025-era connection behavior. The 2026-07-28 protocol is a separate opt-in through createMcpHandler for HTTP or serveStdio for stdio. createMcpHandler serves modern traffic and, by default, falls back to stateless serving for 2025-era clients. Pass legacy: "reject" only after every host you support speaks the new revision.

Which Streamable HTTP transport should an MCP App server use in SDK v2?

For a 2025-era server, use NodeStreamableHTTPServerTransport from @modelcontextprotocol/node with Node IncomingMessage and ServerResponse objects, or WebStandardStreamableHTTPServerTransport from @modelcontextprotocol/server on Cloudflare Workers, Deno, or Bun. For the 2026-07-28 protocol, use createMcpHandler with a per-request server factory and mount handler.fetch directly or wrap it with toNodeHandler from @modelcontextprotocol/node for Express, Fastify, or node:http.

What Zod version does the MCP Apps SDK 2.x require?

ext-apps 2.x requires zod 4.2.0 or newer because tool schemas must implement Standard JSON Schema (~standard.jsonSchema). Zod 3, 4.0, and 4.1 are rejected. ArkType and Valibot also work. Raw Zod shapes such as { city: z.string() } still work with registerAppTool but are deprecated, so wrap them in z.object().

How should I test an MCP App after the SDK v2 migration?

Test tools/list, resources/read, tool calls, content, structuredContent, resource MIME types, _meta.ui.resourceUri, app-only tool visibility, and error results. Add tests for the error codes that changed in v2. Then render the app in each supported host runtime and check tool input, results, bridge calls, themes, and display modes. If you enable the 2026-07-28 protocol, run the protocol suite against both legacy and modern clients. Keep one real-host smoke test after local and CI tests pass.