Skip to main content
All posts

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

Abe Wheeler
MCP AppsMCP Apps SDKMCP App FrameworkMCP App TestingChatGPT AppsChatGPT App FrameworkClaude ConnectorsClaude Connector FrameworkTypeScriptReact
The MCP Apps SDK connects an MCP server, an interactive view, and the AI host that renders it.

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:

  1. @modelcontextprotocol/ext-apps 2.0 moved onto the MCP TypeScript SDK v2. Its peers are now @modelcontextprotocol/client, core, and server at ^2.0.0, plus zod@^4.2.0. The last 1.x release, 1.7.5, peered on @modelcontextprotocol/sdk 1.x.
  2. 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.
  3. 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:

ImportJobWho needs it
@modelcontextprotocol/serverMcpServer, tools, resources, stdio, Web Standard HTTP transportServer authors
@modelcontextprotocol/nodeNodeStreamableHTTPServerTransport for Node http serversServer authors on Node HTTP
@modelcontextprotocol/expresscreateMcpExpressApp with host and origin checksServer authors using Express
@modelcontextprotocol/clientProtocol base class that App and AppBridge extendEveryone (required peer)
@modelcontextprotocol/ext-appsApp, PostMessageTransport, view lifecycle, host context, app actionsApp view developers
@modelcontextprotocol/ext-apps/reactuseApp, useHostStyles, useDocumentTheme, useAutoResizeReact view developers
@modelcontextprotocol/ext-apps/serverregisterAppTool, registerAppResource, RESOURCE_MIME_TYPE, getUiCapabilityMCP App server authors
@modelcontextprotocol/ext-apps/app-bridgeHost-side iframe rendering and message proxyingMCP host developers
@modelcontextprotocol/ext-apps/app-with-depsApp with client, core, and zod bundled inPages 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:

  1. _meta.ui.resourceUri to the UI tool.
  2. A matching app resource.
  3. The MCP App resource MIME type.
  4. 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 through RESOURCE_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:

OptionDefaultWhat it does
autoResizetrueWatches the document with ResizeObserver and sends ui/notifications/size-changed
strictfalseThrows instead of warning when you call a host method, such as callServerTool, before connect() finishes. The SDK says throwing will become the default
allowUnsafeEvalfalseWhen 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:

  • useApp to create and connect an App and expose { app, isConnected, error }.
  • useHostStyles to apply host CSS variables and fonts.
  • useDocumentTheme to follow the host theme.
  • useAutoResize when 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:

Area1.x2.x
Base SDK peer@modelcontextprotocol/sdk 1.xclient, core, server at ^2.0.0. Uninstall the v1 package
ZodZod 3 or 4zod@^4.2.0, or another Standard JSON Schema library
Tool schemasRaw shapesz.object({...}). Raw shapes still work but are deprecated
Handler contextextra.signal, extra.requestId, extra.authInfoctx.mcpReq.signal, ctx.mcpReq.id, ctx.http?.authInfo
Custom request handlerssetRequestHandler(Schema, handler)setRequestHandler('method', { params }, (params, ctx) => ...). Old form warns once and goes away in 3.0
ErrorsMcpError with numeric codeProtocolError for remote errors, SdkError with string codes such as REQUEST_TIMEOUT
Unknown tool via callServerTool on a v2 serverResolves with isError: trueRejects with JSON-RPC error -32602
Bundlesapp-with-deps included the old SDKapp-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.resourceUri exists.
  • 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:

  • content gives non-UI hosts a useful fallback.
  • structuredContent matches the view’s expected shape, and outputSchema if you declare one.
  • _meta contains 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

Documentation →
npx sunpeak new

Further Reading

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.