-This repo contains the SDK and [specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)).
+
+
+ Excalidraw built with MCP Apps, running in Claude
+
-MCP Apps are a proposed standard inspired by [MCP-UI](https://mcpui.dev/) and [OpenAI's Apps SDK](https://developers.openai.com/apps-sdk/) to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots.
+## Table of Contents
-## Why MCP Apps?
+- [Build with Agent Skills](#build-with-agent-skills)
+- [Supported Clients](#supported-clients)
+- [Why MCP Apps?](#why-mcp-apps)
+- [How It Works](#how-it-works)
+- [Getting Started](#getting-started)
+- [Using the SDK](#using-the-sdk)
+- [Examples](#examples)
+- [Specification](#specification)
+- [Resources](#resources)
+- [Contributing](#contributing)
-MCP tools return text and structured data. That works for many cases, but not when you need an interactive UI, like a chart, form, or video player.
+## Build with Agent Skills
-MCP Apps provide a standardized way to deliver interactive UIs from MCP servers. Your UI renders inline in the conversation, in context, in any compliant host.
+The fastest way to build an MCP App is to let your AI coding agent do it. This
+repo ships four [Agent Skills](https://agentskills.io/) โ install them once,
+then just ask:
-## How It Works
+| Skill | What it does | Try it |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------- |
+| [`create-mcp-app`](./plugins/mcp-apps/skills/create-mcp-app/SKILL.md) | Scaffolds a new MCP App with an interactive UI from scratch | _"Create an MCP App"_ |
+| [`migrate-oai-app`](./plugins/mcp-apps/skills/migrate-oai-app/SKILL.md) | Converts an existing OpenAI App to use MCP Apps | _"Migrate from OpenAI Apps SDK"_ |
+| [`add-app-to-server`](./plugins/mcp-apps/skills/add-app-to-server/SKILL.md) | Adds interactive UI to an existing MCP server's tools | _"Add UI to my MCP server"_ |
+| [`convert-web-app`](./plugins/mcp-apps/skills/convert-web-app/SKILL.md) | Turns an existing web app into a hybrid web + MCP App | _"Add MCP App support to my web app"_ |
-MCP Apps extend the Model Context Protocol by letting tools declare UI resources:
+### Install the Skills
-1. **Tool definition** โ Your tool declares a `ui://` resource containing its HTML interface
-2. **Tool call** โ The LLM calls the tool on your server
-3. **Host renders** โ The host fetches the resource and displays it in a sandboxed iframe
-4. **Bidirectional communication** โ The host passes tool data to the UI via notifications, and the UI can call other tools through the host
-
-## Using the SDK
-
-This SDK serves two audiences:
-
-### For App Developers
-
-Build interactive UIs that run inside MCP-enabled chat clients.
-
-- **SDK for Apps**: `@modelcontextprotocol/ext-apps` โ [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/app.html)
-- **React hooks**: `@modelcontextprotocol/ext-apps/react` โ [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/_modelcontextprotocol_ext-apps_react.html)
-
-### For Host Developers
-
-Embed and communicate with MCP Apps in your chat application.
-
-- **SDK for Hosts**: `@modelcontextprotocol/ext-apps/app-bridge` โ [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/app-bridge.html)
-
-There's no _supported_ host implementation in this repo (beyond the [examples/basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example).
-
-We have [contributed a tentative implementation](https://github.com/MCP-UI-Org/mcp-ui/pull/147) of hosting / iframing / sandboxing logic to the [MCP-UI](https://github.com/idosal/mcp-ui) repository, and expect OSS clients may use it, while other clients might roll their own hosting logic.
-
-## Installation
-
-```bash
-npm install -S @modelcontextprotocol/ext-apps
-```
-
-### Install Agent Skills
-
-This repository provides two [Agent Skills](https://agentskills.io/) for building MCP Apps. You can install the skills as a Claude Code plugin:
+**Claude Code** โ install via the plugin marketplace:
```
/plugin marketplace add modelcontextprotocol/ext-apps
/plugin install mcp-apps@modelcontextprotocol-ext-apps
```
-For more information, including instructions for installing the skills in your favorite AI coding agent, see the [agent skills guide](./docs/agent-skills.md).
+**Other agents** โ any AI coding agent that supports
+[Agent Skills](https://agentskills.io/) can use these skills. See the
+[agent skills guide](./docs/agent-skills.md) for manual installation
+instructions.
+
+Once installed, verify by asking your agent _"What skills do you have?"_ โ you
+should see `create-mcp-app`, `migrate-oai-app`, `add-app-to-server`, and
+`convert-web-app` in the list. Then just ask it to create or migrate an app and
+it will guide you through the rest.
+
+## Supported Clients
+
+
+
+
+
+
+
+
+
+
+
+
+> [!NOTE]
+> MCP Apps is an extension to the
+> [core MCP specification](https://modelcontextprotocol.io/specification). Host
+> support varies โ see the
+> [clients page](https://modelcontextprotocol.io/clients) for the full list.
+
+## Why MCP Apps?
+
+MCP tools return text and structured data. That works for many cases, but not
+when you need an interactive UI, like a chart, form, design canvas or video player.
+
+MCP Apps provide a standardized way to deliver interactive UIs from MCP servers.
+Your UI renders inline in the conversation, in context, in any compliant host.
+
+## How It Works
+
+MCP Apps extend the Model Context Protocol by letting tools declare UI
+resources:
+
+1. **Tool definition** โ Your tool declares a `ui://` resource containing its
+ HTML interface
+2. **Tool call** โ The LLM calls the tool on your server
+3. **Host renders** โ The host fetches the resource and displays it in a
+ sandboxed iframe
+4. **Bidirectional communication** โ The host passes tool data to the UI via
+ notifications, and the UI can call other tools through the host
+
+## Getting Started
+
+Requires Node.js 20+. The base MCP SDK packages are `^2.0.0` peers of
+`ext-apps` (`@modelcontextprotocol/core` is a required peer that `client` already depends on, so npm installs it for you).
+
+For a View or host:
+
+```bash
+npm install -S @modelcontextprotocol/ext-apps \
+ @modelcontextprotocol/client@^2.0.0 \
+ zod@^4.2.0
+```
+
+For an MCP server, add the server package (and, for HTTP transports, the Node
+and Express adapters):
+
+```bash
+npm install -S @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
+```
+
+The wire protocol is unchanged between `ext-apps` 1.x and 2.x: a 2.x View works
+in a 1.x host and a 2.x host renders 1.x Views. See the
+[migration guide](https://apps.extensions.modelcontextprotocol.io/api/documents/migrate-to-v2.html)
+when upgrading from 1.x.
+
+**New here?** Start with the
+[Quickstart Guide](https://apps.extensions.modelcontextprotocol.io/api/documents/quickstart.html)
+to build your first MCP App.
+
+## Using the SDK
+
+The SDK serves three roles: app developers building interactive Views, host
+developers embedding those Views, and MCP server authors registering tools with
+UI metadata.
+
+| Package | Purpose | Docs |
+| ------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `@modelcontextprotocol/ext-apps` | Build interactive Views (App class, PostMessageTransport) | [API Docs โ](https://apps.extensions.modelcontextprotocol.io/api/modules/app.html) |
+| `@modelcontextprotocol/ext-apps/react` | React hooks for Views (useApp, useHostStyles, etc.) | [API Docs โ](https://apps.extensions.modelcontextprotocol.io/api/modules/_modelcontextprotocol_ext-apps_react.html) |
+| `@modelcontextprotocol/ext-apps/app-bridge` | Embed and communicate with Views in your chat client | [API Docs โ](https://apps.extensions.modelcontextprotocol.io/api/modules/app-bridge.html) |
+| `@modelcontextprotocol/ext-apps/server` | Register tools and resources on your MCP server | [API Docs โ](https://apps.extensions.modelcontextprotocol.io/api/modules/server-helpers.html) |
+
+There's no _supported_ host implementation in this repo (beyond the
+[examples/basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host)
+example).
+
+The [MCP-UI](https://github.com/idosal/mcp-ui) client SDK offers a
+fully-featured MCP Apps framework used by a few hosts. Clients may choose to use
+it or roll their own implementation.
## Examples
-The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains demo apps showcasing real-world use cases.
+The
+[`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples)
+directory contains demo apps showcasing real-world use cases.
| | | |
@@ -88,7 +206,9 @@ The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/exa
#### With basic-host
-To run all examples locally using [basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) (the reference host implementation included in this repo):
+To run all examples locally using
+[basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host)
+(the reference host implementation included in this repo):
```bash
git clone https://github.com/modelcontextprotocol/ext-apps.git
@@ -101,234 +221,64 @@ Then open http://localhost:8080/.
#### With MCP Clients
-To use these examples with MCP clients that support the stdio transport (such as Claude Desktop or VS Code), add this MCP server configuration to your client's settings:
-
-
-MCP client configuration for all examples (using stdio)
+Every Node.js example is published as `@modelcontextprotocol/server-`. To
+add one to an MCP client that supports stdio (Claude Desktop, VS Code, etc.),
+use this pattern:
```json
{
"mcpServers": {
- "basic-react": {
+ "": {
"command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-", "--stdio"]
+ }
+ }
+}
+```
+
+For example, to add the map server: `@modelcontextprotocol/server-map`. The
+Python examples (`qr-server`, `say-server`) use `uv run` instead โ see their
+READMEs for details.
+
+#### Local Development
+
+To test local modifications with an MCP client, clone the repo, install, then
+point your client at a local build:
+
+```json
+{
+ "mcpServers": {
+ "": {
+ "command": "bash",
"args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-basic-react",
- "--stdio"
- ]
- },
- "basic-vanillajs": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-basic-vanillajs",
- "--stdio"
- ]
- },
- "basic-vue": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-basic-vue",
- "--stdio"
- ]
- },
- "basic-svelte": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-basic-svelte",
- "--stdio"
- ]
- },
- "basic-preact": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-basic-preact",
- "--stdio"
- ]
- },
- "basic-solid": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-basic-solid",
- "--stdio"
- ]
- },
- "budget-allocator": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-budget-allocator",
- "--stdio"
- ]
- },
- "cohort-heatmap": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-cohort-heatmap",
- "--stdio"
- ]
- },
- "customer-segmentation": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-customer-segmentation",
- "--stdio"
- ]
- },
- "map": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-map",
- "--stdio"
- ]
- },
- "pdf": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-pdf",
- "--stdio"
- ]
- },
- "scenario-modeler": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-scenario-modeler",
- "--stdio"
- ]
- },
- "shadertoy": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-shadertoy",
- "--stdio"
- ]
- },
- "sheet-music": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-sheet-music",
- "--stdio"
- ]
- },
- "system-monitor": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-system-monitor",
- "--stdio"
- ]
- },
- "threejs": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-threejs",
- "--stdio"
- ]
- },
- "transcript": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-transcript",
- "--stdio"
- ]
- },
- "video-resource": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-video-resource",
- "--stdio"
- ]
- },
- "wiki-explorer": {
- "command": "npx",
- "args": [
- "-y",
- "--silent",
- "--registry=https://registry.npmjs.org/",
- "@modelcontextprotocol/server-wiki-explorer",
- "--stdio"
- ]
- },
- "qr": {
- "command": "uv",
- "args": [
- "run",
- "/path/to/ext-apps/examples/qr-server/server.py",
- "--stdio"
- ]
- },
- "say": {
- "command": "uv",
- "args": [
- "run",
- "--default-index",
- "https://pypi.org/simple",
- "https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/refs/heads/main/examples/say-server/server.py",
- "--stdio"
+ "-c",
+ "cd ~/code/ext-apps/examples/-server && npm run build >&2 && node dist/index.js --stdio"
]
}
}
}
```
-
+## Specification
-> [!NOTE]
-> The `qr` server requires cloning the repository first. See [qr-server README](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server) for details.
+
+
+| Version | Status | Link |
+| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **2026-01-26** | Stable | [specification/2026-01-26/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) |
+| **draft** | Development | [specification/draft/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) |
+
+
## Resources
-- [Quickstart Guide](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html)
-- [API Documentation](https://modelcontextprotocol.github.io/ext-apps/api/)
-- [Draft Specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx)
+- [Quickstart Guide](https://apps.extensions.modelcontextprotocol.io/api/documents/quickstart.html)
+- [API Documentation](https://apps.extensions.modelcontextprotocol.io/api/)
+- [Specification (2026-01-26)](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)
+ ([Draft](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx))
- [SEP-1865 Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
+guidelines on how to get started, submit pull requests, and report issues.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..5029242
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,21 @@
+# Security Policy
+
+Thank you for helping keep the Model Context Protocol and its ecosystem secure.
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in this repository, please report it through
+the [GitHub Security Advisory process](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
+for this repository.
+
+Please **do not** report security vulnerabilities through public GitHub issues, discussions,
+or pull requests.
+
+## What to Include
+
+To help us triage and respond quickly, please include:
+
+- A description of the vulnerability
+- Steps to reproduce the issue
+- The potential impact
+- Any suggested fixes (optional)
diff --git a/build.bun.ts b/build.bun.ts
index 0e53418..61361e6 100644
--- a/build.bun.ts
+++ b/build.bun.ts
@@ -1,9 +1,18 @@
#!/usr/bin/env bun
import { $ } from "bun";
+import { cpSync, mkdirSync, rmSync } from "node:fs";
+
+// Avoid publishing artifacts left behind by an earlier build or branch.
+rmSync("dist", { recursive: true, force: true });
// Run TypeScript compiler for type declarations
await $`tsc`;
+// Copy schema.json (tsc is emitDeclarationOnly, Bun.build doesn't emit JSON assets).
+// Needed for the "./schema.json" package export.
+mkdirSync("dist/src/generated", { recursive: true });
+cpSync("src/generated/schema.json", "dist/src/generated/schema.json");
+
const isDevelopment = Bun.env.NODE_ENV === "development";
// Build all JavaScript/TypeScript files
@@ -25,10 +34,20 @@ function buildJs(
});
}
+// Peer dependencies stay external in the standard entry points so consumers
+// share one base MCP SDK and Zod instance. The *-with-deps entry points keep
+// bundling these dependencies for standalone browser use.
+const PEER_EXTERNALS = [
+ "@modelcontextprotocol/client",
+ "@modelcontextprotocol/core",
+ "@modelcontextprotocol/server",
+ "zod",
+];
+
await Promise.all([
buildJs("src/app.ts", {
outdir: "dist/src",
- external: ["@modelcontextprotocol/sdk"],
+ external: PEER_EXTERNALS,
}),
buildJs("src/app.ts", {
outdir: "dist/src",
@@ -36,19 +55,19 @@ await Promise.all([
}),
buildJs("src/app-bridge.ts", {
outdir: "dist/src",
- external: ["@modelcontextprotocol/sdk"],
+ external: PEER_EXTERNALS,
}),
buildJs("src/react/index.tsx", {
outdir: "dist/src/react",
- external: ["react", "react-dom", "@modelcontextprotocol/sdk"],
+ external: ["react", "react-dom", ...PEER_EXTERNALS],
}),
buildJs("src/react/index.tsx", {
outdir: "dist/src/react",
- external: ["react", "react-dom", "@modelcontextprotocol/sdk"],
+ external: ["react", "react-dom"],
naming: { entry: "react-with-deps.js" },
}),
buildJs("src/server/index.ts", {
outdir: "dist/src/server",
- external: ["@modelcontextprotocol/sdk"],
+ external: PEER_EXTERNALS,
}),
]);
diff --git a/docs/agent-skills.md b/docs/agent-skills.md
index 4d957a2..d27ad71 100644
--- a/docs/agent-skills.md
+++ b/docs/agent-skills.md
@@ -1,15 +1,19 @@
---
title: Agent Skills
+group: Getting Started
+description: Use Agent Skills to build, migrate, and extend MCP Apps with AI coding agents. Install skills that scaffold new apps, convert OpenAI Apps, and add UI to existing servers.
---
# Agent Skills
[Agent Skills](https://agentskills.io/) are instruction sets that guide AI coding agents through tasks. When you invoke a skill, the agent takes the lead โ it asks clarifying questions, makes decisions based on your codebase, and executes the work.
-This repository provides two skills:
+This repository provides four skills:
- [**create-mcp-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/create-mcp-app/SKILL.md) โ scaffolds a new MCP App with an interactive UI
- [**migrate-oai-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/migrate-oai-app/SKILL.md) โ migrates an existing OpenAI App to the MCP Apps SDK
+- [**add-app-to-server**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/add-app-to-server/SKILL.md) โ adds interactive UI to an existing MCP server's tools
+- [**convert-web-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/convert-web-app/SKILL.md) โ converts an existing web application into an MCP App
## Install the Skills
@@ -51,7 +55,7 @@ Then copy the skills from `plugins/mcp-apps/skills/` to your agent's skills dire
## Verify Installation
-Ask your agent "What skills do you have?" โ you should see `create-mcp-app` and `migrate-oai-app` among the available skills.
+Ask your agent "What skills do you have?" โ you should see `create-mcp-app`, `migrate-oai-app`, `add-app-to-server`, and `convert-web-app` among the available skills.
## Invoke a Skill
@@ -59,6 +63,8 @@ Try invoking the skills by asking your agent:
- "Create an MCP App" โ scaffolds a new MCP App with an interactive UI
- "Migrate from OpenAI Apps SDK" โ converts an existing OpenAI App to use the MCP Apps SDK
+- "Add UI to my MCP server" โ adds interactive UI to an existing MCP server's tools
+- "Convert my web app to an MCP App" โ converts an existing web application into an MCP App
The agent will guide you through the process, asking clarifying questions as needed.
diff --git a/docs/authorization.md b/docs/authorization.md
new file mode 100644
index 0000000..df7adc6
--- /dev/null
+++ b/docs/authorization.md
@@ -0,0 +1,211 @@
+---
+title: Authorization
+group: Security
+description: Learn how to protect MCP App tools with OAuth authorization, including per-server and per-tool auth patterns, token verification, and UI-initiated auth escalation.
+---
+
+# Authorization
+
+MCP Apps can protect tools behind OAuth-based authorization, as defined in the [MCP specification](https://modelcontextprotocol.io/specification/latest/basic/authorization). There are two approaches:
+
+- **Per-server authorization** โ The entire MCP server requires authorization at connection time. Every request must include a valid token, regardless of which tool is being called. This is the simpler model when all tools are sensitive.
+- **Per-tool authorization** โ Only specific tools require authorization. Public tools work without a token, and the OAuth flow is triggered only when the user calls a protected tool. This lets you mix public and protected tools in the same server.
+
+## Shared setup
+
+Regardless of which approach you choose, you need OAuth discovery metadata and token verification. These are the same for both.
+
+### OAuth discovery metadata
+
+The MCP specification requires servers to implement [authorization server discovery](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-server-discovery) so clients know how to obtain authorization. Two well-known endpoints are needed:
+
+**[Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)** (`/.well-known/oauth-protected-resource`) โ describes the resource server and identifies which authorization server(s) can issue tokens for it. The MCP SDK's `mcpAuthRouter` handles this automatically.
+
+**Authorization Server Metadata** (`/.well-known/oauth-authorization-server`) โ advertises the authorization and token endpoints, supported scopes, and whether [Client ID Metadata Documents](https://modelcontextprotocol.io/specification/latest/basic/authorization#client-id-metadata-documents) (CIMD) is supported:
+
+```ts
+app.get("/.well-known/oauth-authorization-server", (_req, res) => {
+ res.json({
+ ...oauthMetadata,
+ client_id_metadata_document_supported: true,
+ });
+});
+```
+
+Setting `client_id_metadata_document_supported: true` tells MCP clients to use CIMD instead of [Dynamic Client Registration](https://modelcontextprotocol.io/specification/latest/basic/authorization#dynamic-client-registration) (DCR). With CIMD, the `client_id` is a URL that serves the client's metadata document, removing the need for a registration endpoint. See [Client Registration Approaches](https://modelcontextprotocol.io/specification/latest/basic/authorization#client-registration-approaches) in the spec for the full list of options and priority order.
+
+### Token verification
+
+Verify access tokens as JWTs against the identity provider's JWKS endpoint. The `jose` library handles key fetching and caching:
+
+```ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+
+const JWKS = createRemoteJWKSet(new URL(`${IDP_DOMAIN}/.well-known/jwks.json`));
+
+const { payload } = await jwtVerify(token, JWKS, {
+ issuer: IDP_DOMAIN,
+});
+```
+
+MCP servers must validate that tokens were issued specifically for them โ see [Token Handling](https://modelcontextprotocol.io/specification/latest/basic/authorization#token-handling) and [Access Token Privilege Restriction](https://modelcontextprotocol.io/specification/latest/basic/authorization#access-token-privilege-restriction) in the spec for the full requirements.
+
+## Per-server authorization
+
+With per-server authorization, every request to the `/mcp` endpoint must include a valid Bearer token. Any unauthorized request receives HTTP `401`, and the host must complete the OAuth flow before the client can use any tools. This is the right choice when all tools are sensitive and there's no value in allowing unauthorized access.
+
+The TypeScript MCP SDK supports this out of the box via `mcpAuthRouter` and `ProxyOAuthServerProvider` โ no custom HTTP handler logic is needed. See the [MCP SDK documentation](https://github.com/modelcontextprotocol/typescript-sdk) for setup details.
+
+## Per-tool authorization
+
+With per-tool authorization, the `/mcp` endpoint handler inspects the raw JSON-RPC request body, checks whether any message targets a protected tool, and only enforces authorization for those calls. Public tools pass through without a token.
+
+### How it works
+
+1. The server maintains a set of tool names that require authorization
+2. When a JSON-RPC request arrives at the `/mcp` endpoint, the server inspects the request body to determine if any message is a `tools/call` targeting a protected tool
+3. If a protected tool is being called and no valid Bearer token is present, the server returns HTTP `401` with a [`WWW-Authenticate` header](https://modelcontextprotocol.io/specification/latest/basic/authorization#protected-resource-metadata-discovery-requirements) pointing to its [Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)
+4. The MCP host (e.g., Claude Desktop) sees the `401`, discovers the authorization server via the metadata URL, runs the [OAuth flow](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-flow-steps) with the user, and retries the request with the acquired token
+5. On retry, the server verifies the token, extracts the user identity, and creates a per-request MCP server instance with that auth context
+6. Unprotected tools pass through without any token check โ they work for everyone
+
+This design means authorization is enforced at the HTTP boundary (as [required by the spec](https://modelcontextprotocol.io/specification/latest/basic/authorization#access-token-usage)), not as a tool-level error. The MCP server itself never sees unauthorized requests for protected tools.
+
+### Enforcing HTTP 401
+
+The [MCP auth specification](https://modelcontextprotocol.io/specification/latest/basic/authorization#access-token-usage) requires protected resources to return HTTP `401` responses โ not tool-level errors.
+
+Start by defining which tools require authorization. Then, in the `/mcp` endpoint handler, inspect the raw JSON-RPC request body, check whether any message targets a protected tool, and either verify the Bearer token or return `401` before the request ever reaches the MCP server:
+
+```ts
+/** Tools that require a valid Bearer token โ checked at the HTTP level for proper 401. */
+const PROTECTED_TOOLS = new Set(["get_account_balance", "manage_branch_admin"]);
+
+app.all("/mcp", async (req, res) => {
+ // Parse the JSON-RPC body โ it may be a single message or a batch
+ const messages = Array.isArray(req.body) ? req.body : [req.body];
+
+ // Check if any message is a tools/call for a protected tool
+ const needsAuth = messages.some(
+ (msg: any) =>
+ msg?.method === "tools/call" && PROTECTED_TOOLS.has(msg.params?.name),
+ );
+
+ // Extract and verify the Bearer token
+ let authInfo: AuthInfo | undefined;
+ const authHeader = req.headers.authorization;
+
+ if (authHeader?.startsWith("Bearer ")) {
+ try {
+ const token = authHeader.slice(7);
+ const { payload } = await jwtVerify(token, JWKS, {
+ issuer: IDP_DOMAIN,
+ });
+ authInfo = { token, sub: payload.sub as string };
+ } catch {
+ if (needsAuth) {
+ return res
+ .status(401)
+ .set(
+ "WWW-Authenticate",
+ `Bearer resource_metadata="${resourceMetadataUrl}"`,
+ )
+ .json({
+ error: "invalid_token",
+ error_description: "The access token is invalid",
+ });
+ }
+ }
+ } else if (needsAuth) {
+ return res
+ .status(401)
+ .set(
+ "WWW-Authenticate",
+ `Bearer resource_metadata="${resourceMetadataUrl}"`,
+ )
+ .json({
+ error: "invalid_token",
+ error_description: "Authorization required",
+ });
+ }
+
+ // Create a per-request MCP server with the auth context.
+ // authInfo is undefined for public tool calls, populated for
+ // authenticated requests โ tool handlers use it to scope data
+ // to the authenticated user.
+ const server = createServer(authInfo);
+ // ... handle the request with transport
+});
+```
+
+The `WWW-Authenticate` header includes the [Protected Resource Metadata](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-server-location) URL, which tells the client where to discover the authorization server.
+
+### Defence-in-depth in tool handlers
+
+Even though the HTTP layer enforces authorization, protected tool handlers should also verify `authInfo` as a defence-in-depth measure. If the HTTP layer is misconfigured or bypassed, the tool handler catches unauthorized access:
+
+```ts
+registerAppTool(
+ server,
+ "get_account_balance",
+ {
+ description: "Get account balance",
+ inputSchema: z.object({ accountId: z.string() }),
+ },
+ async ({ accountId }) => {
+ if (!authInfo) {
+ return {
+ isError: true,
+ content: [
+ {
+ type: "text",
+ text: "Authorization required to access account data.",
+ },
+ ],
+ };
+ }
+
+ const balance = await getBalance(authInfo.sub, accountId);
+ return {
+ content: [{ type: "text", text: `Balance: ${balance}` }],
+ };
+ },
+);
+```
+
+### UI-initiated auth escalation
+
+A powerful pattern is mixing public and protected tools in the same app. The app loads with public data (no authorization required), and the OAuth flow is triggered only when the user performs a protected action. This is a practical application of the [step-up authorization flow](https://modelcontextprotocol.io/specification/latest/basic/authorization#step-up-authorization-flow) described in the spec:
+
+1. A public tool (e.g., `manage_branch`) loads the UI without requiring authorization
+2. The user clicks a button that calls a protected tool via `app.callServerTool()`
+3. The MCP host receives HTTP `401` and automatically runs the OAuth flow
+4. After the user completes the OAuth flow, the host retries the tool call with the acquired token
+5. The protected data appears in the UI
+
+```tsx
+function BranchItem({ branch }: { branch: Branch }) {
+ const [adminData, setAdminData] = useState(null);
+
+ async function handleManage() {
+ // This call may trigger the OAuth flow if the user
+ // hasn't been authorized yet โ the host handles it
+ // transparently.
+ const result = await app.callServerTool({
+ name: "manage_branch_admin",
+ arguments: { branch_id: branch.id },
+ });
+ setAdminData(result.structuredContent);
+ }
+
+ return (
+
+ {branch.name}
+
+ {adminData && }
+
+ );
+}
+```
+
+This pattern keeps the initial experience fast (no login wall) while securing sensitive operations behind authorization. The host manages the entire OAuth flow โ the app code simply calls the tool and handles the result.
diff --git a/docs/csp-cors.md b/docs/csp-cors.md
new file mode 100644
index 0000000..8978ab6
--- /dev/null
+++ b/docs/csp-cors.md
@@ -0,0 +1,64 @@
+---
+title: CSP and CORS
+group: Security
+description: Configure Content Security Policy and CORS for MCP Apps that make network requests from sandboxed iframes, including connectDomains, resourceDomains, and stable origin setup.
+---
+
+# CSP & CORS
+
+Unlike regular web apps, MCP Apps HTML is served as an MCP resource and runs in a sandboxed iframe with no same-origin server. Any app that makes network requests must configure Content Security Policy (CSP) and possibly CORS.
+
+**CSP** controls what the _browser_ allows. You must declare _all_ origins in {@link types!McpUiResourceMeta.csp `_meta.ui.csp`} ({@link types!McpUiResourceCsp `McpUiResourceCsp`}) โ including `localhost` during development. Declare `connectDomains` for fetch/XHR/WebSocket requests and `resourceDomains` for scripts, stylesheets, images, and fonts.
+
+**CORS** controls what the _API server_ allows. Public APIs that respond with `Access-Control-Allow-Origin: *` or use API key authentication work without CORS configuration. For APIs that allowlist specific origins, use {@link types!McpUiResourceMeta.domain `_meta.ui.domain`} to give the app a stable origin that the API server can allowlist. The format is host-specific, so check each host's documentation for its supported format.
+
+
+```ts source="../src/server/index.examples.ts#registerAppResource_withDomain"
+// Computes a stable origin from an MCP server URL for hosting in Claude.
+function computeAppDomainForClaude(mcpServerUrl: string): string {
+ const hash = crypto
+ .createHash("sha256")
+ .update(mcpServerUrl)
+ .digest("hex")
+ .slice(0, 32);
+ return `${hash}.claudemcpcontent.com`;
+}
+
+const APP_DOMAIN = computeAppDomainForClaude("https://example.com/mcp");
+
+registerAppResource(
+ server,
+ "Company Dashboard",
+ "ui://dashboard/view.html",
+ {
+ description: "Internal dashboard with company data",
+ },
+ async () => ({
+ contents: [
+ {
+ uri: "ui://dashboard/view.html",
+ mimeType: RESOURCE_MIME_TYPE,
+ text: dashboardHtml,
+ _meta: {
+ ui: {
+ // CSP: tell browser the app is allowed to make requests
+ csp: {
+ connectDomains: ["https://api.example.com"],
+ },
+ // CORS: give app a stable origin for the API server to allowlist
+ //
+ // (Public APIs that use `Access-Control-Allow-Origin: *` or API
+ // key auth don't need this.)
+ domain: APP_DOMAIN,
+ },
+ },
+ },
+ ],
+ }),
+);
+```
+
+Note that `_meta.ui.csp` and `_meta.ui.domain` are set in the `contents[]` objects returned by the resource read callback, not in `registerAppResource()`'s config object.
+
+> [!NOTE]
+> For full examples that configures CSP, see: [`examples/sheet-music-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/sheet-music-server) (`connectDomains`) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (`connectDomains` and `resourceDomains`).
diff --git a/docs/favicons/apple-touch-icon.png b/docs/favicons/apple-touch-icon.png
new file mode 100644
index 0000000..2e10abc
Binary files /dev/null and b/docs/favicons/apple-touch-icon.png differ
diff --git a/docs/favicons/favicon-16x16.png b/docs/favicons/favicon-16x16.png
new file mode 100644
index 0000000..1548f7e
Binary files /dev/null and b/docs/favicons/favicon-16x16.png differ
diff --git a/docs/favicons/favicon-32x32.png b/docs/favicons/favicon-32x32.png
new file mode 100644
index 0000000..88f78f6
Binary files /dev/null and b/docs/favicons/favicon-32x32.png differ
diff --git a/docs/favicons/favicon-dark-16x16.png b/docs/favicons/favicon-dark-16x16.png
new file mode 100644
index 0000000..1548f7e
Binary files /dev/null and b/docs/favicons/favicon-dark-16x16.png differ
diff --git a/docs/favicons/favicon-dark-32x32.png b/docs/favicons/favicon-dark-32x32.png
new file mode 100644
index 0000000..b861b12
Binary files /dev/null and b/docs/favicons/favicon-dark-32x32.png differ
diff --git a/docs/favicons/favicon-dark.ico b/docs/favicons/favicon-dark.ico
new file mode 100644
index 0000000..fd1f24d
Binary files /dev/null and b/docs/favicons/favicon-dark.ico differ
diff --git a/docs/favicons/favicon.ico b/docs/favicons/favicon.ico
new file mode 100644
index 0000000..b92e162
Binary files /dev/null and b/docs/favicons/favicon.ico differ
diff --git a/docs/mcp-theme.css b/docs/mcp-theme.css
new file mode 100644
index 0000000..d786e55
--- /dev/null
+++ b/docs/mcp-theme.css
@@ -0,0 +1,216 @@
+/*
+ * MCP Apps custom theme โ aligns TypeDoc styling with modelcontextprotocol.io
+ */
+
+@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap");
+
+/* ------------------------------------------------------------------ */
+/* Fonts */
+/* ------------------------------------------------------------------ */
+
+:root {
+ --font-family-text:
+ "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+ --font-family-code:
+ "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
+body {
+ font-family: var(--font-family-text);
+ -webkit-font-smoothing: antialiased;
+ -moz-osx-font-smoothing: grayscale;
+}
+
+/* ------------------------------------------------------------------ */
+/* Light mode colors */
+/* ------------------------------------------------------------------ */
+
+:root {
+ --light-color-background: #ffffff;
+ --light-color-background-secondary: #f9fafb;
+ --light-color-background-navbar: #ffffff;
+ --light-color-accent: #e5e7eb;
+ --light-color-text: #111827;
+ --light-color-text-aside: #6b7280;
+}
+
+/* ------------------------------------------------------------------ */
+/* Dark mode colors */
+/* ------------------------------------------------------------------ */
+
+:root {
+ --dark-color-background: #0f1117;
+ --dark-color-background-secondary: #161b22;
+ --dark-color-background-navbar: #0f1117;
+ --dark-color-accent: #30363d;
+ --dark-color-text: #f0f6fc;
+ --dark-color-text-aside: #8b949e;
+}
+
+/* ------------------------------------------------------------------ */
+/* Header โ taller, frosted glass */
+/* ------------------------------------------------------------------ */
+
+:root {
+ --dim-toolbar-contents-height: 3.5rem;
+}
+
+.tsd-page-toolbar {
+ backdrop-filter: blur(12px);
+ -webkit-backdrop-filter: blur(12px);
+}
+
+@media (prefers-color-scheme: light) {
+ .tsd-page-toolbar {
+ background-color: rgba(255, 255, 255, 0.85);
+ }
+}
+
+@media (prefers-color-scheme: dark) {
+ .tsd-page-toolbar {
+ background-color: rgba(15, 17, 23, 0.75);
+ }
+}
+
+:root[data-theme="light"] .tsd-page-toolbar {
+ background-color: rgba(255, 255, 255, 0.85);
+}
+
+:root[data-theme="dark"] .tsd-page-toolbar {
+ background-color: rgba(15, 17, 23, 0.75);
+}
+
+/* ------------------------------------------------------------------ */
+/* Theme-aware logo (rewritten from README by mcpstyle plugin) */
+/* ------------------------------------------------------------------ */
+
+/* Explicit theme selection via TypeDoc switcher โ takes precedence */
+:root[data-theme="light"] .mcp-logo-dark,
+:root[data-theme="dark"] .mcp-logo-light {
+ display: none;
+}
+
+/* "OS" mode (data-theme='os') follows prefers-color-scheme */
+@media (prefers-color-scheme: light) {
+ :root[data-theme="os"] .mcp-logo-dark {
+ display: none;
+ }
+}
+
+@media (prefers-color-scheme: dark) {
+ :root[data-theme="os"] .mcp-logo-light {
+ display: none;
+ }
+}
+
+/* ------------------------------------------------------------------ */
+/* Sidebar navigation (matches modelcontextprotocol.io sidebar) */
+/* ------------------------------------------------------------------ */
+
+.tsd-navigation a {
+ padding: 0.375rem 0.75rem;
+ font-size: 0.875rem;
+ line-height: 1.5;
+ border-radius: 0.75rem;
+ color: var(--color-text-aside);
+ transition:
+ background-color 0.15s ease,
+ color 0.15s ease;
+}
+
+.tsd-navigation a:hover:not(.current) {
+ background-color: rgba(107, 114, 128, 0.05);
+ color: var(--color-text);
+}
+
+.tsd-navigation a.current {
+ background-color: rgba(107, 114, 128, 0.15);
+ color: var(--color-text);
+ font-weight: 700;
+}
+
+/* Group headers (Documents, Security, API Documentation) */
+.tsd-accordion-summary > h3 {
+ font-weight: 600;
+ font-size: 0.875rem;
+ letter-spacing: 0.01em;
+}
+
+.site-menu {
+ padding: 1.25rem 0;
+}
+
+@media (prefers-color-scheme: dark) {
+ .tsd-navigation a {
+ color: var(--color-text-aside);
+ }
+
+ .tsd-navigation a:hover:not(.current) {
+ background-color: rgba(229, 231, 235, 0.05);
+ color: var(--color-text);
+ }
+
+ .tsd-navigation a.current {
+ background-color: rgba(229, 231, 235, 0.15);
+ color: var(--color-text);
+ font-weight: 700;
+ }
+}
+
+:root[data-theme="dark"] .tsd-navigation a {
+ color: var(--color-text-aside);
+}
+
+:root[data-theme="dark"] .tsd-navigation a:hover:not(.current) {
+ background-color: rgba(229, 231, 235, 0.05);
+ color: var(--color-text);
+}
+
+:root[data-theme="dark"] .tsd-navigation a.current {
+ background-color: rgba(229, 231, 235, 0.15);
+ color: var(--color-text);
+ font-weight: 700;
+}
+
+/* ------------------------------------------------------------------ */
+/* Content area */
+/* ------------------------------------------------------------------ */
+
+.tsd-typography {
+ line-height: 1.6;
+}
+
+.tsd-panel.tsd-typography h1 {
+ margin-top: 0;
+ padding-bottom: 0.4em;
+}
+
+.tsd-panel.tsd-typography h2 {
+ margin-top: 2rem;
+ padding-bottom: 0.3em;
+}
+
+.tsd-panel.tsd-typography h3 {
+ margin-top: 1.75rem;
+}
+
+/* ------------------------------------------------------------------ */
+/* Code blocks */
+/* ------------------------------------------------------------------ */
+
+code,
+pre {
+ font-family: var(--font-family-code);
+ font-size: 1em;
+}
+
+.tsd-typography pre {
+ padding: 1rem 1.25rem;
+ border: 1px solid var(--color-accent);
+}
+
+/* Inline code */
+.tsd-typography code:not(pre code) {
+ padding: 0.15em 0.35em;
+ font-size: 1em;
+}
diff --git a/docs/migrate-to-2.md b/docs/migrate-to-2.md
new file mode 100644
index 0000000..f9341d0
--- /dev/null
+++ b/docs/migrate-to-2.md
@@ -0,0 +1,130 @@
+---
+title: Migrate to v2
+group: Getting Started
+description: Upgrade from ext-apps 1.x to 2.x โ new base MCP SDK peer packages, API changes for Views and hosts, and what stays wire-compatible.
+---
+
+# Migrating from ext-apps 1.x to 2.x
+
+ext-apps 2.x is built on the base MCP TypeScript SDK 2.x, which replaced the
+single `@modelcontextprotocol/sdk` package with `@modelcontextprotocol/client`,
+`server`, `core`, `node` and `express`. The MCP Apps wire protocol did not
+change; the breaking changes are in dependencies and in the TypeScript API.
+
+## Host compatibility
+
+The `ui/*` messages exchanged over the iframe channel are byte-identical to
+1.x. A 2.x View runs in a 1.x host and a 2.x host renders 1.x Views. The only
+host-side deltas are in error responses (see below).
+
+## What stays the same
+
+`App` / `AppBridge` constructors, the `on*` setters, `addEventListener`,
+`callServerTool`, `readServerResource`, `registerAppResource`, the React hooks
+and the `_meta.ui.resourceUri` handling are unchanged. Published `.d.ts` files
+now resolve under `moduleResolution: NodeNext` / `Node16` without workarounds
+(#705).
+
+## Peer dependencies by role
+
+| Role | Install |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| View author | `@modelcontextprotocol/ext-apps`, `@modelcontextprotocol/client@^2.0.0`, `zod@^4.2.0` (+ `react`/`react-dom` for `./react`) |
+| Host author | same as View author |
+| MCP server author | View author packages + `@modelcontextprotocol/server@^2.0.0`; for HTTP transports also `@modelcontextprotocol/node@^2.0.0` (`NodeStreamableHTTPServerTransport`) and `@modelcontextprotocol/express@^2.0.0` (`createMcpExpressApp`, which peers on `express`) |
+| CDN / `*-with-deps` | nothing extra: `./app-with-deps` and `./react-with-deps` bundle client, core and zod (about 25% larger than the 1.x bundles) |
+
+`@modelcontextprotocol/client` is a required peer (`App` and `AppBridge` extend
+its `Protocol` class); `@modelcontextprotocol/core` is a required peer that `client` already depends on, so npm installs it without you listing it;
+`@modelcontextprotocol/server` stays optional and is only needed for the
+`./server` helpers. Node.js 20+ is required.
+
+## Breaking changes
+
+- **Peer packages.** `@modelcontextprotocol/sdk@^1` is replaced by the split
+ 2.x packages above, all at `^2.0.0`. Remove the 1.x package from your
+ project: the two SDKs share no classes or types (a 1.x `McpError` or
+ `Client` cannot be passed to 2.x code), even though they speak the same
+ wire protocol.
+- **zod 3 dropped.** The peer range is `zod@^4.2.0`. Tool schemas must
+ implement Standard JSON Schema (`~standard.jsonSchema`): zod 4.2+, ArkType,
+ Valibot. zod 4.0 and 4.1 do not expose `~standard.jsonSchema` and are
+ rejected too. Raw zod shapes (`{ q: z.string() }`) still work with
+ `registerAppTool` but are deprecated; wrap them with `z.object({...})`.
+- **`App` / `AppBridge` extend `Protocol` from `@modelcontextprotocol/client`.**
+ `ProtocolWithEvents` is gone; use the SDK's `Protocol`. The `AppRequest`,
+ `AppNotification` and `AppResult` unions are kept as deprecated type
+ aliases (nothing in 2.x consumes them) and will be removed in 3.0.
+- **Handler context.** Custom request handlers, `registerAppTool` callbacks
+ (server) and `app.registerTool` callbacks (View) receive the SDK 2.x
+ context: `extra.signal` โ `extra.mcpReq.signal`, `extra.requestId` โ
+ `extra.mcpReq.id`; `extra.sessionId` is unchanged and `extra.authInfo`
+ moved to `extra.http?.authInfo`.
+- **`setRequestHandler` / `setNotificationHandler` take method names.**
+ `app.setRequestHandler(SomeRequestSchema, handler)` becomes
+ `app.setRequestHandler("some/method", { params: SomeParamsSchema }, (params, ctx) => โฆ)`
+ for custom methods (the handler receives the parsed params); the two-argument
+ `setRequestHandler("tools/call", handler)` form exists only for spec-defined
+ method names. The 1.x `(Schema, handler)` form still works on `App` and
+ `AppBridge` as a deprecated overload: it logs a one-time warning, hands the
+ handler the whole `{ method, params }` message as before, and gives request
+ handlers a 1.x-shaped `extra` (`signal`, `requestId`, `sessionId`, `_meta`,
+ `sendRequest`, `sendNotification`, `authInfo`; exported as
+ `LegacyRequestHandlerExtra`). It will be removed in 3.0.
+- **Double-registration guard covers the SDK's own handlers.** Registering a
+ handler for `notifications/progress` or `notifications/cancelled` (which
+ the base `Protocol` already owns) now throws `already registered`, as
+ `ping` and the `on*`-owned methods did in 1.x. Use `addEventListener` or
+ the SDK's progress callbacks instead of replacing these.
+- **Errors.** Remote JSON-RPC errors are `ProtocolError` (numeric `code`);
+ local conditions are `SdkError` with a string `code`: request timeout โ
+ `"REQUEST_TIMEOUT"`, connection closed โ `"CONNECTION_CLOSED"`. Cancelling a
+ request with an `AbortSignal` also rejects with `"REQUEST_TIMEOUT"` (the
+ message is the abort reason). Messages no longer carry the `MCP error N:`
+ prefix.
+ A resource-not-found reply that carries `data.uri` arrives as
+ `ResourceNotFoundError` (a `ProtocolError` subclass, `code` `-32602`, with a
+ `.uri` getter).
+
+## Host-side wire deltas
+
+Observed when a 2.x `AppBridge` answers a View; a 1.x View sees these too.
+
+| Situation | 1.x host | 2.x host |
+| --------------------------------------------------------- | ------------------------------ | --------------------------------------------------- |
+| A handler throws `-32002` (resource not found) | `error.code: -32002` | `error.code: -32602` (the SDK never emits `-32002`) |
+| Invalid params on a `ui/*` request | `-32603` with a zod issue dump | `-32602 Invalid params for : โฆ` |
+| Error message text | `MCP error -32602: โฆ` prefix | plain message |
+| `tools/call` to an unknown tool through a 2.x `McpServer` | `result.isError: true` | JSON-RPC error `-32602` (`callServerTool` rejects) |
+
+## `schema.json`
+
+The published `./schema.json` export is regenerated from the 2.x core schemas:
+
+- `McpUiToolResultNotification.params.structuredContent` is any JSON value (was
+ `type: "object"`).
+- `McpUiToolResultNotification.params._meta` documents
+ `io.modelcontextprotocol/serverInfo` and no longer lists `progressToken` /
+ `related-task` (both still pass through).
+- `McpUiHostContext.toolInfo.tool.outputSchema` is a loose object (only
+ `$schema` is documented); `inputSchema.properties` values are now typed as
+ JSON values.
+- A recursive JSON-value definition (`__schema0`) is added under the `$defs` of
+ `McpUiHostContext`, `McpUiHostContextChangedNotification` and
+ `McpUiInitializeResult`.
+
+## Checklist
+
+1. `npm uninstall @modelcontextprotocol/sdk` and install the packages for your
+ role from the table above.
+2. Replace `sdk/...` imports with the split packages (`sdk/server/mcp.js` โ
+ `@modelcontextprotocol/server`, `sdk/server/streamableHttp.js` โ
+ `NodeStreamableHTTPServerTransport` from `@modelcontextprotocol/node`,
+ `sdk/server/stdio.js` โ `@modelcontextprotocol/server/stdio`, hand-written
+ Express routing โ `createMcpExpressApp` from `@modelcontextprotocol/express`,
+ `sdk/types.js` โ `@modelcontextprotocol/client` or `server` for the types,
+ `@modelcontextprotocol/core` for the zod schemas).
+3. Wrap raw zod shapes with `z.object({...})`.
+4. Update custom handlers to the `extra.mcpReq.*` context and method-keyed
+ `setRequestHandler` calls.
+5. Replace `McpError` / numeric-code checks with `ProtocolError` / `SdkError`.
diff --git a/docs/migrate_from_openai_apps.md b/docs/migrate_from_openai_apps.md
index 6f5a1c3..22d5d9f 100644
--- a/docs/migrate_from_openai_apps.md
+++ b/docs/migrate_from_openai_apps.md
@@ -1,5 +1,7 @@
---
title: Migrate OpenAI App
+group: Getting Started
+description: Migrate from the OpenAI Apps SDK to MCP Apps SDK with concept mapping tables, API equivalents, and complete before/after code examples.
---
# Migrating from OpenAI Apps SDK to MCP Apps SDK
@@ -64,7 +66,7 @@ The server-side changes involve updating metadata structure and using helper fun
#### Before (OpenAI)
```typescript
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
import { z } from "zod";
function createServer() {
@@ -76,7 +78,7 @@ function createServer() {
{
title: "Shopping Cart",
description: "Display the user's shopping cart",
- inputSchema: { userId: z.string() },
+ inputSchema: z.object({ userId: z.string() }),
annotations: { readOnlyHint: true },
_meta: {
"openai/outputTemplate": "ui://view/cart.html",
@@ -124,7 +126,7 @@ function createServer() {
#### After (MCP Apps)
```typescript
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
import {
registerAppTool,
registerAppResource,
@@ -142,7 +144,7 @@ function createServer() {
{
title: "Shopping Cart",
description: "Display the user's shopping cart",
- inputSchema: { userId: z.string() },
+ inputSchema: z.object({ userId: z.string() }),
annotations: { readOnlyHint: true },
_meta: { ui: { resourceUri: "ui://view/cart.html" } },
},
diff --git a/docs/overview.md b/docs/overview.md
index b2f5c6a..8eda95d 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -1,5 +1,7 @@
---
title: Overview
+group: Getting Started
+description: MCP Apps extends the Model Context Protocol to let MCP servers deliver interactive UIs โ charts, forms, dashboards โ rendered securely in iframes inside any compliant host.
---
# MCP Apps Overview
@@ -25,7 +27,7 @@ MCP Apps is designed for graceful degradation. Hosts advertise their UI support
This is fundamental: UI is a progressive enhancement, not a requirement. Your server works everywhere; hosts that support UI get a richer experience.
-See the [Client<>Server Capability Negotiation](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#clientserver-capability-negotiation) section of the specification.
+See the [Client<>Server Capability Negotiation](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#clientserver-capability-negotiation) section of the specification.
## Architecture
@@ -54,7 +56,11 @@ flowchart LR
- **Host** โ The chat client (e.g., Claude Desktop) that connects to servers, embeds Views in iframes, and proxies communication between them.
- **View** โ The UI running inside a sandboxed iframe. It receives tool data from the Host and can call server tools or send messages back to the chat.
-The View acts as an MCP client, the Host acts as a proxy, and the Server is a standard MCP server.
+The View's `App` and the Host's `AppBridge` both subclass the `Protocol` class
+exported by `@modelcontextprotocol/client` for the iframe channel. A separate outer `Client` connects
+the Host to the actual MCP Server. Keeping those two connections separate
+preserves the Apps-only iframe handshake and prevents iframe capabilities from
+leaking into the server connection.
## Lifecycle
@@ -91,12 +97,12 @@ sequenceDiagram
```
1. **Discovery** โ The Host learns about tools and their UI resources when connecting to the server.
-2. **Initialization** โ When a UI tool is called, the Host renders the iframe. The View sends `ui/initialize` and receives host context (theme, capabilities, container dimensions). This handshake ensures the View is ready before receiving data.
+2. **Initialization** โ When a UI tool is called, the Host renders the iframe. The View sends `ui/initialize` (the only handshake on the iframe channel) and receives host context (theme, capabilities, container dimensions). `ui/initialize` is authoritative for Apps capabilities and identity, and `ui/notifications/initialized` is the public View-ready signal.
3. **Data delivery** โ The Host sends tool arguments and, once available, tool results to the View. Results include both `content` (text for the model's context) and optionally `structuredContent` (data optimized for UI rendering). This separation lets servers provide rich data to the UI without bloating the model's context.
4. **Interactive phase** โ The user interacts with the View. The View can call tools, send messages, or update context.
5. **Teardown** โ Before unmounting, the Host notifies the View so it can save state or release resources.
-See the [Lifecycle](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#lifecycle) section of the specification for the complete sequence diagrams.
+See the [Lifecycle](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#lifecycle) section of the specification for the complete sequence diagrams.
## UI Resources
@@ -108,7 +114,7 @@ Resources are declared upfront, during tool registration. This design enables:
- **Separation of concerns** โ Templates (presentation) are separate from tool results (data)
- **Review** โ Hosts can inspect UI templates during connection setup
-See the [UI Resource Format](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#ui-resource-format) section of the specification for the full schema.
+See the [UI Resource Format](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#ui-resource-format) section of the specification for the full schema.
## Tool-UI Linkage
@@ -126,7 +132,7 @@ When this tool is called, the Host:
2. Renders it in a sandboxed iframe
3. Passes the tool arguments and results to the View
-See the [Resource Discovery](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#resource-discovery) section of the specification for details.
+See the [Resource Discovery](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#resource-discovery) section of the specification for details.
## Bidirectional Communication
@@ -146,7 +152,7 @@ Views communicate with Hosts using JSON-RPC over [`postMessage`](https://develop
- Open external links (`ui/open-link`)
-See the {@link app!App} class for the View-side API and the [Communication Protocol](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#communication-protocol) section of the specification.
+See the {@link app!App} class for the View-side API and the [Communication Protocol](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#communication-protocol) section of the specification.
## Tool Visibility
@@ -168,7 +174,7 @@ Views use this context to adapt their presentation. For example, a chart might u
The Host notifies Views when context changes (e.g., the user toggles dark mode), allowing dynamic updates without reloading.
-See the [Host Context](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#host-context-in-mcpuiinitializeresult) section of the specification for the full schema.
+See the [Host Context](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#host-context-in-mcpuiinitializeresult) section of the specification for the full schema.
## Theming
@@ -183,7 +189,7 @@ Hosts provide CSS custom properties for colors, typography, and borders. Views u
Theme changes (light/dark toggle) are sent via notifications, allowing Views to update dynamically.
-See the [Theming](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#theming) section of the specification for the full list of CSS variables.
+See the [Theming](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#theming) section of the specification for the full list of CSS variables.
## Display Modes
@@ -195,17 +201,17 @@ Views can be displayed in different modes:
Views declare which modes they support; Hosts declare which they can provide. Views can request mode changes, but the Host decides whether to honor them โ the Host always has final say over its own UI.
-See the [Display Modes](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#display-modes) section of the specification.
+See the [Display Modes](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#display-modes) section of the specification.
## Security
All Views run in sandboxed iframes with no access to the Host's DOM, cookies, or storage. Communication happens only through [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage), making it auditable.
-Servers declare which external domains their UI needs via [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) metadata. Hosts enforce these declarations โ if no domains are declared, no external connections are allowed. This "restrictive by default" approach prevents data exfiltration to undeclared servers.
+Servers declare which network domains their UI needs via [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) metadata. Hosts enforce these declarations โ if no domains are declared, no external connections are allowed. This "restrictive by default" approach prevents data exfiltration to undeclared servers.
-See the [Security Implications](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#security-implications) section of the specification for the threat model and mitigations.
+See the [Security Implications](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#security-implications) section of the specification for the threat model and mitigations.
## Learn More
-- [Specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) โ Full protocol specification
+- [Specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) โ Full protocol specification
- [Quickstart](./quickstart.md) โ Build your first MCP App
diff --git a/docs/patterns.md b/docs/patterns.md
index 43d7519..884de26 100644
--- a/docs/patterns.md
+++ b/docs/patterns.md
@@ -1,5 +1,7 @@
---
title: Patterns
+group: Getting Started
+description: Common patterns and recipes for building MCP Apps โ polling, chunked data, binary resources, theming, fullscreen, model context, state persistence, and more.
---
# MCP Apps Patterns
@@ -8,7 +10,7 @@ This document covers common patterns and recipes for building MCP Apps.
## Tools that are private to Apps
-Set {@link types!McpUiToolMeta.visibility `Tool._meta.ui.visibility`} to `["app"]` to make tools only callable by Apps (hidden from the model). This is useful for UI-driven actions like updating quantities, toggling settings, or other interactions that shouldn't appear in the model's tool list.
+Set {@link types!McpUiToolMeta.visibility `Tool._meta.ui.visibility`} to `["app"]` to make tools only callable by Apps (hidden from the model). This is useful for UI-driven actions like updating server-side state, polling, or other interactions that shouldn't appear in the model's tool list.
```ts source="../src/server/index.examples.ts#registerAppTool_appOnlyVisibility"
@@ -17,7 +19,7 @@ registerAppTool(
"update-quantity",
{
description: "Update item quantity in cart",
- inputSchema: { itemId: z.string(), quantity: z.number() },
+ inputSchema: z.object({ itemId: z.string(), quantity: z.number() }),
_meta: {
ui: {
resourceUri: "ui://shop/cart.html",
@@ -32,7 +34,73 @@ registerAppTool(
);
```
-_See [`examples/system-monitor-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/system-monitor-server) for a full implementation of this pattern._
+> [!NOTE]
+> For full examples that implement this pattern, see: [`examples/system-monitor-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/system-monitor-server) and [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server).
+
+## Polling for live data
+
+For real-time dashboards or monitoring views, use an app-only tool (with `visibility: ["app"]`) that the App polls at regular intervals.
+
+**Vanilla JS:**
+
+
+```ts source="./patterns.tsx#pollingVanillaJs"
+let intervalId: number | null = null;
+
+async function poll() {
+ const result = await app.callServerTool({
+ name: "poll-data",
+ arguments: {},
+ });
+ updateUI(result.structuredContent);
+}
+
+function startPolling() {
+ if (intervalId !== null) return;
+ poll();
+ intervalId = window.setInterval(poll, 2000);
+}
+
+function stopPolling() {
+ if (intervalId === null) return;
+ clearInterval(intervalId);
+ intervalId = null;
+}
+
+// Clean up when host tears down the view
+app.onteardown = async () => {
+ stopPolling();
+ return {};
+};
+```
+
+**React:**
+
+
+```tsx source="./patterns.tsx#pollingReact"
+useEffect(() => {
+ if (!app) return;
+ let cancelled = false;
+
+ async function poll() {
+ const result = await app!.callServerTool({
+ name: "poll-data",
+ arguments: {},
+ });
+ if (!cancelled) setData(result.structuredContent);
+ }
+
+ poll();
+ const id = setInterval(poll, 2000);
+ return () => {
+ cancelled = true;
+ clearInterval(id);
+ };
+}, [app]);
+```
+
+> [!NOTE]
+> For a full example that implements this pattern, see: [`examples/system-monitor-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/system-monitor-server).
## Reading large amounts of data via chunked tool calls
@@ -59,14 +127,14 @@ registerAppTool(
{
title: "Read Data Bytes",
description: "Load binary data in chunks",
- inputSchema: {
+ inputSchema: z.object({
id: z.string().describe("Resource identifier"),
offset: z.number().min(0).default(0).describe("Byte offset"),
byteCount: z
.number()
.default(MAX_CHUNK_BYTES)
.describe("Bytes to read"),
- },
+ }),
outputSchema: DataChunkSchema,
// Hidden from model - only callable by the App
_meta: { ui: { visibility: ["app"] } },
@@ -156,9 +224,10 @@ loadDataInChunks(resourceId, (loaded, total) => {
});
```
-_See [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server) for a full implementation of this pattern._
+> [!NOTE]
+> For a full example that implements this pattern, see: [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server).
-## Giving errors back to model
+## Giving errors back to the model
**Server-side**: Tool handler validates inputs and returns `{ isError: true, content: [...] }`. The model receives this error through the normal tool call response.
@@ -182,18 +251,67 @@ try {
}
```
-## Matching host styling (CSS variables, theme, and fonts)
+## Serving binary blobs via resources
-Use the SDK's style helpers to apply host styling, then reference them in your CSS:
+Binary content (e.g., video) can be served via MCP resources as base64-encoded blobs. The server returns the data in the `blob` field of the resource content, and the App fetches it via `resources/read` for use in the browser.
+
+**Server-side**: Register a resource that returns binary data in the `blob` field:
+
+
+```ts source="./patterns.tsx#binaryBlobResourceServer"
+server.registerResource(
+ "Video",
+ new ResourceTemplate("video://{id}", { list: undefined }),
+ {
+ description: "Video data served as base64 blob",
+ mimeType: "video/mp4",
+ },
+ async (uri, { id }): Promise => {
+ // Fetch or load your binary data
+ const idString = Array.isArray(id) ? id[0] : id;
+ const buffer = await getVideoData(idString);
+ const blob = Buffer.from(buffer).toString("base64");
+
+ return { contents: [{ uri: uri.href, mimeType: "video/mp4", blob }] };
+ },
+);
+```
+
+**Client-side**: Fetch the resource and convert the base64 blob to a data URI:
+
+
+```ts source="./patterns.tsx#binaryBlobResourceClient"
+const result = await app.readServerResource({ uri: `video://${videoId}` });
+
+const content = result.contents[0];
+if (!content || !("blob" in content)) {
+ throw new Error("Resource did not contain blob data");
+}
+
+const videoEl = document.querySelector("video")!;
+videoEl.src = `data:${content.mimeType!};base64,${content.blob}`;
+```
+
+> [!NOTE]
+> For a full example that implements this pattern, see: [`examples/video-resource-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/video-resource-server).
+
+## Configuring CSP and CORS
+
+See the dedicated [CSP & CORS](./csp-cors.md) guide in the Security section.
+
+## Adapting to host context (theme, styling, fonts, and safe areas)
+
+The host provides context about its environment via {@link types!McpUiHostContext `McpUiHostContext`}. Use this to adapt your app's appearance and layout:
-- **CSS variables** โ Use `var(--color-background-primary)`, etc. in your CSS
- **Theme** โ Use `[data-theme="dark"]` selectors or `light-dark()` function for theme-aware styles
+- **CSS variables** โ Use `var(--color-background-primary)`, etc. in your CSS (see {@link types!McpUiStyleVariableKey `McpUiStyleVariableKey`} for a full list)
- **Fonts** โ Use `var(--font-sans)` or `var(--font-mono)` with fallbacks (e.g., `font-family: var(--font-sans, system-ui, sans-serif)`)
+- **Safe area insets** โ Apply padding to avoid device notches, rounded corners, or system UI overlays
**Vanilla JS:**
-```tsx source="./patterns.tsx#hostStylingVanillaJs"
+```tsx source="./patterns.tsx#hostContextVanillaJs"
function applyHostContext(ctx: McpUiHostContext) {
if (ctx.theme) {
applyDocumentTheme(ctx.theme);
@@ -204,12 +322,18 @@ function applyHostContext(ctx: McpUiHostContext) {
if (ctx.styles?.css?.fonts) {
applyHostFonts(ctx.styles.css.fonts);
}
+ if (ctx.safeAreaInsets) {
+ mainEl.style.paddingTop = `${ctx.safeAreaInsets.top}px`;
+ mainEl.style.paddingRight = `${ctx.safeAreaInsets.right}px`;
+ mainEl.style.paddingBottom = `${ctx.safeAreaInsets.bottom}px`;
+ mainEl.style.paddingLeft = `${ctx.safeAreaInsets.left}px`;
+ }
}
// Apply when host context changes
app.onhostcontextchanged = applyHostContext;
-// Apply initial styles after connecting
+// Apply initial context after connecting
app.connect().then(() => {
const ctx = app.getHostContext();
if (ctx) {
@@ -221,43 +345,72 @@ app.connect().then(() => {
**React:**
-```tsx source="./patterns.tsx#hostStylingReact"
+```tsx source="./patterns.tsx#hostContextReact"
function MyApp() {
+ const [hostContext, setHostContext] = useState();
+
const { app } = useApp({
appInfo: { name: "MyApp", version: "1.0.0" },
capabilities: {},
+ onAppCreated: (app) => {
+ app.onhostcontextchanged = (ctx) => {
+ setHostContext((prev) => ({ ...prev, ...ctx }));
+ };
+ },
});
- // Apply all host styles (variables, theme, fonts)
- useHostStyles(app, app?.getHostContext());
+ // Set initial host context after connection
+ useEffect(() => {
+ if (app) {
+ setHostContext(app.getHostContext());
+ }
+ }, [app]);
+
+ // Apply styles when host context changes
+ useEffect(() => {
+ if (hostContext?.theme) {
+ applyDocumentTheme(hostContext.theme);
+ }
+ if (hostContext?.styles?.variables) {
+ applyHostStyleVariables(hostContext.styles.variables);
+ }
+ if (hostContext?.styles?.css?.fonts) {
+ applyHostFonts(hostContext.styles.css.fonts);
+ }
+ }, [hostContext]);
return (
-
Styled with host CSS variables and fonts
-
Uses [data-theme] selectors
+ Styled with host CSS variables, fonts, and safe area insets
);
}
```
-_See [`examples/basic-server-vanillajs/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) and [`examples/basic-server-react/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) for full implementations of this pattern._
+> [!NOTE]
+> For full examples that implement this pattern, see: [`examples/basic-server-vanillajs/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) and [`examples/basic-server-react/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react).
-## Entering / Exiting fullscreen
+## Entering / exiting fullscreen
Toggle fullscreen mode by calling {@link app!App.requestDisplayMode `requestDisplayMode`}:
```ts source="../src/app.examples.ts#App_requestDisplayMode_toggle"
+const container = document.getElementById("main")!;
const ctx = app.getHostContext();
-if (ctx?.availableDisplayModes?.includes("fullscreen")) {
- const target = ctx.displayMode === "fullscreen" ? "inline" : "fullscreen";
- const result = await app.requestDisplayMode({ mode: target });
- console.log("Now in:", result.mode);
+const newMode = ctx?.displayMode === "inline" ? "fullscreen" : "inline";
+if (ctx?.availableDisplayModes?.includes(newMode)) {
+ const result = await app.requestDisplayMode({ mode: newMode });
+ container.classList.toggle("fullscreen", result.mode === "fullscreen");
}
```
@@ -265,17 +418,39 @@ Listen for display mode changes via {@link app!App.onhostcontextchanged `onhostc
```ts source="../src/app.examples.ts#App_onhostcontextchanged_respondToDisplayMode"
-app.onhostcontextchanged = (params) => {
- if (params.displayMode) {
- const isFullscreen = params.displayMode === "fullscreen";
- document.body.classList.toggle("fullscreen", isFullscreen);
+app.onhostcontextchanged = (ctx) => {
+ // Adjust to current display mode
+ if (ctx.displayMode) {
+ const container = document.getElementById("main")!;
+ const isFullscreen = ctx.displayMode === "fullscreen";
+ container.classList.toggle("fullscreen", isFullscreen);
+ }
+
+ // Adjust display mode controls
+ if (ctx.availableDisplayModes) {
+ const fullscreenBtn = document.getElementById("fullscreen-btn")!;
+ const canFullscreen = ctx.availableDisplayModes.includes("fullscreen");
+ fullscreenBtn.style.display = canFullscreen ? "block" : "none";
}
};
```
-_See [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server) for a full implementation of this pattern._
+In fullscreen mode, remove the container's border radius so content extends to the viewport edges:
-## Passing contextual information from the App to the Model
+```css
+#main {
+ border-radius: var(--border-radius-lg);
+
+ &.fullscreen {
+ border-radius: 0;
+ }
+}
+```
+
+> [!NOTE]
+> For full examples that implement this pattern, see: [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server), [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server), and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server).
+
+## Passing contextual information from the App to the model
Use {@link app!App.updateModelContext `updateModelContext`} to keep the model informed about what the user is viewing or interacting with. Structure the content with YAML frontmatter for easy parsing:
@@ -296,7 +471,8 @@ await app.updateModelContext({
});
```
-_See [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) for a full implementation of this pattern._
+> [!NOTE]
+> For full examples that implement this pattern, see: [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) and [`examples/transcript-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/transcript-server).
## Sending large follow-up messages
@@ -321,11 +497,12 @@ await app.sendMessage({
});
```
-_See [`examples/transcript-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/transcript-server) for a full implementation of this pattern._
+> [!NOTE]
+> For a full example that implements this pattern, see: [`examples/transcript-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/transcript-server).
## Persisting view state
-To persist view state across conversation reloads (e.g., current page in a PDF viewer, camera position in a map), use [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) with a stable identifier provided by the server.
+For recoverable view state (e.g., current page in a PDF viewer, camera position in a map), use [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) with a stable identifier provided by the server.
**Server-side**: Tool handler generates a unique `viewUUID` and returns it in `CallToolResult._meta.viewUUID`:
@@ -345,21 +522,56 @@ return {
```tsx source="./patterns.tsx#persistData"
-// In your tool callback, include viewUUID in the result metadata.
-return {
- content: [{ type: "text", text: `Displaying PDF viewer for "${title}"` }],
- structuredContent: { url, title, pageCount, initialPage: 1 },
- _meta: {
- viewUUID: randomUUID(),
- },
+// Store the viewUUID received from the server
+let viewUUID: string | undefined;
+
+// Helper to save state to localStorage
+function saveState(state: T): void {
+ if (!viewUUID) return;
+ try {
+ localStorage.setItem(viewUUID, JSON.stringify(state));
+ } catch (err) {
+ console.error("Failed to save view state:", err);
+ }
+}
+
+// Helper to load state from localStorage
+function loadState(): T | null {
+ if (!viewUUID) return null;
+ try {
+ const saved = localStorage.getItem(viewUUID);
+ return saved ? (JSON.parse(saved) as T) : null;
+ } catch (err) {
+ console.error("Failed to load view state:", err);
+ return null;
+ }
+}
+
+// Receive viewUUID from the tool result
+app.ontoolresult = (result) => {
+ viewUUID = result._meta?.viewUUID
+ ? String(result._meta.viewUUID)
+ : undefined;
+
+ // Restore any previously saved state
+ const savedState = loadState<{ currentPage: number }>();
+ if (savedState) {
+ // Apply restored state to your UI...
+ }
};
+
+// Call saveState() whenever your view state changes
+// e.g., saveState({ currentPage: 5 });
```
-_See [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) for a full implementation of this pattern._
+For state that represents user effort (e.g., saved bookmarks, annotations, custom configurations), consider persisting it server-side using [app-only tools](#tools-that-are-private-to-apps) instead. Pass the `viewUUID` to the app-only tool to scope the saved data to that view instance.
-## Pausing computation-heavy views when out of view
+> [!NOTE]
+> For full examples using `localStorage`, see: [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server) (persists current page) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (persists camera position).
-Views with animations, WebGL rendering, or polling can consume significant CPU/GPU even when scrolled out of view. Use [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to pause expensive operations when the view isn't visible:
+## Pausing computation-heavy views when offscreen
+
+Views with animations, WebGL rendering, or polling can consume significant CPU/GPU even when scrolled offscreen. Use [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to pause expensive operations when the view isn't visible:
```tsx source="./patterns.tsx#visibilityBasedPause"
@@ -367,9 +579,9 @@ Views with animations, WebGL rendering, or polling can consume significant CPU/G
const observer = new IntersectionObserver((entries) => {
entries.forEach((entry) => {
if (entry.isIntersecting) {
- animation.play();
+ animation.play(); // or startPolling(), etc
} else {
- animation.pause();
+ animation.pause(); // or stopPolling(), etc
}
});
});
@@ -383,38 +595,33 @@ app.onteardown = async () => {
};
```
-_See [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server) for a full implementation of this pattern._
+> [!NOTE]
+> For full examples that implement this pattern, see: [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server) and [`examples/threejs-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/threejs-server).
## Lowering perceived latency
-Use {@link app!App.ontoolinputpartial `ontoolinputpartial`} to receive streaming tool arguments as they arrive, allowing you to show a loading preview before the complete input is available.
+Use {@link app!App.ontoolinputpartial `ontoolinputpartial`} to receive streaming tool arguments as they arrive. This lets you show a loading preview before the complete input is available, such as streaming code into a `
` tag before executing it, partially rendering a table as data arrives, or incrementally populating a chart.
```ts source="../src/app.examples.ts#App_ontoolinputpartial_progressiveRendering"
-let toolInputs: Record | null = null;
-let toolInputsPartial: Record | null = null;
+const codePreview = document.querySelector("#code-preview")!;
+const canvas = document.querySelector("#canvas")!;
app.ontoolinputpartial = (params) => {
- toolInputsPartial = params.arguments as Record;
- render();
+ codePreview.textContent = (params.arguments?.code as string) ?? "";
+ codePreview.style.display = "block";
+ canvas.style.display = "none";
};
app.ontoolinput = (params) => {
- toolInputs = params.arguments as Record;
- toolInputsPartial = null;
- render();
+ codePreview.style.display = "none";
+ canvas.style.display = "block";
+ render(params.arguments?.code as string);
};
-
-function render() {
- if (toolInputs) {
- renderFinalUI(toolInputs);
- } else {
- renderLoadingUI(toolInputsPartial); // e.g., shimmer with partial preview
- }
-}
```
> [!IMPORTANT]
> Partial arguments are "healed" JSON โ the host closes unclosed brackets/braces to produce valid JSON. This means objects may be incomplete (e.g., the last item in an array may be truncated). Don't rely on partial data for critical operations; use it only for preview UI.
-_See [`examples/threejs-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/threejs-server) for a full implementation of this pattern._
+> [!NOTE]
+> For full examples that implement this pattern, see: [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server) and [`examples/threejs-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/threejs-server).
diff --git a/docs/patterns.tsx b/docs/patterns.tsx
index f13268f..bb9eaa4 100644
--- a/docs/patterns.tsx
+++ b/docs/patterns.tsx
@@ -14,13 +14,83 @@ import {
applyHostStyleVariables,
} from "../src/styles.js";
import { randomUUID } from "node:crypto";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type {
+ CallToolResult,
+ ReadResourceResult,
+} from "@modelcontextprotocol/server";
import type { McpUiHostContext } from "../src/types.js";
-import { useApp, useHostStyles } from "../src/react/index.js";
+import { useEffect, useState } from "react";
+import { useApp } from "../src/react/index.js";
import { registerAppTool } from "../src/server/index.js";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/server";
import { z } from "zod";
+/**
+ * Example: Polling for live data (Vanilla JS)
+ */
+function pollingVanillaJs(app: App, updateUI: (data: unknown) => void) {
+ //#region pollingVanillaJs
+ let intervalId: number | null = null;
+
+ async function poll() {
+ const result = await app.callServerTool({
+ name: "poll-data",
+ arguments: {},
+ });
+ updateUI(result.structuredContent);
+ }
+
+ function startPolling() {
+ if (intervalId !== null) return;
+ poll();
+ intervalId = window.setInterval(poll, 2000);
+ }
+
+ function stopPolling() {
+ if (intervalId === null) return;
+ clearInterval(intervalId);
+ intervalId = null;
+ }
+
+ // Clean up when host tears down the view
+ app.onteardown = async () => {
+ stopPolling();
+ return {};
+ };
+ //#endregion pollingVanillaJs
+}
+
+/**
+ * Example: Polling for live data (React)
+ */
+function pollingReact(
+ app: App | null, // via useApp()
+) {
+ const [data, setData] = useState();
+
+ //#region pollingReact
+ useEffect(() => {
+ if (!app) return;
+ let cancelled = false;
+
+ async function poll() {
+ const result = await app!.callServerTool({
+ name: "poll-data",
+ arguments: {},
+ });
+ if (!cancelled) setData(result.structuredContent);
+ }
+
+ poll();
+ const id = setInterval(poll, 2000);
+ return () => {
+ cancelled = true;
+ clearInterval(id);
+ };
+ }, [app]);
+ //#endregion pollingReact
+}
+
/**
* Example: Server-side chunked data tool (app-only)
*/
@@ -43,14 +113,14 @@ function chunkedDataServer(server: McpServer) {
{
title: "Read Data Bytes",
description: "Load binary data in chunks",
- inputSchema: {
+ inputSchema: z.object({
id: z.string().describe("Resource identifier"),
offset: z.number().min(0).default(0).describe("Byte offset"),
byteCount: z
.number()
.default(MAX_CHUNK_BYTES)
.describe("Bytes to read"),
- },
+ }),
outputSchema: DataChunkSchema,
// Hidden from model - only callable by the App
_meta: { ui: { visibility: ["app"] } },
@@ -147,10 +217,54 @@ function chunkedDataClient(app: App, resourceId: string) {
}
/**
- * Example: Unified host styling (theme, CSS variables, fonts)
+ * Example: Serving binary blobs via resources (server-side)
*/
-function hostStylingVanillaJs(app: App) {
- //#region hostStylingVanillaJs
+function binaryBlobResourceServer(
+ server: McpServer,
+ getVideoData: (id: string) => Promise,
+) {
+ //#region binaryBlobResourceServer
+ server.registerResource(
+ "Video",
+ new ResourceTemplate("video://{id}", { list: undefined }),
+ {
+ description: "Video data served as base64 blob",
+ mimeType: "video/mp4",
+ },
+ async (uri, { id }): Promise => {
+ // Fetch or load your binary data
+ const idString = Array.isArray(id) ? id[0] : id;
+ const buffer = await getVideoData(idString);
+ const blob = Buffer.from(buffer).toString("base64");
+
+ return { contents: [{ uri: uri.href, mimeType: "video/mp4", blob }] };
+ },
+ );
+ //#endregion binaryBlobResourceServer
+}
+
+/**
+ * Example: Serving binary blobs via resources (client-side)
+ */
+async function binaryBlobResourceClient(app: App, videoId: string) {
+ //#region binaryBlobResourceClient
+ const result = await app.readServerResource({ uri: `video://${videoId}` });
+
+ const content = result.contents[0];
+ if (!content || !("blob" in content)) {
+ throw new Error("Resource did not contain blob data");
+ }
+
+ const videoEl = document.querySelector("video")!;
+ videoEl.src = `data:${content.mimeType!};base64,${content.blob}`;
+ //#endregion binaryBlobResourceClient
+}
+
+/**
+ * Example: Adapting to host context (theme, CSS variables, fonts, safe areas)
+ */
+function hostContextVanillaJs(app: App, mainEl: HTMLElement) {
+ //#region hostContextVanillaJs
function applyHostContext(ctx: McpUiHostContext) {
if (ctx.theme) {
applyDocumentTheme(ctx.theme);
@@ -161,48 +275,81 @@ function hostStylingVanillaJs(app: App) {
if (ctx.styles?.css?.fonts) {
applyHostFonts(ctx.styles.css.fonts);
}
+ if (ctx.safeAreaInsets) {
+ mainEl.style.paddingTop = `${ctx.safeAreaInsets.top}px`;
+ mainEl.style.paddingRight = `${ctx.safeAreaInsets.right}px`;
+ mainEl.style.paddingBottom = `${ctx.safeAreaInsets.bottom}px`;
+ mainEl.style.paddingLeft = `${ctx.safeAreaInsets.left}px`;
+ }
}
// Apply when host context changes
app.onhostcontextchanged = applyHostContext;
- // Apply initial styles after connecting
+ // Apply initial context after connecting
app.connect().then(() => {
const ctx = app.getHostContext();
if (ctx) {
applyHostContext(ctx);
}
});
- //#endregion hostStylingVanillaJs
+ //#endregion hostContextVanillaJs
}
/**
- * Example: Host styling with React (CSS variables, theme, fonts)
+ * Example: Adapting to host context with React (CSS variables, theme, fonts, safe areas)
*/
-function hostStylingReact() {
- //#region hostStylingReact
+function hostContextReact() {
+ //#region hostContextReact
function MyApp() {
+ const [hostContext, setHostContext] = useState();
+
const { app } = useApp({
appInfo: { name: "MyApp", version: "1.0.0" },
capabilities: {},
+ onAppCreated: (app) => {
+ app.onhostcontextchanged = (ctx) => {
+ setHostContext((prev) => ({ ...prev, ...ctx }));
+ };
+ },
});
- // Apply all host styles (variables, theme, fonts)
- useHostStyles(app, app?.getHostContext());
+ // Set initial host context after connection
+ useEffect(() => {
+ if (app) {
+ setHostContext(app.getHostContext());
+ }
+ }, [app]);
+
+ // Apply styles when host context changes
+ useEffect(() => {
+ if (hostContext?.theme) {
+ applyDocumentTheme(hostContext.theme);
+ }
+ if (hostContext?.styles?.variables) {
+ applyHostStyleVariables(hostContext.styles.variables);
+ }
+ if (hostContext?.styles?.css?.fonts) {
+ applyHostFonts(hostContext.styles.css.fonts);
+ }
+ }, [hostContext]);
return (
-
Styled with host CSS variables and fonts
-
Uses [data-theme] selectors
+ Styled with host CSS variables, fonts, and safe area insets
);
}
- //#endregion hostStylingReact
+ //#endregion hostContextReact
}
/**
@@ -284,9 +431,9 @@ function visibilityBasedPause(
const observer = new IntersectionObserver((entries) => {
entries.forEach((entry) => {
if (entry.isIntersecting) {
- animation.play();
+ animation.play(); // or startPolling(), etc
} else {
- animation.pause();
+ animation.pause(); // or stopPolling(), etc
}
});
});
@@ -302,10 +449,14 @@ function visibilityBasedPause(
}
// Suppress unused variable warnings
+void pollingVanillaJs;
+void pollingReact;
void chunkedDataServer;
void chunkedDataClient;
-void hostStylingVanillaJs;
-void hostStylingReact;
+void binaryBlobResourceServer;
+void binaryBlobResourceClient;
+void hostContextVanillaJs;
+void hostContextReact;
void persistViewStateServer;
void persistViewState;
void visibilityBasedPause;
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 8146824..a021912 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,5 +1,7 @@
---
title: Quickstart
+group: Getting Started
+description: Build your first MCP App step by step โ create an MCP server with an interactive View that renders inside Claude Desktop and other MCP hosts.
---
# Build Your First MCP App
@@ -19,7 +21,7 @@ This tutorial assumes you've built an MCP server before and are comfortable with
We'll use the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) to build the server.
-You'll also need Node.js 18+.
+You'll also need Node.js 20+.
## 1. Set up the project
@@ -35,7 +37,7 @@ Install the dependencies you'll need:
```bash
npm init -y
-npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk express cors
+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 express cors
npm install -D typescript vite vite-plugin-singlefile @types/express @types/cors @types/node tsx concurrently cross-env
```
@@ -44,9 +46,12 @@ Configure your [`package.json`](https://github.com/modelcontextprotocol/ext-apps
```bash
npm pkg set type=module
npm pkg set scripts.build="tsc --noEmit && tsc -p tsconfig.server.json && cross-env INPUT=mcp-app.html vite build"
-npm pkg set scripts.start="concurrently 'cross-env NODE_ENV=development INPUT=mcp-app.html vite build --watch' 'tsx watch main.ts'"
+npm pkg set scripts.start='concurrently --raw "cross-env NODE_ENV=development INPUT=mcp-app.html vite build --watch" "tsx watch main.ts"'
```
+> [!NOTE]
+> Windows `cmd.exe` users will need to convert quotes in the above command: `npm pkg set scripts.start="concurrently --raw ""cross-env NODE_ENV=development INPUT=mcp-app.html vite build --watch"" ""tsx watch main.ts"""`.
+
Create tsconfig.json:
@@ -54,6 +59,7 @@ npm pkg set scripts.start="concurrently 'cross-env NODE_ENV=development INPUT=mc
```json source="../examples/quickstart/tsconfig.json"
{
"compilerOptions": {
+ "types": ["node", "vite/client"],
"target": "ESNext",
"lib": ["ESNext", "DOM", "DOM.Iterable"],
"module": "ESNext",
@@ -82,6 +88,7 @@ npm pkg set scripts.start="concurrently 'cross-env NODE_ENV=development INPUT=mc
```json source="../examples/quickstart/tsconfig.server.json"
{
"compilerOptions": {
+ "types": ["node"],
"target": "ES2022",
"lib": ["ES2022"],
"module": "NodeNext",
@@ -108,7 +115,7 @@ npm pkg set scripts.start="concurrently 'cross-env NODE_ENV=development INPUT=mc
```ts source="../examples/quickstart/vite.config.ts"
-import { defineConfig } from "vite";
+import { createLogger, defineConfig } from "vite";
import { viteSingleFile } from "vite-plugin-singlefile";
const INPUT = process.env.INPUT;
@@ -118,7 +125,14 @@ if (!INPUT) {
const isDevelopment = process.env.NODE_ENV === "development";
+const prefixedLogger = createLogger();
+for (const level of ["info", "warn", "error"] as const) {
+ const fn = prefixedLogger[level];
+ prefixedLogger[level] = (msg, opts) => fn(msg.replace(/^/mg, "[vite] "), opts);
+}
+
export default defineConfig({
+ customLogger: prefixedLogger,
plugins: [viteSingleFile()],
build: {
sourcemap: isDevelopment ? "inline" : undefined,
@@ -166,9 +180,10 @@ import {
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
import fs from "node:fs/promises";
import path from "node:path";
+import { z } from "zod";
const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -193,7 +208,7 @@ export function createServer(): McpServer {
{
title: "Get Time",
description: "Returns the current server time.",
- inputSchema: {},
+ inputSchema: z.object({}),
_meta: { ui: { resourceUri } }, // Links this tool to its UI resource
},
async () => {
@@ -228,10 +243,10 @@ export function createServer(): McpServer {
```ts source="../examples/quickstart/main.ts"
-import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/express";
+import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
+import type { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import cors from "cors";
import type { Request, Response } from "express";
import { createServer } from "./server.js";
@@ -251,7 +266,7 @@ export async function startStreamableHTTPServer(
app.all("/mcp", async (req: Request, res: Response) => {
const server = createServer();
- const transport = new StreamableHTTPServerTransport({
+ const transport = new NodeStreamableHTTPServerTransport({
sessionIdGenerator: undefined,
});
@@ -447,8 +462,9 @@ MCP server listening on http://localhost:3001/mcp
```bash
git clone https://github.com/modelcontextprotocol/ext-apps.git
-cd ext-apps/examples/basic-host
+cd ext-apps
npm install
+cd examples/basic-host
npm start
```
@@ -468,4 +484,4 @@ You've built your first MCP App!
- **Continue learning**: The [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) example builds on this quickstart with host communication, theming, and lifecycle handlers
- **React version**: Compare with [`basic-server-react`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) for a React-based UI
- **Other frameworks**: See also [Vue](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vue), [Svelte](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-svelte), [Preact](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-preact), and [Solid](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-solid) examples
-- **API reference**: See the full [API documentation](https://modelcontextprotocol.github.io/ext-apps/api/)
+- **API reference**: See the full [API documentation](https://apps.extensions.modelcontextprotocol.io/api/)
diff --git a/docs/testing-mcp-apps.md b/docs/testing-mcp-apps.md
index 06873da..a8eb333 100644
--- a/docs/testing-mcp-apps.md
+++ b/docs/testing-mcp-apps.md
@@ -1,5 +1,7 @@
---
title: Testing MCP Apps
+group: Getting Started
+description: Test MCP Apps locally with the basic-host reference implementation or in production hosts like Claude.ai and VS Code.
---
# Test Your MCP App
@@ -21,10 +23,15 @@ The [`basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/ex
```bash
git clone https://github.com/modelcontextprotocol/ext-apps.git
- cd ext-apps/examples/basic-host
+ cd ext-apps
npm install
+ cd examples/basic-host
```
+ The root install runs the package build, including type-checking the
+ documentation snippets against the pinned base MCP SDK 2.x packages. Do
+ not bypass a failed build before testing the host.
+
2. Start basic-host, pointing it to your MCP server:
```bash
@@ -59,8 +66,8 @@ For additional observability, open your browser's developer console. Basic-host
To test your App in a real conversational environment, install your MCP server in a host that supports MCP Apps:
- Claude\.ai
- - [Remote MCP servers (over HTTP)](https://claude.ai/docs/connectors/custom/remote-mcp)
- - [Local MCP servers (over stdio)](https://claude.ai/docs/connectors/custom/desktop-extensions)
+ - [Remote MCP servers (over HTTP)](https://claude.com/docs/connectors/custom/remote-mcp)
+ - [Local MCP servers (over stdio)](https://claude.com/docs/connectors/custom/desktop-extensions)
- [VS Code (Insiders)](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
- [Goose](https://block.github.io/goose/docs/getting-started/using-extensions/)
diff --git a/examples/basic-host/package.json b/examples/basic-host/package.json
index d3ce4f9..cefe9d5 100644
--- a/examples/basic-host/package.json
+++ b/examples/basic-host/package.json
@@ -1,7 +1,7 @@
{
"homepage": "https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host",
"name": "@modelcontextprotocol/ext-apps-basic-host",
- "version": "0.4.2",
+ "version": "2.0.0",
"type": "module",
"scripts": {
"build": "tsc --noEmit && concurrently \"cross-env INPUT=index.html vite build\" \"cross-env INPUT=sandbox.html vite build\"",
@@ -11,11 +11,11 @@
"dev": "cross-env NODE_ENV=development concurrently \"npm run watch\" \"npm run serve\""
},
"dependencies": {
- "@modelcontextprotocol/ext-apps": "../..",
- "@modelcontextprotocol/sdk": "^1.24.0",
+ "@modelcontextprotocol/client": "2.0.0",
+ "@modelcontextprotocol/ext-apps": "^2.0.0",
"react": "^19.2.0",
"react-dom": "^19.2.0",
- "zod": "^4.1.13"
+ "zod": "^4.2.0"
},
"devDependencies": {
"@types/express": "^5.0.0",
@@ -29,7 +29,6 @@
"prettier": "^3.6.2",
"typescript": "^5.9.3",
"vite": "^6.0.0",
- "vite-plugin-singlefile": "^2.3.0",
- "vitest": "^3.2.4"
+ "vite-plugin-singlefile": "^2.3.0"
}
}
diff --git a/examples/basic-host/serve.ts b/examples/basic-host/serve.ts
index 03c3a0b..bc3fbff 100644
--- a/examples/basic-host/serve.ts
+++ b/examples/basic-host/serve.ts
@@ -82,6 +82,8 @@ function buildCspHeader(csp?: McpUiResourceCsp): string {
`img-src 'self' data: blob: ${resourceDomains}`.trim(),
// Fonts: same-origin + data/blob URIs + specified domains
`font-src 'self' data: blob: ${resourceDomains}`.trim(),
+ // Media (audio/video): same-origin + data/blob URIs + specified domains
+ `media-src 'self' data: blob: ${resourceDomains}`.trim(),
// Network requests: same-origin + specified API/tile domains
`connect-src 'self' ${connectDomains}`.trim(),
// Workers: same-origin + blob (dynamic workers) + specified domains
diff --git a/examples/basic-host/src/implementation.ts b/examples/basic-host/src/implementation.ts
index 434169a..5f680ff 100644
--- a/examples/basic-host/src/implementation.ts
+++ b/examples/basic-host/src/implementation.ts
@@ -1,8 +1,12 @@
import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, buildAllowAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+ Client,
+ SSEClientTransport,
+ StreamableHTTPClientTransport,
+ type CallToolResult,
+ type Resource,
+ type Tool,
+} from "@modelcontextprotocol/client";
import { getTheme, onThemeChange } from "./theme";
import { HOST_STYLE_VARIABLES } from "./host-styles";
@@ -22,6 +26,7 @@ export interface ServerInfo {
name: string;
client: Client;
tools: Map;
+ resources: Map;
appHtmlCache: Map;
}
@@ -36,7 +41,12 @@ export async function connectToServer(serverUrl: URL): Promise {
const tools = new Map(toolsList.tools.map((tool) => [tool.name, tool]));
log.info("Server tools:", Array.from(tools.keys()));
- return { name, client, tools, appHtmlCache: new Map() };
+ // Fetch resources for listing-level _meta.ui (fallback for content-level)
+ const resourcesList = await client.listResources();
+ const resources = new Map(resourcesList.resources.map((r) => [r.uri, r]));
+ log.info("Server resources:", Array.from(resources.keys()));
+
+ return { name, client, tools, resources, appHtmlCache: new Map() };
}
async function connectWithFallback(serverUrl: URL): Promise {
@@ -128,14 +138,23 @@ async function getUiResource(serverInfo: ServerInfo, uri: string): Promise {
+ const width = Math.round(entry.contentRect.width);
+ if (width > 0) {
+ appBridge.sendHostContextChange({
+ containerDimensions: { width, maxHeight: 6000 },
+ });
+ }
+ });
+ iframeResizeObserver.observe(iframe);
+ // AppBridge inherits Protocol's onclose hook โ chain disposal there.
+ const prevOnclose = appBridge.onclose;
+ appBridge.onclose = () => {
+ iframeResizeObserver.disconnect();
+ prevOnclose?.();
+ };
+
// Register all handlers before calling connect(). The view can start
// sending requests immediately after the initialization handshake, so any
// handlers registered after connect() might miss early requests.
diff --git a/examples/basic-host/src/index.module.css b/examples/basic-host/src/index.module.css
index ec18e2b..0bd09dd 100644
--- a/examples/basic-host/src/index.module.css
+++ b/examples/basic-host/src/index.module.css
@@ -1,7 +1,7 @@
/* Theme toggle button */
.themeToggle {
position: fixed;
- top: 1rem;
+ bottom: 1rem;
right: 1rem;
width: 2.5rem;
height: 2.5rem;
@@ -165,7 +165,7 @@
margin: 0;
padding: 1rem;
max-width: none;
- background: white;
+ background: var(--color-bg);
border: none;
border-radius: 0;
display: flex;
@@ -201,29 +201,30 @@
width: 32px;
height: 32px;
padding: 0;
- border: 1px solid #ccc;
+ border: 1px solid var(--color-border);
border-radius: 4px;
- background: #f5f5f5;
+ background: var(--color-bg-secondary);
+ color: var(--color-text);
font-size: 1.25rem;
cursor: pointer;
&:hover {
- background: #e0e0e0;
+ background: var(--color-bg);
}
}
.collapsiblePanel {
margin: 0.5rem 0;
padding: 0.5rem 0.75rem;
- border: 1px solid #e0e0e0;
+ border: 1px solid var(--color-border);
border-radius: 4px;
- background-color: #fafafa;
+ background-color: var(--color-bg-secondary);
font-size: 0.875rem;
cursor: pointer;
transition: background-color 0.15s;
&:hover {
- background-color: #f0f0f0;
+ background-color: var(--color-bg);
}
}
@@ -235,23 +236,23 @@
.collapsibleLabel {
font-weight: 600;
- color: #555;
+ color: var(--color-text);
}
.collapsibleSize {
- color: #888;
+ color: var(--color-text-secondary);
font-size: 0.75rem;
}
.collapsibleToggle {
margin-left: auto;
- color: #888;
+ color: var(--color-text-secondary);
font-size: 0.75rem;
}
.collapsiblePreview {
margin-top: 0.25rem;
- color: #666;
+ color: var(--color-text-secondary);
font-family: monospace;
font-size: 0.8rem;
white-space: nowrap;
@@ -263,7 +264,8 @@
margin: 0.5rem 0 0;
padding: 0.5rem;
border-radius: 4px;
- background-color: #f5f5f5;
+ background-color: var(--color-bg);
+ color: var(--color-text);
font-family: monospace;
font-size: 0.8rem;
white-space: pre-wrap;
diff --git a/examples/basic-host/src/index.tsx b/examples/basic-host/src/index.tsx
index 3d488a7..00c0d52 100644
--- a/examples/basic-host/src/index.tsx
+++ b/examples/basic-host/src/index.tsx
@@ -1,5 +1,5 @@
import { getToolUiResourceUri, McpUiToolMetaSchema } from "@modelcontextprotocol/ext-apps/app-bridge";
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Tool } from "@modelcontextprotocol/client";
import { Component, type ErrorInfo, type ReactNode, StrictMode, Suspense, use, useEffect, useMemo, useRef, useState } from "react";
import { createRoot } from "react-dom/client";
import { callTool, connectToServer, hasAppHtml, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo, type ModelContext, type AppMessage } from "./implementation";
diff --git a/examples/basic-host/src/sandbox.ts b/examples/basic-host/src/sandbox.ts
index 1caf1c5..6f1dd93 100644
--- a/examples/basic-host/src/sandbox.ts
+++ b/examples/basic-host/src/sandbox.ts
@@ -1,5 +1,5 @@
-import type { McpUiSandboxProxyReadyNotification, McpUiSandboxResourceReadyNotification } from "../../../dist/src/types";
-import { buildAllowAttribute } from "../../../dist/src/app-bridge";
+import type { McpUiSandboxProxyReadyNotification, McpUiSandboxResourceReadyNotification } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { buildAllowAttribute } from "@modelcontextprotocol/ext-apps/app-bridge";
const ALLOWED_REFERRER_PATTERN = /^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/;
diff --git a/examples/basic-host/tsconfig.json b/examples/basic-host/tsconfig.json
index 9d7c3bc..3c143ca 100644
--- a/examples/basic-host/tsconfig.json
+++ b/examples/basic-host/tsconfig.json
@@ -1,5 +1,6 @@
{
"compilerOptions": {
+ "types": ["node", "vite/client"],
"target": "ESNext",
"lib": ["ESNext", "DOM", "DOM.Iterable"],
"module": "ESNext",
diff --git a/examples/basic-server-preact/README.md b/examples/basic-server-preact/README.md
index b85fb90..6a75ddb 100644
--- a/examples/basic-server-preact/README.md
+++ b/examples/basic-server-preact/README.md
@@ -26,11 +26,29 @@ Add to your MCP client configuration (stdio transport):
}
```
+### Local Development
+
+To test local modifications, use this configuration (replace `~/code/ext-apps` with your clone path):
+
+```json
+{
+ "mcpServers": {
+ "basic-preact": {
+ "command": "bash",
+ "args": [
+ "-c",
+ "cd ~/code/ext-apps/examples/basic-server-preact && npm run build >&2 && node dist/index.js --stdio"
+ ]
+ }
+ }
+}
+```
+
## Overview
- Tool registration with a linked UI resource
-- Preact UI using the [`App`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html) class
-- App communication APIs: [`callServerTool`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#callservertool), [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage), [`sendLog`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendlog), [`openLink`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#openlink)
+- Preact UI using the [`App`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html) class
+- App communication APIs: [`callServerTool`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#callservertool), [`sendMessage`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#sendmessage), [`sendLog`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#sendlog), [`openLink`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#openlink)
## Key Files
@@ -52,4 +70,4 @@ npm run dev
## Build System
-This example bundles into a single HTML file using Vite with `vite-plugin-singlefile` โ see [`vite.config.ts`](vite.config.ts). This allows all UI content to be served as a single MCP resource. Alternatively, MCP apps can load external resources by defining [`_meta.ui.csp.resourceDomains`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceCsp.html#resourcedomains) in the UI resource metadata.
+This example bundles into a single HTML file using Vite with `vite-plugin-singlefile` โ see [`vite.config.ts`](vite.config.ts). This allows all UI content to be served as a single MCP resource. Alternatively, MCP apps can load external resources by defining [`_meta.ui.csp.resourceDomains`](https://apps.extensions.modelcontextprotocol.io/api/interfaces/app.McpUiResourceCsp.html#resourcedomains) in the UI resource metadata.
diff --git a/examples/basic-server-preact/main.ts b/examples/basic-server-preact/main.ts
index 7642632..ffdff52 100644
--- a/examples/basic-server-preact/main.ts
+++ b/examples/basic-server-preact/main.ts
@@ -4,10 +4,10 @@
* Or: node dist/index.js [--stdio]
*/
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/express";
+import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
+import type { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import cors from "cors";
import type { Request, Response } from "express";
import { createServer } from "./server.js";
@@ -27,7 +27,7 @@ export async function startStreamableHTTPServer(
app.all("/mcp", async (req: Request, res: Response) => {
const server = createServer();
- const transport = new StreamableHTTPServerTransport({
+ const transport = new NodeStreamableHTTPServerTransport({
sessionIdGenerator: undefined,
});
diff --git a/examples/basic-server-preact/package.json b/examples/basic-server-preact/package.json
index d58b2f4..60aa40d 100644
--- a/examples/basic-server-preact/package.json
+++ b/examples/basic-server-preact/package.json
@@ -1,11 +1,11 @@
{
"name": "@modelcontextprotocol/server-basic-preact",
- "version": "0.4.2",
+ "version": "2.0.0",
"type": "module",
"description": "Basic MCP App Server example using Preact",
"repository": {
"type": "git",
- "url": "https://github.com/modelcontextprotocol/ext-apps",
+ "url": "git+https://github.com/modelcontextprotocol/ext-apps.git",
"directory": "examples/basic-server-preact"
},
"license": "MIT",
@@ -17,17 +17,22 @@
"build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build && tsc -p tsconfig.server.json && bun build server.ts --outdir dist --target node && bun build main.ts --outfile dist/index.js --target node --external \"./server.js\" --banner \"#!/usr/bin/env node\"",
"watch": "cross-env INPUT=mcp-app.html vite build --watch",
"serve": "bun --watch main.ts",
+ "serve:stdio": "bun main.ts --stdio",
"start": "cross-env NODE_ENV=development npm run build && npm run serve",
- "dev": "cross-env NODE_ENV=development concurrently 'npm run watch' 'npm run serve'",
+ "start:stdio": "cross-env NODE_ENV=development npm run build 1>&2 && npm run serve:stdio",
+ "dev": "cross-env NODE_ENV=development concurrently \"npm run watch\" \"npm run serve\"",
"prepublishOnly": "npm run build"
},
"dependencies": {
- "@modelcontextprotocol/ext-apps": "../..",
- "@modelcontextprotocol/sdk": "^1.24.0",
+ "@modelcontextprotocol/client": "2.0.0",
+ "@modelcontextprotocol/express": "2.0.0",
+ "@modelcontextprotocol/ext-apps": "^2.0.0",
+ "@modelcontextprotocol/node": "2.0.0",
+ "@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"preact": "^10.0.0",
- "zod": "^4.1.13"
+ "zod": "^4.2.0"
},
"devDependencies": {
"@preact/preset-vite": "^2.0.0",
diff --git a/examples/basic-server-preact/server.ts b/examples/basic-server-preact/server.ts
index bf14ea5..dfec94a 100644
--- a/examples/basic-server-preact/server.ts
+++ b/examples/basic-server-preact/server.ts
@@ -1,8 +1,12 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import {
+ McpServer,
+ type CallToolResult,
+ type ReadResourceResult,
+} from "@modelcontextprotocol/server";
import fs from "node:fs/promises";
import path from "node:path";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
// Works both from source (server.ts) and compiled (dist/server.js)
const DIST_DIR = import.meta.filename.endsWith(".ts")
? path.join(import.meta.dirname, "dist")
@@ -28,7 +32,7 @@ export function createServer(): McpServer {
{
title: "Get Time",
description: "Returns the current server time as an ISO 8601 string.",
- inputSchema: {},
+ inputSchema: z.object({}),
_meta: { ui: { resourceUri } }, // Links this tool to its UI resource
},
async (): Promise => {
diff --git a/examples/basic-server-preact/src/global.css b/examples/basic-server-preact/src/global.css
index 08d4da1..801291f 100644
--- a/examples/basic-server-preact/src/global.css
+++ b/examples/basic-server-preact/src/global.css
@@ -1,18 +1,92 @@
+:root {
+ color-scheme: light dark;
+
+ /*
+ * Fallbacks for host style variables used by this app.
+ * The host may provide these (and many more) via the host context.
+ */
+ --color-text-primary: light-dark(#1f2937, #f3f4f6);
+ --color-text-inverse: light-dark(#f3f4f6, #1f2937);
+ --color-text-info: light-dark(#1d4ed8, #60a5fa);
+ --color-background-primary: light-dark(#ffffff, #1a1a1a);
+ --color-background-inverse: light-dark(#1a1a1a, #ffffff);
+ --color-background-info: light-dark(#eff6ff, #1e3a5f);
+ --color-ring-primary: light-dark(#3b82f6, #60a5fa);
+ --border-radius-md: 6px;
+ --border-width-regular: 1px;
+ --font-sans: ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+ --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
+ --font-weight-normal: 400;
+ --font-weight-bold: 700;
+ --font-text-md-size: 1rem;
+ --font-text-md-line-height: 1.5;
+ --font-heading-3xl-size: 2.25rem;
+ --font-heading-3xl-line-height: 1.1;
+ --font-heading-2xl-size: 1.875rem;
+ --font-heading-2xl-line-height: 1.2;
+ --font-heading-xl-size: 1.5rem;
+ --font-heading-xl-line-height: 1.25;
+ --font-heading-lg-size: 1.25rem;
+ --font-heading-lg-line-height: 1.3;
+ --font-heading-md-size: 1rem;
+ --font-heading-md-line-height: 1.4;
+ --font-heading-sm-size: 0.875rem;
+ --font-heading-sm-line-height: 1.4;
+
+ /* Spacing derived from host typography */
+ --spacing-unit: var(--font-text-md-size);
+ --spacing-xs: calc(var(--spacing-unit) * 0.25);
+ --spacing-sm: calc(var(--spacing-unit) * 0.5);
+ --spacing-md: var(--spacing-unit);
+ --spacing-lg: calc(var(--spacing-unit) * 1.5);
+
+ /* App accent color (customize for your brand) */
+ --color-accent: #2563eb;
+ --color-text-on-accent: #ffffff;
+}
+
* {
box-sizing: border-box;
}
html, body {
- font-family: system-ui, -apple-system, sans-serif;
- font-size: 1rem;
+ font-family: var(--font-sans);
+ font-size: var(--font-text-md-size);
+ font-weight: var(--font-weight-normal);
+ line-height: var(--font-text-md-line-height);
+ color: var(--color-text-primary);
}
-code {
+h1 {
+ font-size: var(--font-heading-3xl-size);
+ line-height: var(--font-heading-3xl-line-height);
+}
+h2 {
+ font-size: var(--font-heading-2xl-size);
+ line-height: var(--font-heading-2xl-line-height);
+}
+h3 {
+ font-size: var(--font-heading-xl-size);
+ line-height: var(--font-heading-xl-line-height);
+}
+h4 {
+ font-size: var(--font-heading-lg-size);
+ line-height: var(--font-heading-lg-line-height);
+}
+h5 {
+ font-size: var(--font-heading-md-size);
+ line-height: var(--font-heading-md-line-height);
+}
+h6 {
+ font-size: var(--font-heading-sm-size);
+ line-height: var(--font-heading-sm-line-height);
+}
+
+code, pre, kbd {
+ font-family: var(--font-mono);
font-size: 1em;
}
-/* Server time fills remaining width for consistent E2E screenshot masking */
-#server-time {
- flex: 1;
- min-width: 0;
+b, strong {
+ font-weight: var(--font-weight-bold);
}
diff --git a/examples/basic-server-preact/src/mcp-app.module.css b/examples/basic-server-preact/src/mcp-app.module.css
index 41a0456..ae08a8c 100644
--- a/examples/basic-server-preact/src/mcp-app.module.css
+++ b/examples/basic-server-preact/src/mcp-app.module.css
@@ -1,8 +1,4 @@
.main {
- --color-primary: #2563eb;
- --color-primary-hover: #1d4ed8;
- --color-notice-bg: #eff6ff;
-
width: 100%;
max-width: 425px;
box-sizing: border-box;
@@ -13,7 +9,7 @@
}
> * + * {
- margin-top: 1.5rem;
+ margin-top: var(--spacing-lg);
}
}
@@ -25,48 +21,59 @@
}
> * + * {
- margin-top: 0.5rem;
+ margin-top: var(--spacing-sm);
}
/* Server time row: flex layout for consistent mask width in E2E tests */
> p {
display: flex;
align-items: baseline;
- gap: 0.25em;
+ gap: var(--spacing-xs);
}
/* Consistent font for form inputs (inherits from global.css) */
textarea,
input {
+ display: block;
font-family: inherit;
font-size: inherit;
}
button {
- padding: 0.5rem 1rem;
+ padding: var(--spacing-sm) var(--spacing-md);
border: none;
- border-radius: 6px;
- color: white;
- font-weight: bold;
- background-color: var(--color-primary);
+ border-radius: var(--border-radius-md);
+ color: var(--color-text-on-accent);
+ font-weight: var(--font-weight-bold);
+ background-color: var(--color-accent);
cursor: pointer;
- &:hover,
+ &:hover {
+ background-color: color-mix(in srgb, var(--color-accent) 85%, var(--color-background-inverse));
+ }
+
&:focus-visible {
- background-color: var(--color-primary-hover);
+ outline: calc(var(--border-width-regular) * 2) solid var(--color-ring-primary);
+ outline-offset: var(--border-width-regular);
}
}
}
.notice {
- padding: 0.5rem 0.75rem;
- color: var(--color-primary);
+ padding: var(--spacing-sm) var(--spacing-md);
+ color: var(--color-text-info);
text-align: center;
font-style: italic;
- background-color: var(--color-notice-bg);
+ background-color: var(--color-background-info);
&::before {
content: "โน๏ธ ";
font-style: normal;
}
}
+
+/* Server time fills remaining width for consistent E2E screenshot masking */
+.serverTime {
+ flex: 1;
+ min-width: 0;
+}
diff --git a/examples/basic-server-preact/src/mcp-app.tsx b/examples/basic-server-preact/src/mcp-app.tsx
index d5b6b60..351a8ec 100644
--- a/examples/basic-server-preact/src/mcp-app.tsx
+++ b/examples/basic-server-preact/src/mcp-app.tsx
@@ -8,7 +8,7 @@ import {
applyHostStyleVariables,
type McpUiHostContext,
} from "@modelcontextprotocol/ext-apps";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult } from "@modelcontextprotocol/client";
import { useCallback, useEffect, useState } from "preact/hooks";
import { render } from "preact";
import styles from "./mcp-app.module.css";
@@ -144,7 +144,7 @@ function GetTimeAppInner({ app, toolResult, hostContext }: GetTimeAppInnerProps)
- Server Time:{serverTime}
+ Server Time:{serverTime}
diff --git a/examples/basic-server-preact/tsconfig.json b/examples/basic-server-preact/tsconfig.json
index 32182d9..9bf9389 100644
--- a/examples/basic-server-preact/tsconfig.json
+++ b/examples/basic-server-preact/tsconfig.json
@@ -1,5 +1,6 @@
{
"compilerOptions": {
+ "types": ["node", "vite/client"],
"target": "ESNext",
"lib": ["ESNext", "DOM", "DOM.Iterable"],
"module": "ESNext",
diff --git a/examples/basic-server-preact/tsconfig.server.json b/examples/basic-server-preact/tsconfig.server.json
index 05ddd8e..27eb28f 100644
--- a/examples/basic-server-preact/tsconfig.server.json
+++ b/examples/basic-server-preact/tsconfig.server.json
@@ -1,5 +1,6 @@
{
"compilerOptions": {
+ "types": ["node"],
"target": "ES2022",
"lib": ["ES2022"],
"module": "NodeNext",
diff --git a/examples/basic-server-react/README.md b/examples/basic-server-react/README.md
index 4b3f26c..d2f2e0d 100644
--- a/examples/basic-server-react/README.md
+++ b/examples/basic-server-react/README.md
@@ -28,11 +28,29 @@ Add to your MCP client configuration (stdio transport):
}
```
+### Local Development
+
+To test local modifications, use this configuration (replace `~/code/ext-apps` with your clone path):
+
+```json
+{
+ "mcpServers": {
+ "basic-react": {
+ "command": "bash",
+ "args": [
+ "-c",
+ "cd ~/code/ext-apps/examples/basic-server-react && npm run build >&2 && node dist/index.js --stdio"
+ ]
+ }
+ }
+}
+```
+
## Overview
- Tool registration with a linked UI resource
-- React UI using the [`useApp()`](https://modelcontextprotocol.github.io/ext-apps/api/functions/_modelcontextprotocol_ext-apps_react.useApp.html) hook
-- App communication APIs: [`callServerTool`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#callservertool), [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage), [`sendLog`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendlog), [`openLink`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#openlink)
+- React UI using the [`useApp()`](https://apps.extensions.modelcontextprotocol.io/api/functions/_modelcontextprotocol_ext-apps_react.useApp.html) hook
+- App communication APIs: [`callServerTool`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#callservertool), [`sendMessage`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#sendmessage), [`sendLog`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#sendlog), [`openLink`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#openlink)
## Key Files
@@ -54,4 +72,4 @@ npm run dev
## Build System
-This example bundles into a single HTML file using Vite with `vite-plugin-singlefile` โ see [`vite.config.ts`](vite.config.ts). This allows all UI content to be served as a single MCP resource. Alternatively, MCP apps can load external resources by defining [`_meta.ui.csp.resourceDomains`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceCsp.html#resourcedomains) in the UI resource metadata.
+This example bundles into a single HTML file using Vite with `vite-plugin-singlefile` โ see [`vite.config.ts`](vite.config.ts). This allows all UI content to be served as a single MCP resource. Alternatively, MCP apps can load external resources by defining [`_meta.ui.csp.resourceDomains`](https://apps.extensions.modelcontextprotocol.io/api/interfaces/app.McpUiResourceCsp.html#resourcedomains) in the UI resource metadata.
diff --git a/examples/basic-server-react/main.ts b/examples/basic-server-react/main.ts
index ec187b6..21c5e18 100644
--- a/examples/basic-server-react/main.ts
+++ b/examples/basic-server-react/main.ts
@@ -4,10 +4,10 @@
* Or: node dist/index.js [--stdio]
*/
-import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/express";
+import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
+import type { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import cors from "cors";
import type { Request, Response } from "express";
import { createServer } from "./server.js";
@@ -27,7 +27,7 @@ export async function startStreamableHTTPServer(
app.all("/mcp", async (req: Request, res: Response) => {
const server = createServer();
- const transport = new StreamableHTTPServerTransport({
+ const transport = new NodeStreamableHTTPServerTransport({
sessionIdGenerator: undefined,
});
diff --git a/examples/basic-server-react/package.json b/examples/basic-server-react/package.json
index df612e0..ea51a8a 100644
--- a/examples/basic-server-react/package.json
+++ b/examples/basic-server-react/package.json
@@ -1,11 +1,11 @@
{
"name": "@modelcontextprotocol/server-basic-react",
- "version": "0.4.2",
+ "version": "2.0.0",
"type": "module",
"description": "Basic MCP App Server example using React",
"repository": {
"type": "git",
- "url": "https://github.com/modelcontextprotocol/ext-apps",
+ "url": "git+https://github.com/modelcontextprotocol/ext-apps.git",
"directory": "examples/basic-server-react"
},
"license": "MIT",
@@ -27,18 +27,23 @@
"build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build && tsc -p tsconfig.server.json && bun build server.ts --outdir dist --target node && bun build main.ts --outfile dist/index.js --target node --external \"./server.js\" --banner \"#!/usr/bin/env node\"",
"watch": "cross-env INPUT=mcp-app.html vite build --watch",
"serve": "bun --watch main.ts",
+ "serve:stdio": "bun main.ts --stdio",
"start": "cross-env NODE_ENV=development npm run build && npm run serve",
- "dev": "cross-env NODE_ENV=development concurrently 'npm run watch' 'npm run serve'",
+ "start:stdio": "cross-env NODE_ENV=development npm run build 1>&2 && npm run serve:stdio",
+ "dev": "cross-env NODE_ENV=development concurrently \"npm run watch\" \"npm run serve\"",
"prepublishOnly": "npm run build"
},
"dependencies": {
- "@modelcontextprotocol/ext-apps": "../..",
- "@modelcontextprotocol/sdk": "^1.24.0",
+ "@modelcontextprotocol/client": "2.0.0",
+ "@modelcontextprotocol/express": "2.0.0",
+ "@modelcontextprotocol/ext-apps": "^2.0.0",
+ "@modelcontextprotocol/node": "2.0.0",
+ "@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"react": "^19.2.0",
"react-dom": "^19.2.0",
- "zod": "^4.1.13"
+ "zod": "^4.2.0"
},
"devDependencies": {
"@types/cors": "^2.8.19",
diff --git a/examples/basic-server-react/server.ts b/examples/basic-server-react/server.ts
index 23f6dda..d77c908 100644
--- a/examples/basic-server-react/server.ts
+++ b/examples/basic-server-react/server.ts
@@ -1,8 +1,12 @@
import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import {
+ McpServer,
+ type CallToolResult,
+ type ReadResourceResult,
+} from "@modelcontextprotocol/server";
import fs from "node:fs/promises";
import path from "node:path";
+import { z } from "zod";
// Works both from source (server.ts) and compiled (dist/server.js)
const DIST_DIR = import.meta.filename.endsWith(".ts")
@@ -29,7 +33,7 @@ export function createServer(): McpServer {
{
title: "Get Time",
description: "Returns the current server time as an ISO 8601 string.",
- inputSchema: {},
+ inputSchema: z.object({}),
_meta: { ui: { resourceUri } }, // Links this tool to its UI resource
},
async (): Promise => {
diff --git a/examples/basic-server-react/src/global.css b/examples/basic-server-react/src/global.css
index 08d4da1..801291f 100644
--- a/examples/basic-server-react/src/global.css
+++ b/examples/basic-server-react/src/global.css
@@ -1,18 +1,92 @@
+:root {
+ color-scheme: light dark;
+
+ /*
+ * Fallbacks for host style variables used by this app.
+ * The host may provide these (and many more) via the host context.
+ */
+ --color-text-primary: light-dark(#1f2937, #f3f4f6);
+ --color-text-inverse: light-dark(#f3f4f6, #1f2937);
+ --color-text-info: light-dark(#1d4ed8, #60a5fa);
+ --color-background-primary: light-dark(#ffffff, #1a1a1a);
+ --color-background-inverse: light-dark(#1a1a1a, #ffffff);
+ --color-background-info: light-dark(#eff6ff, #1e3a5f);
+ --color-ring-primary: light-dark(#3b82f6, #60a5fa);
+ --border-radius-md: 6px;
+ --border-width-regular: 1px;
+ --font-sans: ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+ --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
+ --font-weight-normal: 400;
+ --font-weight-bold: 700;
+ --font-text-md-size: 1rem;
+ --font-text-md-line-height: 1.5;
+ --font-heading-3xl-size: 2.25rem;
+ --font-heading-3xl-line-height: 1.1;
+ --font-heading-2xl-size: 1.875rem;
+ --font-heading-2xl-line-height: 1.2;
+ --font-heading-xl-size: 1.5rem;
+ --font-heading-xl-line-height: 1.25;
+ --font-heading-lg-size: 1.25rem;
+ --font-heading-lg-line-height: 1.3;
+ --font-heading-md-size: 1rem;
+ --font-heading-md-line-height: 1.4;
+ --font-heading-sm-size: 0.875rem;
+ --font-heading-sm-line-height: 1.4;
+
+ /* Spacing derived from host typography */
+ --spacing-unit: var(--font-text-md-size);
+ --spacing-xs: calc(var(--spacing-unit) * 0.25);
+ --spacing-sm: calc(var(--spacing-unit) * 0.5);
+ --spacing-md: var(--spacing-unit);
+ --spacing-lg: calc(var(--spacing-unit) * 1.5);
+
+ /* App accent color (customize for your brand) */
+ --color-accent: #2563eb;
+ --color-text-on-accent: #ffffff;
+}
+
* {
box-sizing: border-box;
}
html, body {
- font-family: system-ui, -apple-system, sans-serif;
- font-size: 1rem;
+ font-family: var(--font-sans);
+ font-size: var(--font-text-md-size);
+ font-weight: var(--font-weight-normal);
+ line-height: var(--font-text-md-line-height);
+ color: var(--color-text-primary);
}
-code {
+h1 {
+ font-size: var(--font-heading-3xl-size);
+ line-height: var(--font-heading-3xl-line-height);
+}
+h2 {
+ font-size: var(--font-heading-2xl-size);
+ line-height: var(--font-heading-2xl-line-height);
+}
+h3 {
+ font-size: var(--font-heading-xl-size);
+ line-height: var(--font-heading-xl-line-height);
+}
+h4 {
+ font-size: var(--font-heading-lg-size);
+ line-height: var(--font-heading-lg-line-height);
+}
+h5 {
+ font-size: var(--font-heading-md-size);
+ line-height: var(--font-heading-md-line-height);
+}
+h6 {
+ font-size: var(--font-heading-sm-size);
+ line-height: var(--font-heading-sm-line-height);
+}
+
+code, pre, kbd {
+ font-family: var(--font-mono);
font-size: 1em;
}
-/* Server time fills remaining width for consistent E2E screenshot masking */
-#server-time {
- flex: 1;
- min-width: 0;
+b, strong {
+ font-weight: var(--font-weight-bold);
}
diff --git a/examples/basic-server-react/src/mcp-app.module.css b/examples/basic-server-react/src/mcp-app.module.css
index 41a0456..ae08a8c 100644
--- a/examples/basic-server-react/src/mcp-app.module.css
+++ b/examples/basic-server-react/src/mcp-app.module.css
@@ -1,8 +1,4 @@
.main {
- --color-primary: #2563eb;
- --color-primary-hover: #1d4ed8;
- --color-notice-bg: #eff6ff;
-
width: 100%;
max-width: 425px;
box-sizing: border-box;
@@ -13,7 +9,7 @@
}
> * + * {
- margin-top: 1.5rem;
+ margin-top: var(--spacing-lg);
}
}
@@ -25,48 +21,59 @@
}
> * + * {
- margin-top: 0.5rem;
+ margin-top: var(--spacing-sm);
}
/* Server time row: flex layout for consistent mask width in E2E tests */
> p {
display: flex;
align-items: baseline;
- gap: 0.25em;
+ gap: var(--spacing-xs);
}
/* Consistent font for form inputs (inherits from global.css) */
textarea,
input {
+ display: block;
font-family: inherit;
font-size: inherit;
}
button {
- padding: 0.5rem 1rem;
+ padding: var(--spacing-sm) var(--spacing-md);
border: none;
- border-radius: 6px;
- color: white;
- font-weight: bold;
- background-color: var(--color-primary);
+ border-radius: var(--border-radius-md);
+ color: var(--color-text-on-accent);
+ font-weight: var(--font-weight-bold);
+ background-color: var(--color-accent);
cursor: pointer;
- &:hover,
+ &:hover {
+ background-color: color-mix(in srgb, var(--color-accent) 85%, var(--color-background-inverse));
+ }
+
&:focus-visible {
- background-color: var(--color-primary-hover);
+ outline: calc(var(--border-width-regular) * 2) solid var(--color-ring-primary);
+ outline-offset: var(--border-width-regular);
}
}
}
.notice {
- padding: 0.5rem 0.75rem;
- color: var(--color-primary);
+ padding: var(--spacing-sm) var(--spacing-md);
+ color: var(--color-text-info);
text-align: center;
font-style: italic;
- background-color: var(--color-notice-bg);
+ background-color: var(--color-background-info);
&::before {
content: "โน๏ธ ";
font-style: normal;
}
}
+
+/* Server time fills remaining width for consistent E2E screenshot masking */
+.serverTime {
+ flex: 1;
+ min-width: 0;
+}
diff --git a/examples/basic-server-react/src/mcp-app.tsx b/examples/basic-server-react/src/mcp-app.tsx
index a42fce7..2b5fbef 100644
--- a/examples/basic-server-react/src/mcp-app.tsx
+++ b/examples/basic-server-react/src/mcp-app.tsx
@@ -3,7 +3,7 @@
*/
import type { App, McpUiHostContext } from "@modelcontextprotocol/ext-apps";
import { useApp } from "@modelcontextprotocol/ext-apps/react";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult } from "@modelcontextprotocol/client";
import { StrictMode, useCallback, useEffect, useState } from "react";
import { createRoot } from "react-dom/client";
import styles from "./mcp-app.module.css";
@@ -131,7 +131,7 @@ function GetTimeAppInner({ app, toolResult, hostContext }: GetTimeAppInnerProps)
- Server Time:{serverTime}
+ Server Time:{serverTime}
diff --git a/examples/basic-server-react/tsconfig.json b/examples/basic-server-react/tsconfig.json
index fc3c210..3ecbdad 100644
--- a/examples/basic-server-react/tsconfig.json
+++ b/examples/basic-server-react/tsconfig.json
@@ -1,5 +1,6 @@
{
"compilerOptions": {
+ "types": ["node", "vite/client"],
"target": "ESNext",
"lib": ["ESNext", "DOM", "DOM.Iterable"],
"module": "ESNext",
diff --git a/examples/basic-server-react/tsconfig.server.json b/examples/basic-server-react/tsconfig.server.json
index 05ddd8e..27eb28f 100644
--- a/examples/basic-server-react/tsconfig.server.json
+++ b/examples/basic-server-react/tsconfig.server.json
@@ -1,5 +1,6 @@
{
"compilerOptions": {
+ "types": ["node"],
"target": "ES2022",
"lib": ["ES2022"],
"module": "NodeNext",
diff --git a/examples/basic-server-solid/README.md b/examples/basic-server-solid/README.md
index 693fec3..43811a2 100644
--- a/examples/basic-server-solid/README.md
+++ b/examples/basic-server-solid/README.md
@@ -26,11 +26,29 @@ Add to your MCP client configuration (stdio transport):
}
```
+### Local Development
+
+To test local modifications, use this configuration (replace `~/code/ext-apps` with your clone path):
+
+```json
+{
+ "mcpServers": {
+ "basic-solid": {
+ "command": "bash",
+ "args": [
+ "-c",
+ "cd ~/code/ext-apps/examples/basic-server-solid && npm run build >&2 && node dist/index.js --stdio"
+ ]
+ }
+ }
+}
+```
+
## Overview
- Tool registration with a linked UI resource
-- Solid UI using the [`App`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html) class
-- App communication APIs: [`callServerTool`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#callservertool), [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage), [`sendLog`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendlog), [`openLink`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#openlink)
+- Solid UI using the [`App`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html) class
+- App communication APIs: [`callServerTool`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#callservertool), [`sendMessage`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#sendmessage), [`sendLog`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#sendlog), [`openLink`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#openlink)
## Key Files
@@ -52,4 +70,4 @@ npm run dev
## Build System
-This example bundles into a single HTML file using Vite with `vite-plugin-singlefile` โ see [`vite.config.ts`](vite.config.ts). This allows all UI content to be served as a single MCP resource. Alternatively, MCP apps can load external resources by defining [`_meta.ui.csp.resourceDomains`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceCsp.html#resourcedomains) in the UI resource metadata.
+This example bundles into a single HTML file using Vite with `vite-plugin-singlefile` โ see [`vite.config.ts`](vite.config.ts). This allows all UI content to be served as a single MCP resource. Alternatively, MCP apps can load external resources by defining [`_meta.ui.csp.resourceDomains`](https://apps.extensions.modelcontextprotocol.io/api/interfaces/app.McpUiResourceCsp.html#resourcedomains) in the UI resource metadata.
diff --git a/examples/basic-server-solid/main.ts b/examples/basic-server-solid/main.ts
index c8d9de2..095ef8d 100644
--- a/examples/basic-server-solid/main.ts
+++ b/examples/basic-server-solid/main.ts
@@ -4,10 +4,10 @@
* Or: node dist/index.js [--stdio]
*/
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { createMcpExpressApp } from "@modelcontextprotocol/express";
+import type { McpServer } from "@modelcontextprotocol/server";
+import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
import cors from "cors";
import type { Request, Response } from "express";
import { createServer } from "./server.js";
@@ -27,7 +27,7 @@ export async function startStreamableHTTPServer(
app.all("/mcp", async (req: Request, res: Response) => {
const server = createServer();
- const transport = new StreamableHTTPServerTransport({
+ const transport = new NodeStreamableHTTPServerTransport({
sessionIdGenerator: undefined,
});
diff --git a/examples/basic-server-solid/package.json b/examples/basic-server-solid/package.json
index 313cc3f..b3ca909 100644
--- a/examples/basic-server-solid/package.json
+++ b/examples/basic-server-solid/package.json
@@ -1,11 +1,11 @@
{
"name": "@modelcontextprotocol/server-basic-solid",
- "version": "0.4.2",
+ "version": "2.0.0",
"type": "module",
"description": "Basic MCP App Server example using Solid",
"repository": {
"type": "git",
- "url": "https://github.com/modelcontextprotocol/ext-apps",
+ "url": "git+https://github.com/modelcontextprotocol/ext-apps.git",
"directory": "examples/basic-server-solid"
},
"license": "MIT",
@@ -17,17 +17,22 @@
"build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build && tsc -p tsconfig.server.json && bun build server.ts --outdir dist --target node && bun build main.ts --outfile dist/index.js --target node --external \"./server.js\" --banner \"#!/usr/bin/env node\"",
"watch": "cross-env INPUT=mcp-app.html vite build --watch",
"serve": "bun --watch main.ts",
+ "serve:stdio": "bun main.ts --stdio",
"start": "cross-env NODE_ENV=development npm run build && npm run serve",
- "dev": "cross-env NODE_ENV=development concurrently 'npm run watch' 'npm run serve'",
+ "start:stdio": "cross-env NODE_ENV=development npm run build 1>&2 && npm run serve:stdio",
+ "dev": "cross-env NODE_ENV=development concurrently \"npm run watch\" \"npm run serve\"",
"prepublishOnly": "npm run build"
},
"dependencies": {
- "@modelcontextprotocol/ext-apps": "../..",
- "@modelcontextprotocol/sdk": "^1.24.0",
+ "@modelcontextprotocol/client": "2.0.0",
+ "@modelcontextprotocol/express": "2.0.0",
+ "@modelcontextprotocol/ext-apps": "^2.0.0",
+ "@modelcontextprotocol/node": "2.0.0",
+ "@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"solid-js": "1.9.10",
- "zod": "^4.1.13"
+ "zod": "^4.2.0"
},
"devDependencies": {
"@types/cors": "^2.8.19",
@@ -38,7 +43,7 @@
"typescript": "^5.9.3",
"vite": "^6.0.0",
"vite-plugin-singlefile": "^2.3.0",
- "vite-plugin-solid": "^2.0.0"
+ "vite-plugin-solid": "^2.11.12"
},
"types": "dist/server.d.ts",
"exports": {
diff --git a/examples/basic-server-solid/server.ts b/examples/basic-server-solid/server.ts
index 2ed2d93..addb522 100644
--- a/examples/basic-server-solid/server.ts
+++ b/examples/basic-server-solid/server.ts
@@ -1,8 +1,12 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import {
+ McpServer,
+ type CallToolResult,
+ type ReadResourceResult,
+} from "@modelcontextprotocol/server";
import fs from "node:fs/promises";
import path from "node:path";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
// Works both from source (server.ts) and compiled (dist/server.js)
const DIST_DIR = import.meta.filename.endsWith(".ts")
? path.join(import.meta.dirname, "dist")
@@ -28,7 +32,7 @@ export function createServer(): McpServer {
{
title: "Get Time",
description: "Returns the current server time as an ISO 8601 string.",
- inputSchema: {},
+ inputSchema: z.object({}),
_meta: { ui: { resourceUri } }, // Links this tool to its UI resource
},
async (): Promise => {
diff --git a/examples/basic-server-solid/src/global.css b/examples/basic-server-solid/src/global.css
index 08d4da1..801291f 100644
--- a/examples/basic-server-solid/src/global.css
+++ b/examples/basic-server-solid/src/global.css
@@ -1,18 +1,92 @@
+:root {
+ color-scheme: light dark;
+
+ /*
+ * Fallbacks for host style variables used by this app.
+ * The host may provide these (and many more) via the host context.
+ */
+ --color-text-primary: light-dark(#1f2937, #f3f4f6);
+ --color-text-inverse: light-dark(#f3f4f6, #1f2937);
+ --color-text-info: light-dark(#1d4ed8, #60a5fa);
+ --color-background-primary: light-dark(#ffffff, #1a1a1a);
+ --color-background-inverse: light-dark(#1a1a1a, #ffffff);
+ --color-background-info: light-dark(#eff6ff, #1e3a5f);
+ --color-ring-primary: light-dark(#3b82f6, #60a5fa);
+ --border-radius-md: 6px;
+ --border-width-regular: 1px;
+ --font-sans: ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+ --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
+ --font-weight-normal: 400;
+ --font-weight-bold: 700;
+ --font-text-md-size: 1rem;
+ --font-text-md-line-height: 1.5;
+ --font-heading-3xl-size: 2.25rem;
+ --font-heading-3xl-line-height: 1.1;
+ --font-heading-2xl-size: 1.875rem;
+ --font-heading-2xl-line-height: 1.2;
+ --font-heading-xl-size: 1.5rem;
+ --font-heading-xl-line-height: 1.25;
+ --font-heading-lg-size: 1.25rem;
+ --font-heading-lg-line-height: 1.3;
+ --font-heading-md-size: 1rem;
+ --font-heading-md-line-height: 1.4;
+ --font-heading-sm-size: 0.875rem;
+ --font-heading-sm-line-height: 1.4;
+
+ /* Spacing derived from host typography */
+ --spacing-unit: var(--font-text-md-size);
+ --spacing-xs: calc(var(--spacing-unit) * 0.25);
+ --spacing-sm: calc(var(--spacing-unit) * 0.5);
+ --spacing-md: var(--spacing-unit);
+ --spacing-lg: calc(var(--spacing-unit) * 1.5);
+
+ /* App accent color (customize for your brand) */
+ --color-accent: #2563eb;
+ --color-text-on-accent: #ffffff;
+}
+
* {
box-sizing: border-box;
}
html, body {
- font-family: system-ui, -apple-system, sans-serif;
- font-size: 1rem;
+ font-family: var(--font-sans);
+ font-size: var(--font-text-md-size);
+ font-weight: var(--font-weight-normal);
+ line-height: var(--font-text-md-line-height);
+ color: var(--color-text-primary);
}
-code {
+h1 {
+ font-size: var(--font-heading-3xl-size);
+ line-height: var(--font-heading-3xl-line-height);
+}
+h2 {
+ font-size: var(--font-heading-2xl-size);
+ line-height: var(--font-heading-2xl-line-height);
+}
+h3 {
+ font-size: var(--font-heading-xl-size);
+ line-height: var(--font-heading-xl-line-height);
+}
+h4 {
+ font-size: var(--font-heading-lg-size);
+ line-height: var(--font-heading-lg-line-height);
+}
+h5 {
+ font-size: var(--font-heading-md-size);
+ line-height: var(--font-heading-md-line-height);
+}
+h6 {
+ font-size: var(--font-heading-sm-size);
+ line-height: var(--font-heading-sm-line-height);
+}
+
+code, pre, kbd {
+ font-family: var(--font-mono);
font-size: 1em;
}
-/* Server time fills remaining width for consistent E2E screenshot masking */
-#server-time {
- flex: 1;
- min-width: 0;
+b, strong {
+ font-weight: var(--font-weight-bold);
}
diff --git a/examples/basic-server-solid/src/mcp-app.module.css b/examples/basic-server-solid/src/mcp-app.module.css
index 41a0456..ae08a8c 100644
--- a/examples/basic-server-solid/src/mcp-app.module.css
+++ b/examples/basic-server-solid/src/mcp-app.module.css
@@ -1,8 +1,4 @@
.main {
- --color-primary: #2563eb;
- --color-primary-hover: #1d4ed8;
- --color-notice-bg: #eff6ff;
-
width: 100%;
max-width: 425px;
box-sizing: border-box;
@@ -13,7 +9,7 @@
}
> * + * {
- margin-top: 1.5rem;
+ margin-top: var(--spacing-lg);
}
}
@@ -25,48 +21,59 @@
}
> * + * {
- margin-top: 0.5rem;
+ margin-top: var(--spacing-sm);
}
/* Server time row: flex layout for consistent mask width in E2E tests */
> p {
display: flex;
align-items: baseline;
- gap: 0.25em;
+ gap: var(--spacing-xs);
}
/* Consistent font for form inputs (inherits from global.css) */
textarea,
input {
+ display: block;
font-family: inherit;
font-size: inherit;
}
button {
- padding: 0.5rem 1rem;
+ padding: var(--spacing-sm) var(--spacing-md);
border: none;
- border-radius: 6px;
- color: white;
- font-weight: bold;
- background-color: var(--color-primary);
+ border-radius: var(--border-radius-md);
+ color: var(--color-text-on-accent);
+ font-weight: var(--font-weight-bold);
+ background-color: var(--color-accent);
cursor: pointer;
- &:hover,
+ &:hover {
+ background-color: color-mix(in srgb, var(--color-accent) 85%, var(--color-background-inverse));
+ }
+
&:focus-visible {
- background-color: var(--color-primary-hover);
+ outline: calc(var(--border-width-regular) * 2) solid var(--color-ring-primary);
+ outline-offset: var(--border-width-regular);
}
}
}
.notice {
- padding: 0.5rem 0.75rem;
- color: var(--color-primary);
+ padding: var(--spacing-sm) var(--spacing-md);
+ color: var(--color-text-info);
text-align: center;
font-style: italic;
- background-color: var(--color-notice-bg);
+ background-color: var(--color-background-info);
&::before {
content: "โน๏ธ ";
font-style: normal;
}
}
+
+/* Server time fills remaining width for consistent E2E screenshot masking */
+.serverTime {
+ flex: 1;
+ min-width: 0;
+}
diff --git a/examples/basic-server-solid/src/mcp-app.tsx b/examples/basic-server-solid/src/mcp-app.tsx
index fa054e6..2d78b7b 100644
--- a/examples/basic-server-solid/src/mcp-app.tsx
+++ b/examples/basic-server-solid/src/mcp-app.tsx
@@ -8,7 +8,7 @@ import {
applyHostStyleVariables,
type McpUiHostContext,
} from "@modelcontextprotocol/ext-apps";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult } from "@modelcontextprotocol/client";
import { createEffect, createSignal, onMount, Show } from "solid-js";
import { render } from "solid-js/web";
import styles from "./mcp-app.module.css";
@@ -149,7 +149,7 @@ function GetTimeAppInner(props: GetTimeAppInnerProps) {
- Server Time:{serverTime()}
+ Server Time:{serverTime()}
diff --git a/examples/basic-server-solid/tsconfig.json b/examples/basic-server-solid/tsconfig.json
index 84f0efe..bb13a01 100644
--- a/examples/basic-server-solid/tsconfig.json
+++ b/examples/basic-server-solid/tsconfig.json
@@ -1,5 +1,6 @@
{
"compilerOptions": {
+ "types": ["node", "vite/client"],
"target": "ESNext",
"lib": ["ESNext", "DOM", "DOM.Iterable"],
"module": "ESNext",
diff --git a/examples/basic-server-solid/tsconfig.server.json b/examples/basic-server-solid/tsconfig.server.json
index 05ddd8e..27eb28f 100644
--- a/examples/basic-server-solid/tsconfig.server.json
+++ b/examples/basic-server-solid/tsconfig.server.json
@@ -1,5 +1,6 @@
{
"compilerOptions": {
+ "types": ["node"],
"target": "ES2022",
"lib": ["ES2022"],
"module": "NodeNext",
diff --git a/examples/basic-server-svelte/README.md b/examples/basic-server-svelte/README.md
index ff599af..ec6a0d2 100644
--- a/examples/basic-server-svelte/README.md
+++ b/examples/basic-server-svelte/README.md
@@ -26,11 +26,29 @@ Add to your MCP client configuration (stdio transport):
}
```
+### Local Development
+
+To test local modifications, use this configuration (replace `~/code/ext-apps` with your clone path):
+
+```json
+{
+ "mcpServers": {
+ "basic-svelte": {
+ "command": "bash",
+ "args": [
+ "-c",
+ "cd ~/code/ext-apps/examples/basic-server-svelte && npm run build >&2 && node dist/index.js --stdio"
+ ]
+ }
+ }
+}
+```
+
## Overview
- Tool registration with a linked UI resource
-- Svelte 5 UI using the [`App`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html) class
-- App communication APIs: [`callServerTool`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#callservertool), [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage), [`sendLog`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendlog), [`openLink`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#openlink)
+- Svelte 5 UI using the [`App`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html) class
+- App communication APIs: [`callServerTool`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#callservertool), [`sendMessage`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#sendmessage), [`sendLog`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#sendlog), [`openLink`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html#openlink)
## Key Files
@@ -52,4 +70,4 @@ npm run dev
## Build System
-This example bundles into a single HTML file using Vite with `vite-plugin-singlefile` โ see [`vite.config.ts`](vite.config.ts). This allows all UI content to be served as a single MCP resource. Alternatively, MCP apps can load external resources by defining [`_meta.ui.csp.resourceDomains`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceCsp.html#resourcedomains) in the UI resource metadata.
+This example bundles into a single HTML file using Vite with `vite-plugin-singlefile` โ see [`vite.config.ts`](vite.config.ts). This allows all UI content to be served as a single MCP resource. Alternatively, MCP apps can load external resources by defining [`_meta.ui.csp.resourceDomains`](https://apps.extensions.modelcontextprotocol.io/api/interfaces/app.McpUiResourceCsp.html#resourcedomains) in the UI resource metadata.
diff --git a/examples/basic-server-svelte/main.ts b/examples/basic-server-svelte/main.ts
index 6c50a25..734ec0c 100644
--- a/examples/basic-server-svelte/main.ts
+++ b/examples/basic-server-svelte/main.ts
@@ -4,10 +4,10 @@
* Or: node dist/index.js [--stdio]
*/
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/express";
+import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
+import type { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import cors from "cors";
import type { Request, Response } from "express";
import { createServer } from "./server.js";
@@ -27,7 +27,7 @@ export async function startStreamableHTTPServer(
app.all("/mcp", async (req: Request, res: Response) => {
const server = createServer();
- const transport = new StreamableHTTPServerTransport({
+ const transport = new NodeStreamableHTTPServerTransport({
sessionIdGenerator: undefined,
});
diff --git a/examples/basic-server-svelte/package.json b/examples/basic-server-svelte/package.json
index 608311e..19fe4c9 100644
--- a/examples/basic-server-svelte/package.json
+++ b/examples/basic-server-svelte/package.json
@@ -1,11 +1,11 @@
{
"name": "@modelcontextprotocol/server-basic-svelte",
- "version": "0.4.2",
+ "version": "2.0.0",
"type": "module",
"description": "Basic MCP App Server example using Svelte",
"repository": {
"type": "git",
- "url": "https://github.com/modelcontextprotocol/ext-apps",
+ "url": "git+https://github.com/modelcontextprotocol/ext-apps.git",
"directory": "examples/basic-server-svelte"
},
"license": "MIT",
@@ -17,17 +17,22 @@
"build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build && tsc -p tsconfig.server.json && bun build server.ts --outdir dist --target node && bun build main.ts --outfile dist/index.js --target node --external \"./server.js\" --banner \"#!/usr/bin/env node\"",
"watch": "cross-env INPUT=mcp-app.html vite build --watch",
"serve": "bun --watch main.ts",
+ "serve:stdio": "bun main.ts --stdio",
"start": "cross-env NODE_ENV=development npm run build && npm run serve",
- "dev": "cross-env NODE_ENV=development concurrently 'npm run watch' 'npm run serve'",
+ "start:stdio": "cross-env NODE_ENV=development npm run build 1>&2 && npm run serve:stdio",
+ "dev": "cross-env NODE_ENV=development concurrently \"npm run watch\" \"npm run serve\"",
"prepublishOnly": "npm run build"
},
"dependencies": {
- "@modelcontextprotocol/ext-apps": "../..",
- "@modelcontextprotocol/sdk": "^1.24.0",
+ "@modelcontextprotocol/client": "2.0.0",
+ "@modelcontextprotocol/express": "2.0.0",
+ "@modelcontextprotocol/ext-apps": "^2.0.0",
+ "@modelcontextprotocol/node": "2.0.0",
+ "@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"svelte": "^5.0.0",
- "zod": "^4.1.13"
+ "zod": "^4.2.0"
},
"devDependencies": {
"@sveltejs/vite-plugin-svelte": "^5.0.0",
diff --git a/examples/basic-server-svelte/server.ts b/examples/basic-server-svelte/server.ts
index da603ca..9414285 100644
--- a/examples/basic-server-svelte/server.ts
+++ b/examples/basic-server-svelte/server.ts
@@ -1,8 +1,12 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import {
+ McpServer,
+ type CallToolResult,
+ type ReadResourceResult,
+} from "@modelcontextprotocol/server";
import fs from "node:fs/promises";
import path from "node:path";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
// Works both from source (server.ts) and compiled (dist/server.js)
const DIST_DIR = import.meta.filename.endsWith(".ts")
? path.join(import.meta.dirname, "dist")
@@ -28,7 +32,7 @@ export function createServer(): McpServer {
{
title: "Get Time",
description: "Returns the current server time as an ISO 8601 string.",
- inputSchema: {},
+ inputSchema: z.object({}),
_meta: { ui: { resourceUri } }, // Links this tool to its UI resource
},
async (): Promise => {
diff --git a/examples/basic-server-svelte/src/App.svelte b/examples/basic-server-svelte/src/App.svelte
index 48fbe66..cabcc31 100644
--- a/examples/basic-server-svelte/src/App.svelte
+++ b/examples/basic-server-svelte/src/App.svelte
@@ -7,7 +7,7 @@ import {
applyHostStyleVariables,
type McpUiHostContext,
} from "@modelcontextprotocol/ext-apps";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult } from "@modelcontextprotocol/client";
function extractTime(result: CallToolResult): string {
const { text } = result.content?.find((c) => c.type === "text")!;
@@ -111,7 +111,7 @@ async function handleOpenLink() {
Watch activity in the DevTools console!
-
Server Time:{serverTime}
+
Server Time:{serverTime}
@@ -133,10 +133,6 @@ async function handleOpenLink() {
+
+ 
+ 
