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

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:
| Package | Version | Notes |
|---|---|---|
@modelcontextprotocol/server | 2.4.0 | McpServer, web-standard transport, createMcpHandler |
@modelcontextprotocol/client | 2.4.0 | Client, and the Protocol class MCP App views extend |
@modelcontextprotocol/core | 2.4.0 | Zod protocol schemas |
@modelcontextprotocol/node | 2.1.2 | NodeStreamableHTTPServerTransport, toNodeHandler |
@modelcontextprotocol/express | 2.0.2 | createMcpExpressApp, auth and host validation middleware |
@modelcontextprotocol/codemod | 2.4.0 | v1-to-v2 migration |
@modelcontextprotocol/ext-apps | 2.0.4 | Peers on client, core, and server ^2.0.0, plus zod@^4.2.0 |
@modelcontextprotocol/sdk | 1.32.2 | Still 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:
- The tool descriptor must point to the right
ui://resource. - The resource must return HTML with
text/html;profile=mcp-app. - The tool result must contain the data shape the view expects.
- The host must send that input and result through the app bridge.
- 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:
| Contract | What changes | How to verify it |
|---|---|---|
| TypeScript SDK API | Packages, imports, handler context, schemas, errors | Type-check and unit tests |
| MCP server protocol | Tools, resources, transport, version negotiation | Protocol and conformance tests |
| MCP App runtime | Resource rendering, tool data, bridge errors, host actions | Local 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/listresources/list, if the server lists UI resourcesresources/readfor each linkedui://URI- One successful and one failed
tools/callper 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 migration | Use it for |
|---|---|
@modelcontextprotocol/server | McpServer, server types, web-standard transport, createMcpHandler |
@modelcontextprotocol/server/stdio | StdioServerTransport and serveStdio |
@modelcontextprotocol/client | MCP client code, client transports, the base Protocol class |
@modelcontextprotocol/core | Public Zod protocol schema constants |
@modelcontextprotocol/node | Node HTTP transport, toNodeHandler, toWebRequest |
@modelcontextprotocol/express | createMcpExpressApp, bearer auth, Origin and Host validation |
@modelcontextprotocol/hono | Hono integration |
@modelcontextprotocol/fastify | Fastify integration |
@modelcontextprotocol/ext-apps | MCP App view-to-host communication (App) |
@modelcontextprotocol/ext-apps/react | React hooks for views |
@modelcontextprotocol/ext-apps/server | registerAppTool, 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:
| v1 | v2 |
|---|---|
extra.signal | extra.mcpReq.signal |
extra.requestId | extra.mcpReq.id |
extra.authInfo | extra.http?.authInfo |
extra.sessionId | extra.sessionId (unchanged) |
McpError with numeric code | ProtocolError for remote JSON-RPC errors |
Timeout or closed connection as McpError | SdkError 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:
| Situation | 1.x behavior | 2.x behavior |
|---|---|---|
| Handler throws resource not found | error.code: -32002 | error.code: -32602 |
Invalid params on a ui/* request | -32603 with a Zod issue dump | -32602 Invalid params for <method>: ... |
| Error message text | MCP error -32602: ... prefix | Plain message |
tools/call to an unknown tool through a 2.x McpServer | Resolves with result.isError: true | JSON-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:
- Finds the tool in
tools/list. - Reads
_meta.ui.resourceUri. - Calls
resources/readwith that URI. - Asserts
RESOURCE_MIME_TYPE. - Checks that the HTML includes the built entry script or bundled app.
- 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.visibilitystill exposes app-only tools to the app and hides them from the model.outputSchemamatchesstructuredContent. In the regenerated ext-apps 2.x schema,structuredContenton 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.contentstill gives non-UI hosts a useful text fallback.- Error results set
isErrorand 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/discoverreplaces the legacy initialization flow.- Each request carries a
_metaenvelope with protocol, client, and capability information. - Server-to-client interaction uses multi-round-trip results.
subscriptions/listenreplaces 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:
- Move to v2 packages and ext-apps 2.x on the legacy protocol.
- Switch to
createMcpHandlerwith 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.resourceUriand visibility- Resource URI, MIME type, and HTML body
- Successful, empty, invalid, cancelled, and error tool results
- The unknown-tool response, now a
-32602JSON-RPC error - Authentication, including that
extra.http?.authInfois 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:
- Record the v1 server and rendered app behavior, including the unknown-tool and error cases.
- Upgrade Node.js and CI images to Node 20.
- Run the codemod with
--dry-run, then for real, and clear every action marker. - Upgrade ext-apps to 2.x and Zod to 4.2+, and remove
@modelcontextprotocol/sdk. - Update handler context, error checks, and app-initiated tool call handling by hand.
- Keep the 2025-era transport.
- Pass type-checks, unit tests, and protocol conformance tests.
- Pass local ChatGPT and Claude runtime tests.
- Deploy to a staging URL and run live smoke tests, then ship.
- In a later release, switch to
createMcpHandlerwith the legacy fallback on. - 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
npx sunpeak newFurther Reading
- MCP Apps SDK guide - packages, architecture, and your first app
- MCP App conformance testing - validate tools, resources, metadata, and fallbacks
- MCP App UI resources - ui:// URIs, MIME types, and resource links
- MCP App lifecycle - connection, tool input, results, and teardown
- MCP App error handling - tool errors, bridge failures, and recovery
- End-to-end TypeScript types in MCP Apps
- How to deploy an MCP App to production
- Regression testing MCP Apps, ChatGPT Apps, and Claude Connectors
- Cross-host testing for ChatGPT Apps and Claude Connectors
- MCP App framework
- ChatGPT App framework
- Claude Connector framework
- sunpeak MCP App testing framework
- sunpeak MCP App Inspector
- Official MCP TypeScript SDK v2 migration guide
- Official MCP TypeScript SDK protocol version guide
- Official ext-apps 1.x to 2.x migration guide
- @modelcontextprotocol/ext-apps 2.0.4 package and peer dependencies
- MCP specification 2026-07-28
- Official MCP Apps overview
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.