MCP Apps SDK Guide: Packages, Architecture, and Your First App (November 2026)

The MCP Apps SDK connects an MCP server, an interactive view, and the AI host that renders it.
Search for “MCP Apps SDK” and you will find two SDK generations, several import paths, a React entry point, server helpers, and something called AppBridge. They fit together, but the names make the first setup harder than it needs to be. Since August, the package also moved to a new major version, and some official pages still show the old install line.
The short version is that core MCP and MCP Apps cover different connections. The base MCP SDK connects your server to an AI host. The MCP Apps SDK connects your interactive view to that host after the host renders it in a sandboxed iframe.
TL;DR: Install @modelcontextprotocol/ext-apps 2.x (2.0.4 as of November 16, 2026) with the split MCP TypeScript SDK v2 packages and zod@^4.2.0. Do not install the v1 @modelcontextprotocol/sdk package next to it. Use the root import in the view, /react for optional React hooks, /server for tool and resource registration, and /app-bridge only when you are building an MCP host. Keep the server-to-host and view-to-host contracts separate, then test both.
The MCP Apps SDK Is One Layer of the App
An MCP App has three running parts:
MCP server
<--- MCP over HTTP or stdio --->
AI host
<--- MCP Apps JSON-RPC over postMessage --->
sandboxed app view
The base MCP SDK owns the top connection. It gives your server tools, resources, schemas, transports, and request handlers.
The MCP Apps SDK owns the bottom connection. It gives the iframe a typed way to receive tool data, read host context, request display mode changes, call server tools through the host, and take other actions that the host allows. The extension ID that hosts advertise for this layer is io.modelcontextprotocol/ui.
The host sits in the middle because the iframe cannot reach into the parent page. The MCP Apps overview specifies a sandboxed iframe and postMessage bridge. That boundary keeps the app isolated from host cookies, local storage, and page DOM.
This split explains a common setup bug: a working MCP server is not yet an MCP App. The server also needs a UI resource, the tool needs metadata that points to it, and the view needs a bridge connection to the host.
What Changed Since August 2026
Three things changed for anyone who set up the SDK earlier this year:
@modelcontextprotocol/ext-apps2.0 moved onto the MCP TypeScript SDK v2. Its peers are now@modelcontextprotocol/client,core, andserverat^2.0.0, pluszod@^4.2.0. The last 1.x release, 1.7.5, peered on@modelcontextprotocol/sdk1.x.- The wire protocol did not change. The ext-apps migration guide says the
ui/*messages are byte-identical, so a 2.x view runs in a 1.x host and a 2.x host renders a 1.x view. - The TypeScript surface did change. Handler context, error classes, custom request handlers, and schema rules all follow SDK v2. The table later in this post lists each one.
One trap to know about: as of this writing, the manual setup on the modelcontextprotocol.io build guide still runs npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk and imports from @modelcontextprotocol/sdk/server/mcp.js. That command now pulls ext-apps 2.x next to SDK v1, which gives you peer dependency warnings and type errors at registerAppTool. Follow the ext-apps quickstart instead, which uses the v2 packages.
The Package Map
Here is every import you might need and who needs it:
| Import | Job | Who needs it |
|---|---|---|
@modelcontextprotocol/server | McpServer, tools, resources, stdio, Web Standard HTTP transport | Server authors |
@modelcontextprotocol/node | NodeStreamableHTTPServerTransport for Node http servers | Server authors on Node HTTP |
@modelcontextprotocol/express | createMcpExpressApp with host and origin checks | Server authors using Express |
@modelcontextprotocol/client | Protocol base class that App and AppBridge extend | Everyone (required peer) |
@modelcontextprotocol/ext-apps | App, PostMessageTransport, view lifecycle, host context, app actions | App view developers |
@modelcontextprotocol/ext-apps/react | useApp, useHostStyles, useDocumentTheme, useAutoResize | React view developers |
@modelcontextprotocol/ext-apps/server | registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, getUiCapability | MCP App server authors |
@modelcontextprotocol/ext-apps/app-bridge | Host-side iframe rendering and message proxying | MCP host developers |
@modelcontextprotocol/ext-apps/app-with-deps | App with client, core, and zod bundled in | Pages with no bundler or a CDN |
Everything under @modelcontextprotocol/ext-apps/ is a subpath export from one package. Do not try to install them as separate npm packages. @modelcontextprotocol/core is also a required peer, but client already depends on it, so npm installs it without you listing it.
Pick Your Role Before Picking Imports
The package has APIs for three different jobs. You rarely need all of them.
You Are Building an App
Most readers are here. You own:
- An MCP server with one or more tools.
- One or more
ui://resources containing HTML, CSS, and JavaScript. - The code inside each resource iframe.
- Tests for tool contracts and rendered behavior.
Use the App class directly, use the React hooks, or use an MCP App framework that wraps them.
You Are Adding UI to an Existing MCP Server
Keep your current tool logic, then add:
_meta.ui.resourceUrito the UI tool.- A matching app resource.
- The MCP App resource MIME type.
- A bundled view that connects to the host.
The server can be written in any language because the host sees the MCP protocol, not your implementation. The ext-apps repository even includes Python examples (qr-server and say-server). If your TypeScript server is still on SDK v1, plan the SDK v2 upgrade and the ext-apps 2.x upgrade as one change, because the 2.x server helpers only accept a v2 McpServer.
You Are Building an MCP Host
Use @modelcontextprotocol/ext-apps/app-bridge only if you are building the client that embeds apps. Host work includes:
- Detecting a tool’s linked UI resource.
- Reading the resource from the MCP server.
- Applying sandbox and Content Security Policy rules.
- Creating and sizing the iframe.
- Proxying allowed tool calls and app requests.
- Sending tool input, tool results, cancellation, and host context to the view.
The repository’s examples/basic-host is the reference host, though the README says it is an example, not a supported host. If your app runs inside an existing host such as ChatGPT or Claude, the host already owns this work.
Install the Direct SDK Stack
Install by role. For a view or a host:
npm install @modelcontextprotocol/ext-apps \
@modelcontextprotocol/client@^2.0.0 \
zod@^4.2.0
For an MCP server that also serves the view, add the server package and, for HTTP, the Node and Express adapters:
npm install @modelcontextprotocol/ext-apps \
@modelcontextprotocol/client@^2.0.0 \
@modelcontextprotocol/server@^2.0.0 \
@modelcontextprotocol/node@^2.0.0 \
@modelcontextprotocol/express@^2.0.0 \
zod@^4.2.0
ext-apps requires Node.js 20 or later. The current versions as of November 16, 2026 are ext-apps 2.0.4, server and client 2.4.0, node 2.1.2, and express 2.0.2.
The Zod floor matters. Tool schemas in SDK v2 must implement Standard JSON Schema (~standard.jsonSchema). Zod 4.2 and later, ArkType, and Valibot do. Zod 4.0 and 4.1 do not, and Zod 3 is gone, so an older Zod in your lockfile shows up as a schema rejection at registration time, not as an install error.
You will also need a bundler such as Vite and whatever UI library you choose. Both quickstarts use vite-plugin-singlefile to inline JS and CSS into one HTML file, which avoids CSP work for local assets. The view can use React, Vue, Svelte, Preact, Solid, or plain JavaScript. The protocol does not require React.
If you use an AI coding agent, the repository also ships a create-mcp-app skill that scaffolds a server, view, and build config. Check the generated package.json against the install lines above before you commit it.
Register the Tool and UI Resource
The server links a tool to a view with a shared resource URI. The helpers from /server keep the metadata and MIME type consistent:
import fs from 'node:fs/promises';
import { McpServer } from '@modelcontextprotocol/server';
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from '@modelcontextprotocol/ext-apps/server';
import { z } from 'zod';
export function createServer() {
const server = new McpServer({ name: 'orders-app', version: '1.0.0' });
const resourceUri = 'ui://orders/summary.html';
registerAppTool(
server,
'show-orders',
{
title: 'Show Orders',
description: 'Show orders for an account, filtered by status',
inputSchema: z.object({
status: z.enum(['open', 'closed']).default('open'),
}),
_meta: { ui: { resourceUri } },
},
async ({ status }) => {
const orders = [
{ id: 'A-104', total: 82 },
{ id: 'A-105', total: 31 },
];
return {
content: [{ type: 'text', text: `Found ${orders.length} ${status} orders.` }],
structuredContent: { status, orders },
};
}
);
registerAppResource(
server,
'Orders summary',
resourceUri,
{ description: 'Interactive order summary', mimeType: RESOURCE_MIME_TYPE },
async () => ({
contents: [
{
uri: resourceUri,
mimeType: RESOURCE_MIME_TYPE,
text: await fs.readFile(new URL('./dist/orders.html', import.meta.url), 'utf8'),
},
],
})
);
return server;
}
Three values form the link:
- The tool descriptor contains
_meta.ui.resourceUri. - The registered resource uses the exact same URI.
- The returned resource uses
text/html;profile=mcp-app, preferably throughRESOURCE_MIME_TYPE.
If any one of those differs, the tool may still run while the UI stays blank. Read the UI resource guide for resource metadata and resource links, and the tool metadata guide for visibility on app-only tools.
Two SDK v2 details show up here. First, inputSchema is a z.object(...). A raw shape such as { status: z.string() } still works with registerAppTool, but it is deprecated, so wrap it now. Second, the handler’s second argument is the v2 context. Read the abort signal from ctx.mcpReq.signal and auth from ctx.http?.authInfo, not the v1 extra.signal and extra.authInfo.
The server is a factory on purpose. With SDK v2 you can serve it through createMcpExpressApp from @modelcontextprotocol/express, NodeStreamableHTTPServerTransport from @modelcontextprotocol/node, or @modelcontextprotocol/server/stdio for local clients, and each transport can create a fresh server per session or request.
Serve Text-Only Hosts Too
Not every MCP client renders apps. getUiCapability reads the client’s extensions capabilities so you can decide what to register:
import { getUiCapability, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
server.server.oninitialized = () => {
const ui = getUiCapability(server.server.getClientCapabilities());
const rendersApps = ui?.mimeTypes?.includes(RESOURCE_MIME_TYPE) ?? false;
// Register the app tool when rendersApps is true, a text-only tool otherwise.
};
Even without this check, a good content array means a text-only client still gets a useful answer. The capability detection guide covers the view side of the same problem.
Connect the View With the App Class
Inside the bundled HTML, the framework-agnostic App class handles the handshake and typed bridge messages:
import { App } from '@modelcontextprotocol/ext-apps';
type OrdersResult = {
status: 'open' | 'closed';
orders: Array<{ id: string; total: number }>;
};
const root = document.querySelector<HTMLDivElement>('#app');
const app = new App({ name: 'orders-view', version: '1.0.0' }, {}, { autoResize: true, strict: true });
app.ontoolresult = (result) => {
const data = result.structuredContent as OrdersResult | undefined;
if (!root || !data) return;
root.replaceChildren(
...data.orders.map((order) => {
const row = document.createElement('p');
row.textContent = `${order.id}: $${order.total}`;
return row;
})
);
};
app.onhostcontextchanged = (context) => {
if (context.theme) document.documentElement.dataset.theme = context.theme;
};
await app.connect();
document.documentElement.dataset.theme = app.getHostContext()?.theme ?? 'light';
Register handlers before connect() so the view does not miss early notifications. connect() runs the ui/initialize handshake over a PostMessageTransport to window.parent, records host capabilities and context, and starts automatic size notifications unless you pass autoResize: false.
The constructor options in 2.x are worth knowing:
| Option | Default | What it does |
|---|---|---|
autoResize | true | Watches the document with ResizeObserver and sends ui/notifications/size-changed |
strict | false | Throws instead of warning when you call a host method, such as callServerTool, before connect() finishes. The SDK says throwing will become the default |
allowUnsafeEval | false | When false, the constructor sets Zod to jitless mode so parsing works under a CSP with no unsafe-eval |
I turn on strict in development because a call that races the handshake is a real bug on stricter hosts, and a thrown error is easier to find than a console warning.
The App object also exposes app-to-host actions: callServerTool, readServerResource, listServerResources, createSamplingMessage, requestDisplayMode, openLink, downloadFile, sendMessage, updateModelContext, sendLog, and requestTeardown. Hosts support different subsets, so check app.getHostCapabilities() before using an optional action and keep a fallback. For the full event order, see the MCP App lifecycle guide.
What the React Entry Point Does
@modelcontextprotocol/ext-apps/react is optional. It gives React apps:
useAppto create and connect anAppand expose{ app, isConnected, error }.useHostStylesto apply host CSS variables and fonts.useDocumentThemeto follow the host theme.useAutoResizewhen you turn off automatic resizing and want to control it.
It does not turn the low-level SDK into a full app framework. You still own the server layout, file discovery, resource bundling, tool result state, tests, and deployment unless another framework handles them.
A small React view starts like this:
import { useState } from 'react';
import { useApp } from '@modelcontextprotocol/ext-apps/react';
type OrdersResult = {
status: 'open' | 'closed';
orders: Array<{ id: string; total: number }>;
};
export function OrdersView() {
const [data, setData] = useState<OrdersResult>();
const { isConnected, error } = useApp({
appInfo: { name: 'orders-view', version: '1.0.0' },
capabilities: {},
strict: true,
onAppCreated: (app) => {
app.ontoolresult = (result) => {
setData(result.structuredContent as OrdersResult);
};
},
});
if (error) return <p>Could not connect to the host.</p>;
if (!isConnected || !data) return <p>Loading orders...</p>;
return (
<ul>
{data.orders.map((order) => (
<li key={order.id}>
{order.id}: ${order.total}
</li>
))}
</ul>
);
}
onAppCreated runs before the connection starts, which is the right place to attach handlers. This is enough for a small app. As the app grows, write an adapter around the SDK events or use a framework with typed data hooks so result parsing does not spread across components. The React guide and TypeScript types guide go further.
ext-apps 1.x to 2.x: What Breaks
If you have an app on ext-apps 1.x, these are the changes the migration guide lists, in the order you will hit them:
| Area | 1.x | 2.x |
|---|---|---|
| Base SDK peer | @modelcontextprotocol/sdk 1.x | client, core, server at ^2.0.0. Uninstall the v1 package |
| Zod | Zod 3 or 4 | zod@^4.2.0, or another Standard JSON Schema library |
| Tool schemas | Raw shapes | z.object({...}). Raw shapes still work but are deprecated |
| Handler context | extra.signal, extra.requestId, extra.authInfo | ctx.mcpReq.signal, ctx.mcpReq.id, ctx.http?.authInfo |
| Custom request handlers | setRequestHandler(Schema, handler) | setRequestHandler('method', { params }, (params, ctx) => ...). Old form warns once and goes away in 3.0 |
| Errors | McpError with numeric code | ProtocolError for remote errors, SdkError with string codes such as REQUEST_TIMEOUT |
Unknown tool via callServerTool on a v2 server | Resolves with isError: true | Rejects with JSON-RPC error -32602 |
| Bundles | app-with-deps included the old SDK | app-with-deps and react-with-deps bundle client, core, and zod, about 25% larger |
The App and AppBridge constructors, the on* setters, addEventListener, callServerTool, readServerResource, registerAppResource, the React hooks, and _meta.ui.resourceUri handling did not change. Most view code moves over with only the error handling update.
The unknown-tool row is the one that breaks views quietly. If your view calls a tool that may not exist on older server builds, wrap callServerTool in try/catch instead of only checking result.isError. The SDK v2 migration guide covers the server half of the upgrade.
Choose the Direct SDK or a Framework
The direct SDK is a good fit when:
- You already have an MCP server architecture you want to keep.
- You need exact control over the bridge, bundler, or resource metadata.
- You are building a host or protocol library.
- You want to learn the wire-level app model.
A framework is a better fit when you want conventions for project layout, tool and resource discovery, build output, host adapters, simulations, and browser tests, and when you would rather not track peer ranges across six packages by hand.
The choice does not change the protocol. A sound framework should still produce normal MCP tools, ui:// resources, portable metadata, and a view that speaks the MCP Apps bridge. For example, sunpeak 0.20.99 depends on @modelcontextprotocol/ext-apps ^2.0.4 and @modelcontextprotocol/server ^2.4.0, so its output is the same contract this post describes.
Test the Contracts in Order
An app can pass a server unit test and still fail in a host. Test from the protocol outward.
1. Tool Discovery
Call tools/list and assert that:
- The tool name and input schema are correct.
_meta.ui.resourceUriexists.- App-only tools are hidden from the model when appropriate.
2. Resource Loading
Call resources/read with the linked URI and assert that:
- The URI matches the tool descriptor.
- The MIME type is
text/html;profile=mcp-app. - The HTML contains the built entry code and required assets.
- CSP metadata covers every external API and asset domain. See the CSP guide.
3. Tool Results
Call the UI tool and test:
contentgives non-UI hosts a useful fallback.structuredContentmatches the view’s expected shape, andoutputSchemaif you declare one._metacontains only app-only data.- Error and empty results use deliberate shapes.
- Calls to unknown or removed tools fail the way your view expects on SDK v2.
4. Rendered View
Open the resource in an MCP App host runtime and cover:
- Partial input, complete input, success, error, and cancellation.
- Light and dark themes.
- Inline, fullscreen, and picture-in-picture where supported.
- Mobile sizes, safe areas, and host context changes.
- Every button that calls a tool or requests a host action.
- Denied and unsupported capability paths.
- No CSP violations in the console under the host’s default policy.
5. Live Host Smoke Test
Keep a small test in each production host you support. Local host replicas catch most app bugs faster, while live tests catch authentication, deployment, connection, and host-release differences.
With sunpeak’s MCP testing framework, you can run protocol tests and Playwright tests against replicated ChatGPT and Claude runtimes for any MCP server, including one you built with the direct SDK. The Inspector also lets you switch host, theme, display mode, viewport, and simulation data without deploying.
A Practical Starting Rule
Use @modelcontextprotocol/ext-apps 2.x with the SDK v2 packages when you want the lowest-level official app API. Add only the subpath imports your role needs, keep Zod at 4.2 or later, and treat a type mismatch between ext-apps and the base SDK as a real compatibility warning, not something to cast away.
If you would rather start with working project conventions, npx sunpeak new creates a typed React MCP App framework project with resource and tool discovery, local host simulation, and tests already wired, on the same ext-apps 2.x stack. Either path should lead to the same portable MCP App contract.
Get Started
npx sunpeak newFurther Reading
- What Is an MCP App? - tools, resources, hosts, and interactive UI
- MCP App lifecycle - connect, tool input, results, and teardown
- MCP App UI resources - ui:// URIs, MIME types, and resource links
- Tool _meta.ui.resourceUri and visibility for MCP Apps
- MCP TypeScript SDK v2 migration guide for MCP Apps
- MCP App TypeScript types - typing tool input, results, and host context
- MCP App React guide - hooks, state, and host styles
- MCP App CSP - calling external APIs from a sandboxed view
- MCP App capability detection and cross-host fallbacks
- MCP App framework - build portable apps with conventions and React hooks
- MCP App Inspector - render and debug apps locally
- MCP testing framework - protocol, browser, visual, and live-host tests
- MCP Apps SDK quickstart (ext-apps 2.x)
- Migrating from ext-apps 1.x to 2.x
- MCP Apps SDK API reference
- Official MCP Apps overview
- MCP Apps SDK source, examples, and starter templates
- sunpeak documentation
Frequently Asked Questions
What is the MCP Apps SDK?
The MCP Apps SDK is the @modelcontextprotocol/ext-apps npm package. It implements the MCP Apps extension (io.modelcontextprotocol/ui): the App class for view-to-host communication, optional React hooks, server helpers for registering UI tools and resources, and AppBridge for developers building an MCP host. As of November 2026 the current release is 2.0.4, which is built on the split MCP TypeScript SDK v2 packages.
Which MCP Apps SDK packages do I need to install in 2026?
It depends on your role. A view or host author installs @modelcontextprotocol/ext-apps, @modelcontextprotocol/client@^2.0.0, and zod@^4.2.0 (plus react and react-dom for the React hooks). An MCP server author adds @modelcontextprotocol/server@^2.0.0, and for HTTP transports @modelcontextprotocol/node@^2.0.0 and @modelcontextprotocol/express@^2.0.0. You do not install @modelcontextprotocol/sdk (the v1 package) alongside ext-apps 2.x.
What is the difference between @modelcontextprotocol/ext-apps and the base MCP TypeScript SDK?
The base SDK (@modelcontextprotocol/server, client, core, node, and express in v2) implements core MCP: tools, resources, transports, and client connections. @modelcontextprotocol/ext-apps adds the interactive app layer on top: UI resource metadata, the text/html;profile=mcp-app MIME type, the iframe-to-host postMessage bridge, host context, display modes, and app actions such as callServerTool. ext-apps 2.x extends the Protocol class from @modelcontextprotocol/client, so the two must be on the same major version.
Can I use @modelcontextprotocol/ext-apps with @modelcontextprotocol/sdk v1?
Only with ext-apps 1.x. ext-apps 2.0 and later declare @modelcontextprotocol/client, core, and server ^2.0.0 as peers and drop the v1 @modelcontextprotocol/sdk package. The two SDK generations share no classes or types, so a v1 McpServer will not type-check against the 2.x registerAppTool. Upgrade both together, or pin ext-apps to 1.x until you migrate the server. The wire protocol did not change, so a 2.x view runs in a 1.x host and the reverse.
Can I use the MCP Apps SDK with React, Vue, Svelte, or plain JavaScript?
Yes. The App class and postMessage protocol are framework-agnostic. The official ext-apps repository has the same starter app built with React, Vue, Svelte, Preact, Solid, and vanilla JavaScript. The @modelcontextprotocol/ext-apps/react entry point is optional and adds useApp, useHostStyles, useDocumentTheme, and useAutoResize. For a page with no bundler, ./app-with-deps and ./react-with-deps ship the client, core, and zod code inside the bundle.
Do I need AppBridge to build an MCP App?
No. AppBridge, imported from @modelcontextprotocol/ext-apps/app-bridge, is for the host side: an AI client that discovers UI resources, creates sandboxed iframes, and proxies messages between apps and MCP servers. If your app runs inside ChatGPT, Claude, or another existing host, use the App class or a framework and let the host own AppBridge. The repository ships examples/basic-host as a reference host for local testing.
Why does my MCP App view fail with a CSP or eval error?
Hosts render views under a deny-by-default Content Security Policy, which usually blocks unsafe-eval. Zod 4 compiles object parsers with new Function() unless it runs in jitless mode. ext-apps 2.x sets z.config({ jitless: true }) in the App constructor by default, so the bridge works under strict CSP. If your own view code builds Zod schemas before constructing App, construct App first or set jitless yourself. Network calls and external assets still need CSP domains declared in the resource _meta.ui.csp.
How should I test an app built with the MCP Apps SDK?
Test the full chain: tools/list exposes _meta.ui.resourceUri, resources/read returns text/html;profile=mcp-app, tools/call returns the expected content and structuredContent, and the rendered iframe handles tool input, results, errors, cancellation, host context, display modes, and app actions. Add browser tests against each target host runtime, such as the ChatGPT and Claude replicas in sunpeak, then keep a small live-host smoke test for deployment and host-specific behavior.