Upload folder using huggingface_hub

.gitattributes

@@ -1,35 +1,11 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Force LF line endings for all text files (for consistent prettier formatting)
+* text=auto eol=lf
+
+package-lock.json linguist-generated=true
+src/generated/** linguist-generated=true
+examples/map-server/grid-cell.png filter=lfs diff=lfs merge=lfs -text
+examples/map-server/screenshot.png filter=lfs diff=lfs merge=lfs -text
+examples/shadertoy-server/screenshot.png filter=lfs diff=lfs merge=lfs -text
+examples/video-resource-server/grid-cell.png filter=lfs diff=lfs merge=lfs -text
+examples/video-resource-server/screenshot.png filter=lfs diff=lfs merge=lfs -text
+tests/e2e/servers.spec.ts-snapshots/map-server.png filter=lfs diff=lfs merge=lfs -text

.github/workflows/ci.yml

@@ -0,0 +1,154 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            name: Linux x64
+          - os: ubuntu-24.04-arm
+            name: Linux ARM64
+          - os: windows-latest
+            name: Windows x64
+          - os: windows-11-arm
+            name: Windows ARM64
+          - os: macos-latest
+            name: macOS ARM64
+
+    name: Build (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify no private URLs in package-lock.json
+        shell: bash
+        run: '! grep -E "\"resolved\": \"https?://" package-lock.json | grep -v registry.npmjs.org'
+
+      - name: Verify example dependency versions
+        shell: bash
+        run: node scripts/check-versions.mjs
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: npm install
+
+      - run: npm run build
+
+      - run: npm run examples:build
+
+      - name: Verify generated schemas are up-to-date
+        shell: bash
+        run: |
+          npm run generate:schemas
+          git diff --exit-code src/generated/ || (echo "Generated schemas are out of date. Run 'npm run generate:schemas' and commit." && exit 1)
+
+      - run: npm test
+
+      - run: npm run prettier
+
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run E2E tests
+        run: npx playwright test --reporter=list
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 7
+
+  # Test build in Windows WSL (Ubuntu)
+  build-wsl:
+    name: Build (Windows WSL)
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: Vampire/setup-wsl@v5
+        with:
+          distribution: Ubuntu-24.04
+
+      - name: Install Node.js in WSL
+        shell: wsl-bash {0}
+        run: |
+          sudo apt-get update
+          curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+          sudo apt-get install -y nodejs
+
+      - name: Build and test in WSL
+        shell: wsl-bash {0}
+        run: |
+          npm install
+          npm run build
+          npm run examples:build
+          npm test
+          npm run prettier
+
+  # Test that the package can be installed from git (triggers prepare script)
+  test-git-install:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            name: Linux x64
+          - os: ubuntu-24.04-arm
+            name: Linux ARM64
+          - os: windows-latest
+            name: Windows x64
+          - os: windows-11-arm
+            name: Windows ARM64
+          - os: macos-latest
+            name: macOS ARM64
+
+    name: Test git install (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Create test project and install from git
+        shell: bash
+        run: |
+          mkdir test-project
+          cd test-project
+          npm init -y
+          # Install from the PR branch (use head repo for fork PRs)
+          npm install "git+https://github.com/${{ github.event.pull_request.head.repo.full_name || github.repository }}#${{ github.head_ref || github.ref_name }}"
+          # Verify the package is usable (ESM import)
+          node --input-type=module -e "import { App } from '@modelcontextprotocol/ext-apps'; console.log('Import successful:', typeof App)"

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Deploy Documentation
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm install
+      - run: npm run build
+      - run: npm run docs
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          publish_branch: gh-pages
+          keep_files: true

.github/workflows/npm-publish.yml

@@ -0,0 +1,139 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run prettier
+
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+      - run: npm ci
+      - run: npm test
+
+  publish:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    environment: Release
+    needs: [build, test]
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
+
+      - name: Determine npm tag
+        id: npm-tag
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          # Check if this is a beta release
+          if [[ "$VERSION" == *"-beta"* ]]; then
+            echo "tag=--tag beta" >> $GITHUB_OUTPUT
+          # Check if this release is from a non-main branch (patch/maintenance release)
+          elif [[ "${{ github.event.release.target_commitish }}" != "main" ]]; then
+            # Use "release-X.Y" as tag for old branch releases
+            MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1,2)
+            echo "tag=--tag release-${MAJOR_MINOR}" >> $GITHUB_OUTPUT
+          else
+            echo "tag=" >> $GITHUB_OUTPUT
+          fi
+
+      - run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_SECRET }}
+
+  publish-examples:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    environment: Release
+    needs: [publish]
+
+    permissions:
+      contents: read
+      id-token: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        example:
+          - basic-server-preact
+          - basic-server-react
+          - basic-server-solid
+          - basic-server-svelte
+          - basic-server-vanillajs
+          - basic-server-vue
+          - budget-allocator-server
+          - cohort-heatmap-server
+          - customer-segmentation-server
+          - map-server
+          - pdf-server
+          - scenario-modeler-server
+          - shadertoy-server
+          - sheet-music-server
+          - system-monitor-server
+          - threejs-server
+          - transcript-server
+          - video-resource-server
+          - wiki-explorer-server
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
+
+      - name: Build example
+        run: npm run build --workspace examples/${{ matrix.example }}
+
+      - name: Publish example
+        run: npm publish --workspace examples/${{ matrix.example }} --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_SECRET }}

.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish Any Commit
+permissions:
+  contents: read
+on:
+  pull_request:
+  push:
+    branches:
+      - "**"
+    tags:
+      - "!**"
+
+jobs:
+  pkg-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run examples:build
+      - run: |
+          npx pkg-pr-new publish \
+            . \
+            ./examples/basic-server-react \
+            ./examples/basic-server-vanillajs \
+            ./examples/budget-allocator-server \
+            ./examples/cohort-heatmap-server \
+            ./examples/customer-segmentation-server \
+            ./examples/map-server \
+            ./examples/pdf-server \
+            ./examples/scenario-modeler-server \
+            ./examples/shadertoy-server \
+            ./examples/sheet-music-server \
+            ./examples/system-monitor-server \
+            ./examples/threejs-server \
+            ./examples/transcript-server \
+            ./examples/video-resource-server \
+            ./examples/wiki-explorer-server

.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+dist/
+node_modules/
+yarn.lock
+bun.lockb
+.vscode/
+docs/api/
+tmp/
+intermediate-findings/
+
+# Playwright
+playwright-report/
+test-results/

.husky/pre-commit

@@ -0,0 +1,12 @@
+# Verify no private registry URLs in package-lock.json
+if grep -E '"resolved": "https?://' package-lock.json | grep -v registry.npmjs.org > /dev/null; then
+  echo "ERROR: package-lock.json contains non-npmjs.org URLs"
+  echo "Run: docker run --rm -i -v \$PWD:/src -w /src node:latest npm i --registry=https://registry.npmjs.org/"
+  exit 1
+fi
+
+npm run build:all
+npm run prettier:fix
+
+# Stage any changes to generated files (they may have been reformatted by prettier)
+git add src/generated/

.prettierignore

@@ -0,0 +1,6 @@
+examples/basic-host/**/*.ts
+examples/basic-host/**/*.tsx
+examples/basic-server-*/**/*.ts
+examples/basic-server-*/**/*.tsx
+**/vendor/**
+SKILL.md

.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": false,
+  "printWidth": 80,
+  "tabWidth": 2
+}

AGENTS.md

@@ -0,0 +1,91 @@
+# MCP Apps SDK
+
+## Project Overview
+
+MCP Apps SDK (`@modelcontextprotocol/ext-apps`) enables MCP servers to display interactive UIs in conversational clients.
+
+Key abstractions:
+
+- **Guest** - UI running in an iframe, uses `App` class with `PostMessageTransport` to communicate with host
+- **Host** - Chat client embedding the iframe, uses `AppBridge` class to proxy MCP requests
+- **Server** - MCP server that registers tools/resources with UI metadata
+
+Specification (draft): `specification/draft/apps.mdx`
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK only (generates schemas + bundles, does not build examples)
+npm run build
+
+# Build everything (SDK + all examples)
+npm run build:all
+
+# Type check + build a single example
+npm run --workspace examples/<example-name> build
+
+# Run all examples (starts server at http://localhost:8080)
+npm start
+
+# Run E2E tests (primary testing mechanism - starts examples server automatically)
+npm run test:e2e
+
+# Run unit tests (E2E tests have broader coverage; unit tests cover specific modules)
+npm test
+
+# Check JSDoc comment syntax and `{@link}` references
+npm exec typedoc -- --treatValidationWarningsAsErrors --emit none
+
+# Regenerate package-lock.json (especially on setups w/ custom npm registry)
+rm -fR  package-lock.json node_modules && \
+  docker run  --rm -it --platform linux/amd64 -v $PWD:/src:rw -w /src node:latest npm i && \
+  rm -fR node_modules && \
+  npm  i  --cache=~/.npm-mcp-apps --registry=https://registry.npmjs.org/
+```
+
+## Architecture
+
+### SDK Entry Points
+
+- `@modelcontextprotocol/ext-apps` - Main SDK for Apps (`App` class, `PostMessageTransport`)
+- `@modelcontextprotocol/ext-apps/react` - React hooks (`useApp`, `useHostStyleVariables`, etc.)
+- `@modelcontextprotocol/ext-apps/app-bridge` - SDK for hosts (`AppBridge` class)
+- `@modelcontextprotocol/ext-apps/server` - Server helpers (`registerAppTool`, `registerAppResource`)
+
+### Key Source Files
+
+- `src/app.ts` - `App` class extends MCP Protocol, handles guest initialization, tool calls, messaging
+- `src/app-bridge.ts` - `AppBridge` class for hosts, proxies MCP requests, sends tool input/results to guests
+- `src/server/index.ts` - Helpers for MCP servers to register tools/resources with UI metadata
+- `src/types.ts` - Protocol types re-exported from `spec.types.ts` and Zod schemas from `generated/schema.ts` (auto-generated during build)
+- `src/message-transport.ts` - `PostMessageTransport` for iframe communication
+- `src/react/` - React hooks: `useApp`, `useHostStyles`, `useAutoResize`, `useDocumentTheme`
+
+### Protocol Flow
+
+```
+Guest UI (App) <--PostMessageTransport--> Host (AppBridge) <--MCP Client--> MCP Server
+```
+
+1. Host creates iframe with Guest UI HTML
+2. Guest UI creates `App` instance and calls `connect()` with `PostMessageTransport`
+3. App sends `ui/initialize` request, receives host capabilities and context
+4. Host sends `sendToolInput()` with tool arguments after initialization
+5. Guest UI can call server tools via `app.callServerTool()` or send messages via `app.sendMessage()`
+6. Host sends `sendToolResult()` when tool execution completes
+7. Host calls `teardownResource()` before unmounting iframe
+
+## Examples
+
+Uses npm workspaces. Examples in `examples/` are separate packages:
+
+- `basic-server-*` - Starter templates (vanillajs, react, vue, svelte, preact, solid). Use these as the basis for new examples.
+- `basic-host` - Reference host implementation
+- Other examples showcase specific features (charts, 3D, video, etc.)
+
+## Claude Code Plugin
+
+The `plugins/mcp-apps/` directory contains a Claude Code plugin distributed via the plugin marketplace. It provides the "Create MCP App" skill (`plugins/mcp-apps/skills/create-mcp-app/SKILL.md`) that guides users through building MCP Apps with interactive UIs.

CLAUDE.md

@@ -0,0 +1,91 @@
+# MCP Apps SDK
+
+## Project Overview
+
+MCP Apps SDK (`@modelcontextprotocol/ext-apps`) enables MCP servers to display interactive UIs in conversational clients.
+
+Key abstractions:
+
+- **Guest** - UI running in an iframe, uses `App` class with `PostMessageTransport` to communicate with host
+- **Host** - Chat client embedding the iframe, uses `AppBridge` class to proxy MCP requests
+- **Server** - MCP server that registers tools/resources with UI metadata
+
+Specification (draft): `specification/draft/apps.mdx`
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK only (generates schemas + bundles, does not build examples)
+npm run build
+
+# Build everything (SDK + all examples)
+npm run build:all
+
+# Type check + build a single example
+npm run --workspace examples/<example-name> build
+
+# Run all examples (starts server at http://localhost:8080)
+npm start
+
+# Run E2E tests (primary testing mechanism - starts examples server automatically)
+npm run test:e2e
+
+# Run unit tests (E2E tests have broader coverage; unit tests cover specific modules)
+npm test
+
+# Check JSDoc comment syntax and `{@link}` references
+npm exec typedoc -- --treatValidationWarningsAsErrors --emit none
+
+# Regenerate package-lock.json (especially on setups w/ custom npm registry)
+rm -fR  package-lock.json node_modules && \
+  docker run  --rm -it --platform linux/amd64 -v $PWD:/src:rw -w /src node:latest npm i && \
+  rm -fR node_modules && \
+  npm  i  --cache=~/.npm-mcp-apps --registry=https://registry.npmjs.org/
+```
+
+## Architecture
+
+### SDK Entry Points
+
+- `@modelcontextprotocol/ext-apps` - Main SDK for Apps (`App` class, `PostMessageTransport`)
+- `@modelcontextprotocol/ext-apps/react` - React hooks (`useApp`, `useHostStyleVariables`, etc.)
+- `@modelcontextprotocol/ext-apps/app-bridge` - SDK for hosts (`AppBridge` class)
+- `@modelcontextprotocol/ext-apps/server` - Server helpers (`registerAppTool`, `registerAppResource`)
+
+### Key Source Files
+
+- `src/app.ts` - `App` class extends MCP Protocol, handles guest initialization, tool calls, messaging
+- `src/app-bridge.ts` - `AppBridge` class for hosts, proxies MCP requests, sends tool input/results to guests
+- `src/server/index.ts` - Helpers for MCP servers to register tools/resources with UI metadata
+- `src/types.ts` - Protocol types re-exported from `spec.types.ts` and Zod schemas from `generated/schema.ts` (auto-generated during build)
+- `src/message-transport.ts` - `PostMessageTransport` for iframe communication
+- `src/react/` - React hooks: `useApp`, `useHostStyles`, `useAutoResize`, `useDocumentTheme`
+
+### Protocol Flow
+
+```
+Guest UI (App) <--PostMessageTransport--> Host (AppBridge) <--MCP Client--> MCP Server
+```
+
+1. Host creates iframe with Guest UI HTML
+2. Guest UI creates `App` instance and calls `connect()` with `PostMessageTransport`
+3. App sends `ui/initialize` request, receives host capabilities and context
+4. Host sends `sendToolInput()` with tool arguments after initialization
+5. Guest UI can call server tools via `app.callServerTool()` or send messages via `app.sendMessage()`
+6. Host sends `sendToolResult()` when tool execution completes
+7. Host calls `teardownResource()` before unmounting iframe
+
+## Examples
+
+Uses npm workspaces. Examples in `examples/` are separate packages:
+
+- `basic-server-*` - Starter templates (vanillajs, react, vue, svelte, preact, solid). Use these as the basis for new examples.
+- `basic-host` - Reference host implementation
+- Other examples showcase specific features (charts, 3D, video, etc.)
+
+## Claude Code Plugin
+
+The `plugins/mcp-apps/` directory contains a Claude Code plugin distributed via the plugin marketplace. It provides the "Create MCP App" skill (`plugins/mcp-apps/skills/create-mcp-app/SKILL.md`) that guides users through building MCP Apps with interactive UIs.

CONTRIBUTING.md

@@ -0,0 +1,184 @@
+# Contributing to MCP Apps SDK
+
+We welcome contributions to the MCP Apps SDK! This document outlines the process for contributing to the project.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/ext-apps.git`
+3. Install dependencies: `npm install`
+4. Build the project: `npm run build`
+5. Run tests: `npm test`
+
+## Development Process
+
+1. Create a new branch for your changes
+2. Make your changes
+3. Run `npm run prettier` to ensure code style compliance
+4. Run `npm test` to verify all tests pass
+5. Submit a pull request
+
+## Pull Request Guidelines
+
+- Follow the existing code style
+- Include tests for new functionality
+- Update documentation as needed
+- Keep changes focused and atomic
+- Provide a clear description of changes
+
+## Running Examples
+
+Start the development environment with hot reloading:
+
+```bash
+npm run examples:dev
+```
+
+Or build and run examples:
+
+```bash
+npm run examples:start
+```
+
+## Testing
+
+### Unit Tests
+
+Run unit tests with Bun:
+
+```bash
+npm test
+```
+
+### E2E Tests
+
+E2E tests use Playwright to verify all example servers work correctly with screenshot comparisons.
+
+```bash
+# Run all E2E tests
+npm run test:e2e
+
+# Run a specific server's tests
+npm run test:e2e -- --grep "Budget Allocator"
+
+# Run tests in interactive UI mode
+npm run test:e2e:ui
+```
+
+### Updating Golden Screenshots
+
+When UI changes are intentional, update the golden screenshots:
+
+```bash
+# Update all screenshots
+npm run test:e2e:update
+
+# Update screenshots for a specific server
+npm run test:e2e:update -- --grep "Three.js"
+```
+
+**Note**: Golden screenshots are platform-agnostic. Tests use canvas masking and tolerance thresholds to handle minor cross-platform rendering differences.
+
+## Code of Conduct
+
+This project follows our [Code of Conduct](CODE_OF_CONDUCT.md). Please review it before contributing.
+
+## Reporting Issues
+
+- Use the [GitHub issue tracker](https://github.com/modelcontextprotocol/ext-apps/issues)
+- Search existing issues before creating a new one
+- Provide clear reproduction steps
+
+## Security Issues
+
+Please review our [Security Policy](SECURITY.md) for reporting security vulnerabilities.
+
+---
+
+## For Maintainers
+
+### Repository Setup
+
+This repository uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) with OIDC - no secrets required.
+
+Before publishing releases, ensure the following are configured:
+
+1. **Trusted publisher on npm**: Configure the package to trust this GitHub repository
+   - Go to https://www.npmjs.com/package/@modelcontextprotocol/ext-apps/access
+   - Under "Trusted Publishers", click "Add trusted publisher"
+   - Select "GitHub Actions"
+   - Repository: `modelcontextprotocol/ext-apps`
+   - Workflow filename: `npm-publish.yml`
+   - Environment: `Release` (optional, for additional protection)
+
+2. **`Release` environment** (optional): Create a protected environment for additional safeguards
+   - Go to Settings > Environments > New environment
+   - Name it `Release`
+   - Add required reviewers or other protection rules as needed
+
+### Publishing a Release
+
+Releases are published automatically via GitHub Actions when a GitHub Release is created.
+
+#### Steps to publish:
+
+1. **Update the version** in `package.json`:
+
+   ```bash
+   # For a regular release
+   npm version patch  # or minor, or major
+
+   # For a beta release
+   npm version prerelease --preid=beta
+   ```
+
+2. **Commit the version bump** (if not done by `npm version`):
+
+   ```bash
+   git add package.json
+   git commit -m "Bump version to X.Y.Z"
+   git push origin main
+   ```
+
+3. **Create a GitHub Release**:
+   - Go to [Releases](https://github.com/modelcontextprotocol/ext-apps/releases)
+   - Click "Draft a new release"
+   - Create a new tag matching the version (e.g., `v0.1.0`)
+   - Set the target branch (usually `main`)
+   - Write release notes describing the changes
+   - Click "Publish release"
+
+4. **Monitor the workflow**:
+   - The [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml) will trigger automatically
+   - It runs build and test jobs before publishing
+   - On success, the package is published to npm with provenance
+
+#### npm Tags
+
+The workflow automatically determines the npm dist-tag:
+
+| Version Pattern               | npm Tag       | Install Command                                          |
+| ----------------------------- | ------------- | -------------------------------------------------------- |
+| `X.Y.Z` (from main)           | `latest`      | `npm install @modelcontextprotocol/ext-apps`             |
+| `X.Y.Z-beta.N`                | `beta`        | `npm install @modelcontextprotocol/ext-apps@beta`        |
+| `X.Y.Z` (from release branch) | `release-X.Y` | `npm install @modelcontextprotocol/ext-apps@release-X.Y` |
+
+#### Maintenance Releases
+
+To release a patch for an older version:
+
+1. Create a release branch from the tag: `git checkout -b release-0.1 v0.1.0`
+2. Cherry-pick or apply fixes
+3. Bump the patch version
+4. Create a GitHub Release targeting the release branch
+5. The package will be published with tag `release-0.1`
+
+### Testing Pre-releases
+
+Every commit and PR automatically publishes a preview package via [pkg-pr-new](https://github.com/pkg-pr-new/pkg-pr-new). Check the PR comments or workflow logs for the install command.
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

LICENSE

@@ -0,0 +1,216 @@
+The MCP project is undergoing a licensing transition from the MIT License to the Apache License, Version 2.0 ("Apache-2.0"). All new code and specification contributions to the project are licensed under Apache-2.0. Documentation contributions (excluding specifications) are licensed under CC-BY-4.0.
+
+Contributions for which relicensing consent has been obtained are licensed under Apache-2.0. Contributions made by authors who originally licensed their work under the MIT License and who have not yet granted explicit permission to relicense remain licensed under the MIT License.
+
+No rights beyond those granted by the applicable original license are conveyed for such contributions.
+
+---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on behalf
+      of the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+---
+
+MIT License
+
+Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Creative Commons Attribution 4.0 International (CC-BY-4.0)
+
+Documentation in this project (excluding specifications) is licensed under
+CC-BY-4.0. See https://creativecommons.org/licenses/by/4.0/legalcode for
+the full license text.

README.md

@@ -0,0 +1,96 @@
+# @modelcontextprotocol/ext-apps
+
+[![npm version](https://img.shields.io/npm/v/@modelcontextprotocol/ext-apps.svg)](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) [![API Documentation](https://img.shields.io/badge/docs-API%20Reference-blue)](https://modelcontextprotocol.github.io/ext-apps/api/)
+
+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)).
+
+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.
+
+## How It Works
+
+MCP Apps extend the Model Context Protocol to let servers deliver **interactive UIs** to MCP hosts. Here's how it works:
+
+1. **Tool call** — The LLM calls a tool on your server
+2. **UI Resource** — The tool's definition links to a predeclared `ui://` resource containing its HTML interface
+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
+
+This enables dashboards, forms, visualizations, and other rich experiences inside chat interfaces.
+
+## Overview
+
+This SDK serves two audiences:
+
+### 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)
+
+### 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
+```
+
+Or edit your `package.json` manually:
+
+```json
+{
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^0.0.1"
+  }
+}
+```
+
+## Examples
+
+<!-- prettier-ignore-start -->
+| | | |
+|:---:|:---:|:---:|
+| [![Map](examples/map-server/grid-cell.png "Interactive 3D globe viewer using CesiumJS")](examples/map-server) | [![Three.js](examples/threejs-server/grid-cell.png "Interactive 3D scene renderer")](examples/threejs-server) | [![ShaderToy](examples/shadertoy-server/grid-cell.png "Real-time GLSL shader renderer")](examples/shadertoy-server) |
+| [**Map**](examples/map-server) | [**Three.js**](examples/threejs-server) | [**ShaderToy**](examples/shadertoy-server) |
+| [![Sheet Music](examples/sheet-music-server/grid-cell.png "ABC notation to sheet music")](examples/sheet-music-server) | [![Wiki Explorer](examples/wiki-explorer-server/grid-cell.png "Wikipedia link graph visualization")](examples/wiki-explorer-server) | [![Cohort Heatmap](examples/cohort-heatmap-server/grid-cell.png "Customer retention heatmap")](examples/cohort-heatmap-server) |
+| [**Sheet Music**](examples/sheet-music-server) | [**Wiki Explorer**](examples/wiki-explorer-server) | [**Cohort Heatmap**](examples/cohort-heatmap-server) |
+| [![Scenario Modeler](examples/scenario-modeler-server/grid-cell.png "SaaS business projections")](examples/scenario-modeler-server) | [![Budget Allocator](examples/budget-allocator-server/grid-cell.png "Interactive budget allocation")](examples/budget-allocator-server) | [![Customer Segmentation](examples/customer-segmentation-server/grid-cell.png "Scatter chart with clustering")](examples/customer-segmentation-server) |
+| [**Scenario Modeler**](examples/scenario-modeler-server) | [**Budget Allocator**](examples/budget-allocator-server) | [**Customer Segmentation**](examples/customer-segmentation-server) |
+| [![System Monitor](examples/system-monitor-server/grid-cell.png "Real-time OS metrics")](examples/system-monitor-server) | [![Transcript](examples/transcript-server/grid-cell.png "Live speech transcription")](examples/transcript-server) | [![Video Resource](examples/video-resource-server/grid-cell.png "Binary video via MCP resources")](examples/video-resource-server) |
+| [**System Monitor**](examples/system-monitor-server) | [**Transcript**](examples/transcript-server) | [**Video Resource**](examples/video-resource-server) |
+| [![PDF Server](examples/pdf-server/grid-cell.png "Interactive PDF viewer with chunked loading")](examples/pdf-server) | | |
+| [**PDF Server**](examples/pdf-server) | | |
+
+### Starter Templates
+
+| | |
+|:---:|:---|
+| [![Basic](examples/basic-server-react/grid-cell.png "Starter template")](examples/basic-server-react) | The same app built with different frameworks — pick your favorite!<br><br>[React](examples/basic-server-react) · [Vue](examples/basic-server-vue) · [Svelte](examples/basic-server-svelte) · [Preact](examples/basic-server-preact) · [Solid](examples/basic-server-solid) · [Vanilla JS](examples/basic-server-vanillajs) |
+<!-- prettier-ignore-end -->
+
+The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains additional demo apps showcasing real-world use cases.
+
+To run all examples:
+
+```bash
+npm install
+npm start
+```
+
+Then open http://localhost:8080/.
+
+## 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)
+- [SEP-1865 Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)

RELEASES.md

@@ -0,0 +1,64 @@
+# Release Notes
+
+## 0.3.0
+
+### Breaking Changes
+
+- **`viewport` replaced with `containerDimensions`** — The `viewport` property in host context has been replaced with `containerDimensions`, which provides a clearer distinction between fixed dimensions and maximum constraints. The new type allows specifying either `height` or `maxHeight`, and either `width` or `maxWidth` by @martinalong in [#153](https://github.com/modelcontextprotocol/ext-apps/pull/153)
+
+### New Examples
+
+- **Video resource server** — Demonstrates video resource handling with proper mimeType declarations by @antonpk1 in [#175](https://github.com/modelcontextprotocol/ext-apps/pull/175)
+- **Sheet music server** — Interactive sheet music notation example by @jonathanhefner in [#196](https://github.com/modelcontextprotocol/ext-apps/pull/196)
+
+### Developer Experience
+
+- **`npm start` alias** — Added `npm start` as alias for `npm run examples:start` by @jonathanhefner in [#183](https://github.com/modelcontextprotocol/ext-apps/pull/183)
+- **Examples cleanup** — Improved consistency across example servers by @jonathanhefner in [#182](https://github.com/modelcontextprotocol/ext-apps/pull/182)
+- **Documentation fixes** — Fixed tsc command in docs to use tsconfig.json by @blackgirlbytes in [#188](https://github.com/modelcontextprotocol/ext-apps/pull/188)
+
+### Bug Fixes
+
+- **Move prettier to dev dependency** — Fixed incorrect dependency classification by @niclim in [#179](https://github.com/modelcontextprotocol/ext-apps/pull/179)
+- **Fix build errors in examples** — Resolved build issues across example servers by @jonathanhefner in [#180](https://github.com/modelcontextprotocol/ext-apps/pull/180)
+
+**Full Changelog**: https://github.com/modelcontextprotocol/ext-apps/compare/v0.2.2...v0.3.0
+
+---
+
+## 0.2.2
+
+Changes from 0.1.x to 0.2.2.
+
+### Highlights
+
+- **Server helpers** — New `registerAppTool()` and `registerAppResource()` simplify server setup with proper type safety. `connect()` now defaults to `PostMessageTransport(window.parent)`, enabling simpler initialization with just `await app.connect()` by @ochafik in [#165](https://github.com/modelcontextprotocol/ext-apps/pull/165)
+- **Tool visibility control** — New `visibility` array field controls whether tools are visible to the agent, apps, or both. Restructured `_meta` format from flat `"ui/resourceUri"` to nested `_meta.ui.resourceUri` by @jonathanhefner in [#131](https://github.com/modelcontextprotocol/ext-apps/pull/131)
+- **Host-provided theming** — Apps receive 36 standardized CSS variables for colors, typography, and spacing via `styles.variables`, enabling visual consistency with the host by @martinalong in [#127](https://github.com/modelcontextprotocol/ext-apps/pull/127)
+- **Display mode requests** — Apps can request display mode changes (e.g., fullscreen) via `requestDisplayMode`, with hosts able to accept or reject by @martinalong in [#152](https://github.com/modelcontextprotocol/ext-apps/pull/152)
+- **Custom fonts support** — Apps can receive custom fonts via `styles.css.fonts` and apply them using `applyHostFonts()` or `useHostFonts()` helpers by @martinalong in [#159](https://github.com/modelcontextprotocol/ext-apps/pull/159)
+
+### API Changes
+
+- **MCP SDK as peer dependency** — Consumers control their SDK version, reducing duplication by @ochafik in [#168](https://github.com/modelcontextprotocol/ext-apps/pull/168)
+- **React as peer dependency** — Supports React 17, 18, and 19 by @ochafik in [#164](https://github.com/modelcontextprotocol/ext-apps/pull/164)
+- **Renamed request methods** — Removed `send` prefix: `openLink()` and `teardownResource()`. Deprecated aliases maintained by @ochafik in [#161](https://github.com/modelcontextprotocol/ext-apps/pull/161)
+- **Optional Client in AppBridge** — Enables custom forwarding scenarios without direct MCP client access by @ochafik in [#146](https://github.com/modelcontextprotocol/ext-apps/pull/146)
+- **Zod v3 and v4 support** — Bring your own Zod by @alpic-ai in [#49](https://github.com/modelcontextprotocol/ext-apps/pull/49)
+- **Zod schemas now version-agnostic** — Generated schemas work with both Zod 3.25+ and v4, using `z.object().passthrough()` instead of v4-only `z.looseObject()` by @ochafik in [#178](https://github.com/modelcontextprotocol/ext-apps/pull/178)
+
+### Platform & DX
+
+- **Windows compatibility** — Bun as optional dependency with automatic setup, `cross-env` for examples. Just run `npm install` by @ochafik in [#145](https://github.com/modelcontextprotocol/ext-apps/pull/145)
+- **Widened `@oven/bun-*` version range** — Lowered the minimum from `^1.3.4` to `^1.2.21`, helping contributors whose registries may not have the latest packages by @ochafik in [#176](https://github.com/modelcontextprotocol/ext-apps/pull/176)
+- **SSE transport support** — All examples now support both stdio and HTTP transports with SSE endpoints for older clients by @ochafik in [#136](https://github.com/modelcontextprotocol/ext-apps/pull/136)
+- **Playwright E2E tests** — Screenshot golden testing across all 9 example servers with parallel execution (~28s) by @ochafik in [#115](https://github.com/modelcontextprotocol/ext-apps/pull/115)
+- **hostContext exposure** — Access `hostContext` directly from the `App` class by @ochafik in [#139](https://github.com/modelcontextprotocol/ext-apps/pull/139)
+
+### Bug Fixes
+
+- **Responsive UIs** — Fixed narrow viewport handling for mobile and sidebar experiences by @ochafik in [#135](https://github.com/modelcontextprotocol/ext-apps/pull/135)
+- **Sandbox notification fix** — Fixed `sandbox-ready` notification name to match implementation by @ochafik in [#160](https://github.com/modelcontextprotocol/ext-apps/pull/160)
+- **Fixed non-UI tool registration** — Use `server.registerTool` for tools without UI and fix missing imports across examples by @ochafik in [#173](https://github.com/modelcontextprotocol/ext-apps/pull/173)
+
+**Full Changelog**: https://github.com/modelcontextprotocol/ext-apps/compare/v0.1.1...v0.2.2

build.bun.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+import { $ } from "bun";
+
+// Run TypeScript compiler for type declarations
+await $`tsc`;
+
+const isDevelopment = Bun.env.NODE_ENV === "development";
+
+// Build all JavaScript/TypeScript files
+function buildJs(
+  entrypoint: string,
+  opts: Partial<Parameters<(typeof Bun)["build"]>[0]> = {},
+) {
+  return Bun.build({
+    entrypoints: [entrypoint],
+    outdir: "dist",
+    target: "browser",
+    minify: !isDevelopment,
+    ...(isDevelopment
+      ? {
+          sourcemap: "inline",
+        }
+      : {}),
+    ...opts,
+  });
+}
+
+await Promise.all([
+  buildJs("src/app.ts", {
+    outdir: "dist/src",
+    external: ["@modelcontextprotocol/sdk"],
+  }),
+  buildJs("src/app.ts", {
+    outdir: "dist/src",
+    naming: { entry: "app-with-deps.js" },
+  }),
+  buildJs("src/app-bridge.ts", {
+    outdir: "dist/src",
+    external: ["@modelcontextprotocol/sdk"],
+  }),
+  buildJs("src/react/index.tsx", {
+    outdir: "dist/src/react",
+    external: ["react", "react-dom", "@modelcontextprotocol/sdk"],
+  }),
+  buildJs("src/react/index.tsx", {
+    outdir: "dist/src/react",
+    external: ["react", "react-dom", "@modelcontextprotocol/sdk"],
+    naming: { entry: "react-with-deps.js" },
+  }),
+  buildJs("src/server/index.ts", {
+    outdir: "dist/src/server",
+    external: ["@modelcontextprotocol/sdk"],
+  }),
+]);

docs/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="refresh" content="0; url=api/">
+  <title>Redirecting...</title>
+</head>
+<body>
+  <p>Redirecting to <a href="api/">API Documentation</a>...</p>
+  <script>window.location.href = 'api/';</script>
+</body>
+</html>

docs/migrate_from_openai_apps.md

@@ -0,0 +1,351 @@
+# Migrating from OpenAI Apps SDK to MCP Apps SDK
+
+This guide helps you migrate from the OpenAI Apps SDK to the MCP Apps SDK (`@modelcontextprotocol/ext-apps`).
+
+## Server-Side
+
+### Quick Start Comparison
+
+| OpenAI Apps SDK                                            | MCP Apps SDK                                                   |
+| ---------------------------------------------------------- | -------------------------------------------------------------- |
+| Flat metadata keys (`_meta["openai/..."]`)                 | Nested metadata structure (`_meta.ui.*`)                       |
+| Direct `server.registerTool()`/`server.registerResource()` | Helper functions: `registerAppTool()`, `registerAppResource()` |
+| UI Resource MIME type: `text/html+skybridge`               | UI Resource MIME type: `text/html;profile=mcp-app`             |
+
+### Tool Metadata
+
+| OpenAI                                         | MCP Apps                           | Notes                                                       |
+| ---------------------------------------------- | ---------------------------------- | ----------------------------------------------------------- |
+| `_meta["openai/outputTemplate"]`               | `_meta.ui.resourceUri`             | URI of UI resource                                          |
+| `_meta["openai/toolInvocation/invoking"]`      | —                                  | Not yet implemented                                         |
+| `_meta["openai/toolInvocation/invoked"]`       | —                                  | Not yet implemented                                         |
+| `_meta["openai/widgetAccessible"]` (`boolean`) | `_meta.ui.visibility` (`string[]`) | `true`/`false` → include/exclude `"app"` in array           |
+| `_meta["openai/visibility"]` (`string`)        | `_meta.ui.visibility` (`string[]`) | `"public"`/`"private"` → include/exclude `"model"` in array |
+
+### Resource Metadata
+
+| OpenAI                                | MCP Apps                 | Notes                                                                              |
+| ------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------- |
+| `_meta["openai/widgetCSP"]`           | `_meta.ui.csp`           | `connect_domains` → `connectDomains`, `resource_domains` → `resourceDomains`, etc. |
+| —                                     | `_meta.ui.permissions`   | MCP adds: permissions for camera, microphone, geolocation, clipboard               |
+| `_meta["openai/widgetDomain"]`        | `_meta.ui.domain`        | Dedicated sandbox origin                                                           |
+| `_meta["openai/widgetPrefersBorder"]` | `_meta.ui.prefersBorder` | Visual boundary preference                                                         |
+| `_meta["openai/widgetDescription"]`   | —                        | Not yet implemented; use `app.updateModelContext()` for dynamic context            |
+
+### Resource MIME Type
+
+| OpenAI                | MCP Apps                    | Notes                                                                            |
+| --------------------- | --------------------------- | -------------------------------------------------------------------------------- |
+| `text/html+skybridge` | `text/html;profile=mcp-app` | Auto-set by `registerAppResource()`; use `RESOURCE_MIME_TYPE` constant if manual |
+
+### Server-Side Migration Example
+
+### Before (OpenAI)
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+function createServer() {
+  const server = new McpServer({ name: "shop", version: "1.0.0" });
+
+  // Register tool with OpenAI metadata
+  server.registerTool(
+    "shopping-cart",
+    {
+      title: "Shopping Cart",
+      description: "Display the user's shopping cart",
+      inputSchema: { userId: z.string() },
+      annotations: { readOnlyHint: true },
+      _meta: {
+        "openai/outputTemplate": "ui://widget/cart.html",
+        "openai/toolInvocation/invoking": "Loading cart...",
+        "openai/toolInvocation/invoked": "Cart ready",
+        "openai/widgetAccessible": true,
+      },
+    },
+    async (args) => {
+      const cart = await getCart(args.userId);
+      return {
+        content: [{ type: "text", text: JSON.stringify(cart) }],
+        structuredContent: { cart },
+      };
+    },
+  );
+
+  // Register UI resource
+  server.registerResource(
+    "Cart Widget",
+    "ui://widget/cart.html",
+    { mimeType: "text/html+skybridge" },
+    async () => ({
+      contents: [
+        {
+          uri: "ui://widget/cart.html",
+          mimeType: "text/html+skybridge",
+          text: getCartHtml(),
+        },
+      ],
+    }),
+  );
+
+  return server;
+}
+```
+
+### After (MCP Apps)
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  registerAppTool,
+  registerAppResource,
+  RESOURCE_MIME_TYPE,
+} from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+
+function createServer() {
+  const server = new McpServer({ name: "shop", version: "1.0.0" });
+
+  // Register tool with MCP Apps metadata
+  registerAppTool(
+    server,
+    "shopping-cart",
+    {
+      title: "Shopping Cart",
+      description: "Display the user's shopping cart",
+      inputSchema: { userId: z.string() },
+      annotations: { readOnlyHint: true },
+      _meta: { ui: { resourceUri: "ui://widget/cart.html" } },
+    },
+    async (args) => {
+      const cart = await getCart(args.userId);
+      return {
+        content: [{ type: "text", text: JSON.stringify(cart) }],
+        structuredContent: { cart },
+      };
+    },
+  );
+
+  // Register UI resource
+  registerAppResource(
+    server,
+    "Cart Widget",
+    "ui://widget/cart.html",
+    { description: "Shopping cart UI" },
+    async () => ({
+      contents: [
+        {
+          uri: "ui://widget/cart.html",
+          mimeType: RESOURCE_MIME_TYPE,
+          text: getCartHtml(),
+        },
+      ],
+    }),
+  );
+
+  return server;
+}
+```
+
+### Key Differences Summary
+
+1. **Metadata Structure**: OpenAI uses flat `_meta["openai/..."]` properties; MCP uses nested `_meta.ui.*` structure
+2. **Tool Visibility**: OpenAI uses boolean/string (`true`/`"public"`); MCP uses string arrays (`["app", "model"]`)
+3. **CSP Property Names**: snake_case → camelCase (`connect_domains` → `connectDomains`)
+4. **App Permissions**: MCP adds `_meta.ui.permissions` for camera, microphone, geolocation, clipboard (not in OpenAI)
+5. **Resource MIME Type**: `text/html+skybridge` → `text/html;profile=mcp-app` (use `RESOURCE_MIME_TYPE` constant)
+6. **Helper Functions**: MCP provides `registerAppTool()` and `registerAppResource()` helpers
+7. **Not Yet Implemented**: `_meta["openai/toolInvocation/invoking"]`, `_meta["openai/toolInvocation/invoked"]`, and `_meta["openai/widgetDescription"]` don't have MCP equivalents yet
+
+## Client-side
+
+### Quick Start Comparison
+
+| OpenAI Apps SDK                   | MCP Apps SDK                       |
+| --------------------------------- | ---------------------------------- |
+| Implicit global (`window.openai`) | Explicit instance (`new App(...)`) |
+| Properties pre-populated on load  | Async connection + notifications   |
+| Sync property access              | Getters + event handlers           |
+
+### Setup & Connection
+
+| OpenAI                           | MCP Apps                                           | Notes                                                                                                           |
+| -------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `window.openai` (auto-available) | `const app = new App({name, version}, {})`         | MCP requires explicit instantiation                                                                             |
+| (implicit)                       | Vanilla: `await app.connect()` / React: `useApp()` | MCP requires async connection; auto-detects OpenAI env                                                          |
+| —                                | `await app.connect(new OpenAITransport())`         | Force OpenAI mode (not yet available, see [PR #172](https://github.com/modelcontextprotocol/ext-apps/pull/172)) |
+| —                                | `await app.connect(new PostMessageTransport(...))` | Force MCP mode explicitly                                                                                       |
+
+### Host Context Properties
+
+| OpenAI                      | MCP Apps                                      | Notes                                   |
+| --------------------------- | --------------------------------------------- | --------------------------------------- |
+| `window.openai.theme`       | `app.getHostContext()?.theme`                 | `"light"` \| `"dark"`                   |
+| `window.openai.locale`      | `app.getHostContext()?.locale`                | BCP 47 language tag (e.g., `"en-US"`)   |
+| `window.openai.displayMode` | `app.getHostContext()?.displayMode`           | `"inline"` \| `"pip"` \| `"fullscreen"` |
+| `window.openai.maxHeight`   | `app.getHostContext()?.viewport?.maxHeight`   | Max container height in px              |
+| `window.openai.safeArea`    | `app.getHostContext()?.safeAreaInsets`        | `{ top, right, bottom, left }`          |
+| `window.openai.userAgent`   | `app.getHostContext()?.userAgent`             | Host user agent string                  |
+| —                           | `app.getHostContext()?.availableDisplayModes` | MCP adds: which modes host supports     |
+| —                           | `app.getHostContext()?.toolInfo`              | MCP adds: tool metadata during call     |
+
+### Tool Data (Input/Output)
+
+| OpenAI                               | MCP Apps                                                      | Notes                               |
+| ------------------------------------ | ------------------------------------------------------------- | ----------------------------------- |
+| `window.openai.toolInput`            | `app.ontoolinput = (params) => { params.arguments }`          | Tool arguments; MCP uses callback   |
+| `window.openai.toolOutput`           | `app.ontoolresult = (params) => { params.structuredContent }` | Tool result; MCP uses callback      |
+| `window.openai.toolResponseMetadata` | `app.ontoolresult` → `params._meta`                           | Widget-only metadata from server    |
+| —                                    | `app.ontoolinputpartial = (params) => {...}`                  | MCP adds: streaming partial args    |
+| —                                    | `app.ontoolcancelled = (params) => {...}`                     | MCP adds: cancellation notification |
+
+### Calling Tools
+
+| OpenAI                                     | MCP Apps                                              | Notes                        |
+| ------------------------------------------ | ----------------------------------------------------- | ---------------------------- |
+| `await window.openai.callTool(name, args)` | `await app.callServerTool({ name, arguments: args })` | Call another MCP server tool |
+
+### Sending Messages
+
+| OpenAI                                                | MCP Apps                                                                             | Notes                             |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------- |
+| `await window.openai.sendFollowUpMessage({ prompt })` | `await app.sendMessage({ role: "user", content: [{ type: "text", text: prompt }] })` | MCP uses structured content array |
+
+### External Links
+
+| OpenAI                                       | MCP Apps                            | Notes                                |
+| -------------------------------------------- | ----------------------------------- | ------------------------------------ |
+| `await window.openai.openExternal({ href })` | `await app.openLink({ url: href })` | Different param name: `href` → `url` |
+
+### Display Mode
+
+| OpenAI                                             | MCP Apps                                                  | Notes                               |
+| -------------------------------------------------- | --------------------------------------------------------- | ----------------------------------- |
+| `await window.openai.requestDisplayMode({ mode })` | `await app.requestDisplayMode({ mode })`                  | Same API                            |
+| —                                                  | Check `app.getHostContext()?.availableDisplayModes` first | MCP lets you check what's available |
+
+### Size Reporting
+
+| OpenAI                                        | MCP Apps                                                             | Notes                                 |
+| --------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------- |
+| `window.openai.notifyIntrinsicHeight(height)` | `app.sendSizeChanged({ width, height })`                             | MCP includes width                    |
+| Manual only                                   | `new App(appInfo, capabilities, { autoResize: true /* default */ })` | MCP auto-reports via `ResizeObserver` |
+
+### State Persistence
+
+| OpenAI                                | MCP Apps | Notes                                                                |
+| ------------------------------------- | -------- | -------------------------------------------------------------------- |
+| `window.openai.widgetState`           | —        | Not directly available in MCP                                        |
+| `window.openai.setWidgetState(state)` | —        | Use alternative mechanisms (`localStorage`, server-side state, etc.) |
+
+### File Operations (Not Yet in MCP Apps)
+
+| OpenAI                                               | MCP Apps | Notes               |
+| ---------------------------------------------------- | -------- | ------------------- |
+| `await window.openai.uploadFile(file)`               | —        | Not yet implemented |
+| `await window.openai.getFileDownloadUrl({ fileId })` | —        | Not yet implemented |
+
+### Other (Not Yet in MCP Apps)
+
+| OpenAI                                      | MCP Apps | Notes               |
+| ------------------------------------------- | -------- | ------------------- |
+| `await window.openai.requestModal(options)` | —        | Not yet implemented |
+| `window.openai.requestClose()`              | —        | Not yet implemented |
+| `window.openai.view`                        | —        | Not yet mapped      |
+
+### Event Handling
+
+| OpenAI                         | MCP Apps                                    | Notes                            |
+| ------------------------------ | ------------------------------------------- | -------------------------------- |
+| Read `window.openai.*` on load | `app.ontoolinput = (params) => {...}`       | Register before `connect()`      |
+| Read `window.openai.*` on load | `app.ontoolresult = (params) => {...}`      | Register before `connect()`      |
+| Poll or re-read properties     | `app.onhostcontextchanged = (ctx) => {...}` | MCP pushes context changes       |
+| —                              | `app.onteardown = async () => {...}`        | MCP adds: cleanup before unmount |
+
+### Logging
+
+| OpenAI             | MCP Apps                                      | Notes                           |
+| ------------------ | --------------------------------------------- | ------------------------------- |
+| `console.log(...)` | `app.sendLog({ level: "info", data: "..." })` | MCP provides structured logging |
+
+### Host Info
+
+| OpenAI | MCP Apps                    | Notes                                             |
+| ------ | --------------------------- | ------------------------------------------------- |
+| —      | `app.getHostVersion()`      | Returns `{ name, version }` of host               |
+| —      | `app.getHostCapabilities()` | Check `serverTools`, `openLinks`, `logging`, etc. |
+
+### Full Migration Example
+
+#### Before (OpenAI)
+
+```typescript
+// OpenAI Apps SDK
+applyTheme(window.openai.theme);
+console.log("Tool args:", window.openai.toolInput);
+console.log("Tool result:", window.openai.toolOutput);
+
+// Call a tool
+const result = await window.openai.callTool("get_weather", { city: "Tokyo" });
+
+// Send a message
+await window.openai.sendFollowUpMessage({ prompt: "Weather updated!" });
+
+// Report height
+window.openai.notifyIntrinsicHeight(400);
+
+// Open link
+await window.openai.openExternal({ href: "https://example.com" });
+```
+
+#### After (MCP Apps)
+
+```typescript
+import { App } from "@modelcontextprotocol/ext-apps";
+
+const app = new App({ name: "MyApp", version: "1.0.0" });
+
+// Register handlers BEFORE connect (events may occur immediately after connect)
+app.ontoolinput = (params) => {
+  console.log("Tool args:", params.arguments);
+};
+
+app.ontoolresult = (params) => {
+  console.log("Tool result:", params.structuredContent);
+};
+
+app.onhostcontextchanged = (ctx) => {
+  if (ctx.theme) applyTheme(ctx.theme);
+};
+
+// Connect (auto-detects OpenAI vs MCP)
+await app.connect();
+
+// Access context
+applyTheme(app.getHostContext()?.theme);
+
+// Call a tool
+const result = await app.callServerTool({
+  name: "get_weather",
+  arguments: { city: "Tokyo" },
+});
+
+// Send a message
+await app.sendMessage({
+  role: "user",
+  content: [{ type: "text", text: "Weather updated!" }],
+});
+
+// Open link (note: url not href)
+await app.openLink({ url: "https://example.com" });
+```
+
+### Key Differences Summary
+
+1. **Initialization**: OpenAI is implicit; MCP requires `new App()` + `await app.connect()`
+2. **Data Flow**: OpenAI pre-populates; MCP uses async notifications (register handlers before `connect()`)
+3. **Auto-resize**: MCP has built-in ResizeObserver support via `autoResize` option
+4. **Structured Content**: MCP uses `{ type: "text", text: "..." }` arrays for messages
+5. **Context Changes**: MCP pushes updates via `onhostcontextchanged`; no polling needed
+6. **Capabilities**: MCP lets you check what the host supports before calling methods

docs/quickstart.md

@@ -0,0 +1,292 @@
+---
+title: Quickstart
+---
+
+# Build Your First MCP App
+
+This tutorial walks you through building an MCP App—a tool with an interactive UI that renders inside MCP hosts like Claude Desktop.
+
+## What You'll Build
+
+A simple app that fetches the current server time and displays it in a clickable UI. You'll learn the core pattern: **MCP Apps = Tool + UI Resource**.
+
+> [!NOTE]
+> The complete example is available at [`examples/basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs).
+
+## Prerequisites
+
+- Familiarity with MCP concepts, especially [Tools](https://modelcontextprotocol.io/docs/learn/server-concepts#tools) and [Resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources)
+- Familiarity with the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- Node.js 18+
+
+> [!TIP]
+> New to building MCP servers? Start with the [official MCP quickstart guide](https://modelcontextprotocol.io/docs/develop/build-server) to learn the core concepts first.
+
+## 1. Project Setup
+
+Create a new directory and initialize:
+
+```bash
+mkdir my-mcp-app && cd my-mcp-app
+npm init -y
+```
+
+Install dependencies:
+
+```bash
+npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk
+npm install -D typescript vite vite-plugin-singlefile express cors @types/express @types/cors tsx
+```
+
+Create `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["*.ts", "src/**/*.ts"]
+}
+```
+
+Create `vite.config.ts` — this bundles your UI into a single HTML file:
+
+```typescript
+import { defineConfig } from "vite";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+export default defineConfig({
+  plugins: [viteSingleFile()],
+  build: {
+    outDir: "dist",
+    rollupOptions: {
+      input: process.env.INPUT,
+    },
+  },
+});
+```
+
+Add to your `package.json`:
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "build": "INPUT=mcp-app.html vite build",
+    "serve": "npx tsx server.ts"
+  }
+}
+```
+
+> [!NOTE]
+> **Full files:** [`package.json`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/package.json), [`tsconfig.json`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/tsconfig.json), [`vite.config.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/vite.config.ts)
+
+## 2. Create the Server
+
+MCP Apps use a **two-part registration**:
+
+1. A **tool** that the LLM/host calls
+2. A **resource** that serves the UI HTML
+
+The tool's `_meta` field links them together.
+
+Create `server.ts`:
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  registerAppTool,
+  registerAppResource,
+  RESOURCE_MIME_TYPE,
+} from "@modelcontextprotocol/ext-apps/server";
+import cors from "cors";
+import express from "express";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const server = new McpServer({
+  name: "My MCP App Server",
+  version: "1.0.0",
+});
+
+// Two-part registration: tool + resource, tied together by the resource URI.
+const resourceUri = "ui://get-time/mcp-app.html";
+
+// Register a tool with UI metadata. When the host calls this tool, it reads
+// `_meta.ui.resourceUri` to know which resource to fetch and render as an
+// interactive UI.
+registerAppTool(
+  server,
+  "get-time",
+  {
+    title: "Get Time",
+    description: "Returns the current server time.",
+    inputSchema: {},
+    _meta: { ui: { resourceUri } },
+  },
+  async () => {
+    const time = new Date().toISOString();
+    return {
+      content: [{ type: "text", text: time }],
+    };
+  },
+);
+
+// Register the resource, which returns the bundled HTML/JavaScript for the UI.
+registerAppResource(
+  server,
+  resourceUri,
+  resourceUri,
+  { mimeType: RESOURCE_MIME_TYPE },
+  async () => {
+    const html = await fs.readFile(
+      path.join(import.meta.dirname, "dist", "mcp-app.html"),
+      "utf-8",
+    );
+    return {
+      contents: [
+        { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+      ],
+    };
+  },
+);
+
+// Start an Express server that exposes the MCP endpoint.
+const expressApp = express();
+expressApp.use(cors());
+expressApp.use(express.json());
+
+expressApp.post("/mcp", async (req, res) => {
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true,
+  });
+  res.on("close", () => transport.close());
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+});
+
+expressApp.listen(3001, (err) => {
+  if (err) {
+    console.error("Error starting server:", err);
+    process.exit(1);
+  }
+  console.log("Server listening on http://localhost:3001/mcp");
+});
+```
+
+> [!NOTE]
+> **Full file:** [`server.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/server.ts)
+
+Then, verify your server compiles:
+
+```bash
+npx tsc --noEmit
+```
+
+No output means success. If you see errors, check for typos in `server.ts`.
+
+## 3. Build the UI
+
+Create `mcp-app.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Get Time App</title>
+  </head>
+  <body>
+    <p>
+      <strong>Server Time:</strong> <code id="server-time">Loading...</code>
+    </p>
+    <button id="get-time-btn">Get Server Time</button>
+    <script type="module" src="/src/mcp-app.ts"></script>
+  </body>
+</html>
+```
+
+Create `src/mcp-app.ts`:
+
+```typescript
+import { App } from "@modelcontextprotocol/ext-apps";
+
+// Get element references
+const serverTimeEl = document.getElementById("server-time")!;
+const getTimeBtn = document.getElementById("get-time-btn")!;
+
+// Create app instance
+const app = new App({ name: "Get Time App", version: "1.0.0" });
+
+// Register handlers BEFORE connecting
+app.ontoolresult = (result) => {
+  const time = result.content?.find((c) => c.type === "text")?.text;
+  serverTimeEl.textContent = time ?? "[ERROR]";
+};
+
+// Wire up button click
+getTimeBtn.addEventListener("click", async () => {
+  const result = await app.callServerTool({ name: "get-time", arguments: {} });
+  const time = result.content?.find((c) => c.type === "text")?.text;
+  serverTimeEl.textContent = time ?? "[ERROR]";
+});
+
+// Connect to host
+app.connect();
+```
+
+> [!NOTE]
+> **Full files:** [`mcp-app.html`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/mcp-app.html), [`src/mcp-app.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/src/mcp-app.ts)
+
+Build the UI:
+
+```bash
+npm run build
+```
+
+This produces `dist/mcp-app.html` which contains your bundled app:
+
+```console
+$ ls dist/mcp-app.html
+dist/mcp-app.html
+```
+
+## 4. Test It
+
+You'll need two terminals.
+
+**Terminal 1** — Build and start your server:
+
+```bash
+npm run build && npm run serve
+```
+
+**Terminal 2** — Run the test host (from the [ext-apps repo](https://github.com/modelcontextprotocol/ext-apps)):
+
+```bash
+git clone https://github.com/modelcontextprotocol/ext-apps.git
+cd ext-apps/examples/basic-host
+npm install
+npm run start
+```
+
+Open http://localhost:8080 in your browser:
+
+1. Select **get-time** from the "Tool Name" dropdown
+2. Click **Call Tool**
+3. Your UI renders in the sandbox below
+4. Click **Get Server Time** — the current time appears!
+
+## Next Steps
+
+- **Host communication**: Add [`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), and [`sendOpenLink()`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendopenlink) to interact with the host — see [`src/mcp-app.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/src/mcp-app.ts)
+- **React version**: Compare with [`basic-server-react`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) for a React-based UI
+- **API reference**: See the full [API documentation](https://modelcontextprotocol.github.io/ext-apps/api/)

examples/basic-host/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

examples/basic-host/README.md

@@ -0,0 +1,43 @@
+# Example: Basic Host
+
+A reference implementation showing how to build an MCP host application that connects to MCP servers and renders tool UIs in a secure sandbox.
+
+This basic host can also be used to test MCP Apps during local development.
+
+## Key Files
+
+- [`index.html`](index.html) / [`src/index.tsx`](src/index.tsx) - React UI host with tool selection, parameter input, and iframe management
+- [`sandbox.html`](sandbox.html) / [`src/sandbox.ts`](src/sandbox.ts) - Outer iframe proxy with security validation and bidirectional message relay
+- [`src/implementation.ts`](src/implementation.ts) - Core logic: server connection, tool calling, and AppBridge setup
+
+## Getting Started
+
+```bash
+npm install
+npm run start
+# Open http://localhost:8080
+```
+
+By default, the host application will try to connect to an MCP server at `http://localhost:3001/mcp`. You can configure this behavior by setting the `SERVERS` environment variable with a JSON array of server URLs:
+
+```bash
+SERVERS='["http://localhost:1234/mcp", "http://localhost:5678/mcp"]' npm run start
+```
+
+## Architecture
+
+This example uses a double-iframe sandbox pattern for secure UI isolation:
+
+```
+Host (port 8080)
+  └── Outer iframe (port 8081) - sandbox proxy
+        └── Inner iframe (srcdoc) - untrusted tool UI
+```
+
+**Why two iframes?**
+
+- The outer iframe runs on a separate origin (port 8081) preventing direct access to the host
+- The inner iframe receives HTML via `srcdoc` and is restricted by sandbox attributes
+- Messages flow through the outer iframe which validates and relays them bidirectionally
+
+This architecture ensures that even if tool UI code is malicious, it cannot access the host application's DOM, cookies, or JavaScript context.

examples/basic-host/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="color-scheme" content="light dark">
+    <title>MCP Apps Host</title>
+    <link rel="stylesheet" href="/src/global.css">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script src="/src/index.tsx" type="module"></script>
+  </body>
+</html>

examples/basic-host/package.json

@@ -0,0 +1,35 @@
+{
+  "homepage": "https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host",
+  "name": "@modelcontextprotocol/ext-apps-basic-host",
+  "version": "0.4.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc --noEmit && concurrently \"cross-env INPUT=index.html vite build\" \"cross-env INPUT=sandbox.html vite build\"",
+    "watch": "concurrently \"cross-env INPUT=index.html vite build --watch\" \"cross-env INPUT=sandbox.html vite build --watch\"",
+    "serve": "bun --watch serve.ts",
+    "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\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "../..",
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "concurrently": "^9.2.1",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "prettier": "^3.6.2",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}

examples/basic-host/sandbox.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="color-scheme" content="light dark">
+    <!-- CSP is set via HTTP headers by serve.ts (based on ?csp= query param).
+         The inner iframe inherits this CSP since we use document.write(). -->
+    <title>MCP-UI Proxy</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        height: 100vh;
+        width: 100vw;
+      }
+      body {
+        display: flex;
+        flex-direction: column;
+      }
+      * {
+        box-sizing: border-box;
+      }
+      iframe {
+        background-color: transparent;
+        border: 0px none transparent;
+        padding: 0px;
+        overflow: hidden;
+        flex-grow: 1;
+      }
+    </style>
+  </head>
+  <body>
+    <script type="module" src="/src/sandbox.ts"></script>
+  </body>
+</html>

examples/basic-host/serve.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env npx tsx
+/**
+ * HTTP servers for the MCP UI example:
+ * - Host server (port 8080): serves host HTML files (React and Vanilla examples)
+ * - Sandbox server (port 8081): serves sandbox.html with CSP headers
+ *
+ * Running on separate ports ensures proper origin isolation for security.
+ *
+ * Security: CSP is set via HTTP headers based on ?csp= query param.
+ * This ensures content cannot tamper with CSP (unlike meta tags).
+ */
+
+import express from "express";
+import cors from "cors";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import type { McpUiResourceCsp } from "@modelcontextprotocol/ext-apps";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const HOST_PORT = parseInt(process.env.HOST_PORT || "8080", 10);
+const SANDBOX_PORT = parseInt(process.env.SANDBOX_PORT || "8081", 10);
+const DIRECTORY = join(__dirname, "dist");
+const SERVERS: string[] = process.env.SERVERS
+  ? JSON.parse(process.env.SERVERS)
+  : ["http://localhost:3001/mcp"];
+
+// ============ Host Server (port 8080) ============
+const hostApp = express();
+hostApp.use(cors());
+
+// Exclude sandbox.html from host server
+hostApp.use((req, res, next) => {
+  if (req.path === "/sandbox.html") {
+    res.status(404).send("Sandbox is served on a different port");
+    return;
+  }
+  next();
+});
+
+hostApp.use(express.static(DIRECTORY));
+
+// API endpoint to get configured server URLs
+hostApp.get("/api/servers", (_req, res) => {
+  res.json(SERVERS);
+});
+
+hostApp.get("/", (_req, res) => {
+  res.redirect("/index.html");
+});
+
+// ============ Sandbox Server (port 8081) ============
+const sandboxApp = express();
+sandboxApp.use(cors());
+
+// Validate CSP domain entries to prevent injection attacks.
+// Rejects entries containing characters that could:
+// - `;` or newlines: break out to new CSP directive
+// - quotes: inject CSP keywords like 'unsafe-eval'
+// - space: inject multiple sources in one entry
+function sanitizeCspDomains(domains?: string[]): string[] {
+  if (!domains) return [];
+  return domains.filter((d) => typeof d === "string" && !/[;\r\n'" ]/.test(d));
+}
+
+function buildCspHeader(csp?: McpUiResourceCsp): string {
+  const resourceDomains = sanitizeCspDomains(csp?.resourceDomains).join(" ");
+  const connectDomains = sanitizeCspDomains(csp?.connectDomains).join(" ");
+  const frameDomains = sanitizeCspDomains(csp?.frameDomains).join(" ") || null;
+  const baseUriDomains =
+    sanitizeCspDomains(csp?.baseUriDomains).join(" ") || null;
+
+  const directives = [
+    // Default: allow same-origin + inline styles/scripts (needed for bundled apps)
+    "default-src 'self' 'unsafe-inline'",
+    // Scripts: same-origin + inline + eval (some libs need eval) + blob (workers) + specified domains
+    `script-src 'self' 'unsafe-inline' 'unsafe-eval' blob: data: ${resourceDomains}`.trim(),
+    // Styles: same-origin + inline + specified domains
+    `style-src 'self' 'unsafe-inline' blob: data: ${resourceDomains}`.trim(),
+    // Images: same-origin + data/blob URIs + specified domains
+    `img-src 'self' data: blob: ${resourceDomains}`.trim(),
+    // Fonts: same-origin + data/blob URIs + specified domains
+    `font-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
+    // This is critical for WebGL apps (CesiumJS, Three.js) that use workers for:
+    // - Tile decoding and terrain processing
+    // - Image processing and texture loading
+    // - Physics and geometry calculations
+    `worker-src 'self' blob: ${resourceDomains}`.trim(),
+    // Nested iframes: use frameDomains if provided, otherwise block all
+    frameDomains ? `frame-src ${frameDomains}` : "frame-src 'none'",
+    // Plugins: always blocked (defense in depth)
+    "object-src 'none'",
+    // Base URI: use baseUriDomains if provided, otherwise block all
+    baseUriDomains ? `base-uri ${baseUriDomains}` : "base-uri 'none'",
+  ];
+
+  return directives.join("; ");
+}
+
+// Serve sandbox.html with CSP from query params
+sandboxApp.get(["/", "/sandbox.html"], (req, res) => {
+  // Parse CSP config from query param: ?csp=<url-encoded-json>
+  let cspConfig: McpUiResourceCsp | undefined;
+  if (typeof req.query.csp === "string") {
+    try {
+      cspConfig = JSON.parse(req.query.csp);
+    } catch (e) {
+      console.warn("[Sandbox] Invalid CSP query param:", e);
+    }
+  }
+
+  // Set CSP via HTTP header - tamper-proof unlike meta tags
+  const cspHeader = buildCspHeader(cspConfig);
+  res.setHeader("Content-Security-Policy", cspHeader);
+
+  // Prevent caching to ensure fresh CSP on each load
+  res.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
+  res.setHeader("Pragma", "no-cache");
+  res.setHeader("Expires", "0");
+
+  res.sendFile(join(DIRECTORY, "sandbox.html"));
+});
+
+sandboxApp.use((_req, res) => {
+  res.status(404).send("Only sandbox.html is served on this port");
+});
+
+// ============ Start both servers ============
+hostApp.listen(HOST_PORT, (err) => {
+  if (err) {
+    console.error("Error starting server:", err);
+    process.exit(1);
+  }
+  console.log(`Host server:    http://localhost:${HOST_PORT}`);
+});
+
+sandboxApp.listen(SANDBOX_PORT, (err) => {
+  if (err) {
+    console.error("Error starting server:", err);
+    process.exit(1);
+  }
+  console.log(`Sandbox server: http://localhost:${SANDBOX_PORT}`);
+  console.log("\nPress Ctrl+C to stop\n");
+});

examples/basic-host/src/global.css

@@ -0,0 +1,12 @@
+* {
+  box-sizing: border-box;
+}
+
+html, body {
+  font-family: system-ui, -apple-system, sans-serif;
+  font-size: 1rem;
+}
+
+code {
+  font-size: 1em;
+}

examples/basic-host/src/implementation.ts

@@ -0,0 +1,312 @@
+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 { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+
+
+const SANDBOX_PROXY_BASE_URL = "http://localhost:8081/sandbox.html";
+const IMPLEMENTATION = { name: "MCP Apps Host", version: "1.0.0" };
+
+
+export const log = {
+  info: console.log.bind(console, "[HOST]"),
+  warn: console.warn.bind(console, "[HOST]"),
+  error: console.error.bind(console, "[HOST]"),
+};
+
+
+export interface ServerInfo {
+  name: string;
+  client: Client;
+  tools: Map<string, Tool>;
+  appHtmlCache: Map<string, string>;
+}
+
+
+export async function connectToServer(serverUrl: URL): Promise<ServerInfo> {
+  const client = new Client(IMPLEMENTATION);
+
+  log.info("Connecting to server:", serverUrl.href);
+  await client.connect(new StreamableHTTPClientTransport(serverUrl));
+  log.info("Connection successful");
+
+  const name = client.getServerVersion()?.name ?? serverUrl.href;
+
+  const toolsList = await client.listTools();
+  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() };
+}
+
+
+interface UiResourceData {
+  html: string;
+  csp?: McpUiResourceCsp;
+  permissions?: McpUiResourcePermissions;
+}
+
+export interface ToolCallInfo {
+  serverInfo: ServerInfo;
+  tool: Tool;
+  input: Record<string, unknown>;
+  resultPromise: Promise<CallToolResult>;
+  appResourcePromise?: Promise<UiResourceData>;
+}
+
+
+export function hasAppHtml(toolCallInfo: ToolCallInfo): toolCallInfo is Required<ToolCallInfo> {
+  return !!toolCallInfo.appResourcePromise;
+}
+
+
+export function callTool(
+  serverInfo: ServerInfo,
+  name: string,
+  input: Record<string, unknown>,
+): ToolCallInfo {
+  log.info("Calling tool", name, "with input", input);
+  const resultPromise = serverInfo.client.callTool({ name, arguments: input }) as Promise<CallToolResult>;
+
+  const tool = serverInfo.tools.get(name);
+  if (!tool) {
+    throw new Error(`Unknown tool: ${name}`);
+  }
+
+  const toolCallInfo: ToolCallInfo = { serverInfo, tool, input, resultPromise };
+
+  const uiResourceUri = getToolUiResourceUri(tool);
+  if (uiResourceUri) {
+    toolCallInfo.appResourcePromise = getUiResource(serverInfo, uiResourceUri);
+  }
+
+  return toolCallInfo;
+}
+
+
+async function getUiResource(serverInfo: ServerInfo, uri: string): Promise<UiResourceData> {
+  log.info("Reading UI resource:", uri);
+  const resource = await serverInfo.client.readResource({ uri });
+
+  if (!resource) {
+    throw new Error(`Resource not found: ${uri}`);
+  }
+
+  if (resource.contents.length !== 1) {
+    throw new Error(`Unexpected contents count: ${resource.contents.length}`);
+  }
+
+  const content = resource.contents[0];
+
+  // Per the MCP App specification, "text/html;profile=mcp-app" signals this
+  // resource is indeed for an MCP App UI.
+  if (content.mimeType !== RESOURCE_MIME_TYPE) {
+    throw new Error(`Unsupported MIME type: ${content.mimeType}`);
+  }
+
+  const html = "blob" in content ? atob(content.blob) : content.text;
+
+  // Extract CSP and permissions metadata from resource content._meta.ui (or content.meta for Python SDK)
+  log.info("Resource content keys:", Object.keys(content));
+  log.info("Resource content._meta:", (content as any)._meta);
+
+  // Try both _meta (spec) and meta (Python SDK quirk)
+  const contentMeta = (content as any)._meta || (content as any).meta;
+  const csp = contentMeta?.ui?.csp;
+  const permissions = contentMeta?.ui?.permissions;
+
+  return { html, csp, permissions };
+}
+
+
+export function loadSandboxProxy(
+  iframe: HTMLIFrameElement,
+  csp?: McpUiResourceCsp,
+  permissions?: McpUiResourcePermissions,
+): Promise<boolean> {
+  // Prevent reload
+  if (iframe.src) return Promise.resolve(false);
+
+  iframe.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms");
+
+  // Set Permission Policy allow attribute based on requested permissions
+  const allowAttribute = buildAllowAttribute(permissions);
+  if (allowAttribute) {
+    iframe.setAttribute("allow", allowAttribute);
+  }
+
+  const readyNotification: McpUiSandboxProxyReadyNotification["method"] =
+    "ui/notifications/sandbox-proxy-ready";
+
+  const readyPromise = new Promise<boolean>((resolve) => {
+    const listener = ({ source, data }: MessageEvent) => {
+      if (source === iframe.contentWindow && data?.method === readyNotification) {
+        log.info("Sandbox proxy loaded")
+        window.removeEventListener("message", listener);
+        resolve(true);
+      }
+    };
+    window.addEventListener("message", listener);
+  });
+
+  // Build sandbox URL with CSP query param for HTTP header-based CSP
+  const sandboxUrl = new URL(SANDBOX_PROXY_BASE_URL);
+  if (csp) {
+    sandboxUrl.searchParams.set("csp", JSON.stringify(csp));
+  }
+
+  log.info("Loading sandbox proxy...", csp ? `(CSP: ${JSON.stringify(csp)})` : "");
+  iframe.src = sandboxUrl.href;
+
+  return readyPromise;
+}
+
+
+export async function initializeApp(
+  iframe: HTMLIFrameElement,
+  appBridge: AppBridge,
+  { input, resultPromise, appResourcePromise }: Required<ToolCallInfo>,
+): Promise<void> {
+  const appInitializedPromise = hookInitializedCallback(appBridge);
+
+  // Connect app bridge (triggers MCP initialization handshake)
+  //
+  // IMPORTANT: Pass `iframe.contentWindow` as BOTH target and source to ensure
+  // this proxy only responds to messages from its specific iframe.
+  await appBridge.connect(
+    new PostMessageTransport(iframe.contentWindow!, iframe.contentWindow!),
+  );
+
+  // Load inner iframe HTML with CSP and permissions metadata
+  const { html, csp, permissions } = await appResourcePromise;
+  log.info("Sending UI resource HTML to MCP App", csp ? `(CSP: ${JSON.stringify(csp)})` : "", permissions ? `(Permissions: ${JSON.stringify(permissions)})` : "");
+  await appBridge.sendSandboxResourceReady({ html, csp, permissions });
+
+  // Wait for inner iframe to be ready
+  log.info("Waiting for MCP App to initialize...");
+  await appInitializedPromise;
+  log.info("MCP App initialized");
+
+  // Send tool call input to iframe
+  log.info("Sending tool call input to MCP App:", input);
+  appBridge.sendToolInput({ arguments: input });
+
+  // Schedule tool call result (or cancellation) to be sent to MCP App
+  resultPromise.then(
+    (result) => {
+      log.info("Sending tool call result to MCP App:", result);
+      appBridge.sendToolResult(result);
+    },
+    (error) => {
+      log.error("Tool call failed, sending cancellation to MCP App:", error);
+      appBridge.sendToolCancelled({
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    },
+  );
+}
+
+/**
+ * Hooks into `AppBridge.oninitialized` and returns a Promise that resolves when
+ * the MCP App is initialized (i.e., when the inner iframe is ready).
+ */
+function hookInitializedCallback(appBridge: AppBridge): Promise<void> {
+  const oninitialized = appBridge.oninitialized;
+  return new Promise<void>((resolve) => {
+    appBridge.oninitialized = (...args) => {
+      resolve();
+      appBridge.oninitialized = oninitialized;
+      appBridge.oninitialized?.(...args);
+    };
+  });
+}
+
+
+export type ModelContext = McpUiUpdateModelContextRequest["params"];
+export type AppMessage = McpUiMessageRequest["params"];
+
+export interface AppBridgeCallbacks {
+  onContextUpdate?: (context: ModelContext | null) => void;
+  onMessage?: (message: AppMessage) => void;
+}
+
+export function newAppBridge(
+  serverInfo: ServerInfo,
+  iframe: HTMLIFrameElement,
+  callbacks?: AppBridgeCallbacks,
+): AppBridge {
+  const serverCapabilities = serverInfo.client.getServerCapabilities();
+  const appBridge = new AppBridge(serverInfo.client, IMPLEMENTATION, {
+    openLinks: {},
+    serverTools: serverCapabilities?.tools,
+    serverResources: serverCapabilities?.resources,
+    // Declare support for model context updates
+    updateModelContext: { text: {} },
+  });
+
+  // Register all handlers before calling connect(). The Guest UI can start
+  // sending requests immediately after the initialization handshake, so any
+  // handlers registered after connect() might miss early requests.
+
+  appBridge.onmessage = async (params, _extra) => {
+    log.info("Message from MCP App:", params);
+    callbacks?.onMessage?.(params);
+    return {};
+  };
+
+  appBridge.onopenlink = async (params, _extra) => {
+    log.info("Open link request:", params);
+    window.open(params.url, "_blank", "noopener,noreferrer");
+    return {};
+  };
+
+  appBridge.onloggingmessage = (params) => {
+    log.info("Log message from MCP App:", params);
+  };
+
+  appBridge.onupdatemodelcontext = async (params) => {
+    log.info("Model context update from MCP App:", params);
+    // Normalize: empty content array means clear context
+    const hasContent = params.content && params.content.length > 0;
+    const hasStructured = params.structuredContent && Object.keys(params.structuredContent).length > 0;
+    callbacks?.onContextUpdate?.(hasContent || hasStructured ? params : null);
+    return {};
+  };
+
+  appBridge.onsizechange = async ({ width, height }) => {
+    // The MCP App has requested a `width` and `height`, but if
+    // `box-sizing: border-box` is applied to the outer iframe element, then we
+    // must add border thickness to `width` and `height` to compute the actual
+    // necessary width and height (in order to prevent a resize feedback loop).
+    const style = getComputedStyle(iframe);
+    const isBorderBox = style.boxSizing === "border-box";
+
+    // Animate the change for a smooth transition.
+    const from: Keyframe = {};
+    const to: Keyframe = {};
+
+    if (width !== undefined) {
+      if (isBorderBox) {
+        width += parseFloat(style.borderLeftWidth) + parseFloat(style.borderRightWidth);
+      }
+      // Use min-width instead of width to allow responsive growing.
+      // With auto-resize (the default), the app reports its minimum content
+      // width; we honor that as a floor but allow the iframe to expand when
+      // the host layout allows. And we use `min(..., 100%)` so that the iframe
+      // shrinks with its container.
+      from.minWidth = `${iframe.offsetWidth}px`;
+      iframe.style.minWidth = to.minWidth = `min(${width}px, 100%)`;
+    }
+    if (height !== undefined) {
+      if (isBorderBox) {
+        height += parseFloat(style.borderTopWidth) + parseFloat(style.borderBottomWidth);
+      }
+      from.height = `${iframe.offsetHeight}px`;
+      iframe.style.height = to.height = `${height}px`;
+    }
+
+    iframe.animate([from, to], { duration: 300, easing: "ease-out" });
+  };
+
+  return appBridge;
+}

examples/basic-host/src/index.module.css

@@ -0,0 +1,255 @@
+.callToolPanel, .toolCallInfoPanel {
+  margin: 0 auto;
+  padding: 1rem;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+
+  * + & {
+    margin-top: 1rem;
+  }
+}
+
+.callToolPanel {
+  max-width: 480px;
+
+  form {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+  }
+
+  label {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    font-weight: 600;
+  }
+
+  select,
+  textarea {
+    padding: 0.5rem;
+    border: 1px solid #ccc;
+    border-radius: 4px;
+    font-size: inherit;
+  }
+
+  .toolSelect {
+    font-family: monospace;
+  }
+
+  .toolInput {
+    min-height: 6rem;
+    font-family: monospace;
+    resize: vertical;
+
+    &[aria-invalid="true"] {
+      background-color: #fdd;
+    }
+  }
+
+  button {
+    align-self: center;
+    min-width: 200px;
+    padding: 0.75rem 1.5rem;
+    border: none;
+    border-radius: 4px;
+    background-color: #1e3a5f;
+    font-size: inherit;
+    font-weight: 600;
+    color: white;
+    cursor: pointer;
+
+    &:hover:not(:disabled) {
+      background-color: #2d4a7c;
+    }
+
+    &:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+  }
+}
+
+.toolCallInfoPanel {
+  display: flex;
+  gap: 1rem;
+  animation: slideDown 0.3s ease-out;
+}
+
+@keyframes slideDown {
+  from { opacity: 0; transform: translateY(-12px); }
+}
+
+.inputInfoPanel {
+  display: flex;
+  flex: 3;
+  flex-direction: column;
+  gap: 0.5rem;
+  min-width: 0;
+
+  h2 {
+    display: flex;
+    flex-direction: column;
+    margin: 0;
+    font-size: 1.5rem;
+    position: relative;
+
+    .toolName {
+      font-family: monospace;
+    }
+
+    .closeButton {
+      position: absolute;
+      top: 0;
+      right: 0;
+      width: 1.5rem;
+      height: 1.5rem;
+      padding: 0;
+      border: none;
+      border-radius: 4px;
+      background: #e0e0e0;
+      font-size: 1.25rem;
+      line-height: 1;
+      color: #666;
+      cursor: pointer;
+
+      &:hover {
+        background: #d0d0d0;
+        color: #333;
+      }
+    }
+  }
+}
+
+.outputInfoPanel {
+  flex: 4;
+  min-width: 0;
+}
+
+.appOutputPanel {
+  flex: 1;
+  min-width: 0;
+}
+
+.appHeader {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+  font-size: 1.25rem;
+  font-weight: 600;
+  position: relative;
+
+  .toolName {
+    font-family: monospace;
+  }
+
+  .closeButton {
+    position: absolute;
+    top: 0;
+    right: 0;
+    width: 1.5rem;
+    height: 1.5rem;
+    padding: 0;
+    border: none;
+    border-radius: 4px;
+    background: #e0e0e0;
+    font-size: 1.25rem;
+    line-height: 1;
+    color: #666;
+    cursor: pointer;
+
+    &:hover {
+      background: #d0d0d0;
+      color: #333;
+    }
+  }
+}
+
+.jsonBlock {
+  flex-grow: 1;
+  min-height: 0;
+  margin: 0;
+  padding: 1rem;
+  border-radius: 4px;
+  background-color: #f5f5f5;
+  overflow: auto;
+}
+
+.appIframePanel {
+  min-height: 200px;
+
+  iframe {
+    width: 100%;
+    height: 600px;
+    box-sizing: border-box;
+    border: 3px dashed #888;
+    border-radius: 4px;
+  }
+}
+
+.collapsiblePanel {
+  margin: 0.5rem 0;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 4px;
+  background-color: #fafafa;
+  font-size: 0.875rem;
+  cursor: pointer;
+  transition: background-color 0.15s;
+
+  &:hover {
+    background-color: #f0f0f0;
+  }
+}
+
+.collapsibleHeader {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.collapsibleLabel {
+  font-weight: 600;
+  color: #555;
+}
+
+.collapsibleSize {
+  color: #888;
+  font-size: 0.75rem;
+}
+
+.collapsibleToggle {
+  margin-left: auto;
+  color: #888;
+  font-size: 0.75rem;
+}
+
+.collapsiblePreview {
+  margin-top: 0.25rem;
+  color: #666;
+  font-family: monospace;
+  font-size: 0.8rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.collapsibleFull {
+  margin: 0.5rem 0 0;
+  padding: 0.5rem;
+  border-radius: 4px;
+  background-color: #f5f5f5;
+  font-family: monospace;
+  font-size: 0.8rem;
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 200px;
+  overflow: auto;
+}
+
+.error {
+  padding: 1.5rem;
+  background-color: #ddd;
+  color: #d00;
+}

examples/basic-host/src/index.tsx

@@ -0,0 +1,530 @@
+import { getToolUiResourceUri, McpUiToolMetaSchema } from "@modelcontextprotocol/ext-apps/app-bridge";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+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";
+import styles from "./index.module.css";
+
+/**
+ * Check if a tool is visible to the model (not app-only).
+ * Tools with `visibility: ["app"]` should not be shown in tool lists.
+ */
+function isToolVisibleToModel(tool: { _meta?: Record<string, unknown> }): boolean {
+  const result = McpUiToolMetaSchema.safeParse(tool._meta?.ui);
+  if (!result.success) return true; // default: visible to model
+  const visibility = result.data.visibility;
+  if (!visibility) return true; // default: visible to model
+  return visibility.includes("model");
+}
+
+/** Compare tools: UI-enabled first, then alphabetically by name. */
+function compareTools(a: Tool, b: Tool): number {
+  const aHasUi = !!getToolUiResourceUri(a);
+  const bHasUi = !!getToolUiResourceUri(b);
+  if (aHasUi && !bHasUi) return -1;
+  if (!aHasUi && bHasUi) return 1;
+  return a.name.localeCompare(b.name);
+}
+
+/**
+ * Extract default values from a tool's JSON Schema inputSchema.
+ * Returns a formatted JSON string with defaults, or "{}" if none found.
+ */
+function getToolDefaults(tool: Tool | undefined): string {
+  if (!tool?.inputSchema?.properties) return "{}";
+
+  const defaults: Record<string, unknown> = {};
+  for (const [key, prop] of Object.entries(tool.inputSchema.properties)) {
+    if (prop && typeof prop === "object" && "default" in prop) {
+      defaults[key] = prop.default;
+    }
+  }
+
+  return Object.keys(defaults).length > 0
+    ? JSON.stringify(defaults, null, 2)
+    : "{}";
+}
+
+
+// Host passes serversPromise to CallToolPanel
+interface HostProps {
+  serversPromise: Promise<ServerInfo[]>;
+}
+
+type ToolCallEntry = ToolCallInfo & { id: number };
+let nextToolCallId = 0;
+
+function Host({ serversPromise }: HostProps) {
+  const [toolCalls, setToolCalls] = useState<ToolCallEntry[]>([]);
+  const [destroyingIds, setDestroyingIds] = useState<Set<number>>(new Set());
+
+  const requestClose = (id: number) => {
+    setDestroyingIds((s) => new Set(s).add(id));
+  };
+
+  const completeClose = (id: number) => {
+    setDestroyingIds((s) => {
+      const next = new Set(s);
+      next.delete(id);
+      return next;
+    });
+    setToolCalls((calls) => calls.filter((c) => c.id !== id));
+  };
+
+  return (
+    <>
+      {toolCalls.map((info) => (
+        <ToolCallInfoPanel
+          key={info.id}
+          toolCallInfo={info}
+          isDestroying={destroyingIds.has(info.id)}
+          onRequestClose={() => requestClose(info.id)}
+          onCloseComplete={() => completeClose(info.id)}
+        />
+      ))}
+      <CallToolPanel
+        serversPromise={serversPromise}
+        addToolCall={(info) => setToolCalls([...toolCalls, { ...info, id: nextToolCallId++ }])}
+      />
+    </>
+  );
+}
+
+
+// CallToolPanel renders the unified form with Suspense around ServerSelect
+interface CallToolPanelProps {
+  serversPromise: Promise<ServerInfo[]>;
+  addToolCall: (info: ToolCallInfo) => void;
+}
+function CallToolPanel({ serversPromise, addToolCall }: CallToolPanelProps) {
+  const [selectedServer, setSelectedServer] = useState<ServerInfo | null>(null);
+  const [selectedTool, setSelectedTool] = useState("");
+  const [inputJson, setInputJson] = useState("{}");
+
+  // Filter out app-only tools, prioritize tools with UIs
+  const toolNames = selectedServer
+    ? Array.from(selectedServer.tools.values())
+        .filter((tool) => isToolVisibleToModel(tool))
+        .sort(compareTools)
+        .map((tool) => tool.name)
+    : [];
+
+  const isValidJson = useMemo(() => {
+    try {
+      JSON.parse(inputJson);
+      return true;
+    } catch {
+      return false;
+    }
+  }, [inputJson]);
+
+  const handleServerSelect = (server: ServerInfo) => {
+    setSelectedServer(server);
+    // Filter out app-only tools, prioritize tools with UIs
+    const visibleTools = Array.from(server.tools.values())
+      .filter((tool) => isToolVisibleToModel(tool))
+      .sort(compareTools);
+    const firstTool = visibleTools[0]?.name ?? "";
+    setSelectedTool(firstTool);
+    // Set input JSON to tool defaults (if any)
+    setInputJson(getToolDefaults(server.tools.get(firstTool)));
+  };
+
+  const handleToolSelect = (toolName: string) => {
+    setSelectedTool(toolName);
+    // Set input JSON to tool defaults (if any)
+    setInputJson(getToolDefaults(selectedServer?.tools.get(toolName)));
+  };
+
+  const handleSubmit = () => {
+    if (!selectedServer) return;
+    const toolCallInfo = callTool(selectedServer, selectedTool, JSON.parse(inputJson));
+    addToolCall(toolCallInfo);
+  };
+
+  return (
+    <div className={styles.callToolPanel}>
+      <form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
+        <label>
+          Server
+          <Suspense fallback={<select disabled><option>Loading...</option></select>}>
+            <ServerSelect serversPromise={serversPromise} onSelect={handleServerSelect} />
+          </Suspense>
+        </label>
+        <label>
+          Tool
+          <select
+            className={styles.toolSelect}
+            value={selectedTool}
+            onChange={(e) => handleToolSelect(e.target.value)}
+          >
+            {selectedServer && toolNames.map((name) => (
+              <option key={name} value={name}>{name}</option>
+            ))}
+          </select>
+        </label>
+        <label>
+          Input
+          <textarea
+            className={styles.toolInput}
+            aria-invalid={!isValidJson}
+            value={inputJson}
+            onChange={(e) => setInputJson(e.target.value)}
+          />
+        </label>
+        <button type="submit" disabled={!selectedTool || !isValidJson}>
+          Call Tool
+        </button>
+      </form>
+    </div>
+  );
+}
+
+
+// ServerSelect calls use() and renders the server <select>
+interface ServerSelectProps {
+  serversPromise: Promise<ServerInfo[]>;
+  onSelect: (server: ServerInfo) => void;
+}
+function ServerSelect({ serversPromise, onSelect }: ServerSelectProps) {
+  const servers = use(serversPromise);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  useEffect(() => {
+    if (servers.length > selectedIndex) {
+      onSelect(servers[selectedIndex]);
+    }
+  }, [servers]);
+
+  if (servers.length === 0) {
+    return <select disabled><option>No servers configured</option></select>;
+  }
+
+  return (
+    <select
+      value={selectedIndex}
+      onChange={(e) => {
+        const newIndex = Number(e.target.value);
+        setSelectedIndex(newIndex);
+        onSelect(servers[newIndex]);
+      }}
+    >
+      {servers.map((server, i) => (
+        <option key={i} value={i}>{server.name}</option>
+      ))}
+    </select>
+  );
+}
+
+
+interface ToolCallInfoPanelProps {
+  toolCallInfo: ToolCallInfo;
+  isDestroying?: boolean;
+  onRequestClose?: () => void;
+  onCloseComplete?: () => void;
+}
+function ToolCallInfoPanel({ toolCallInfo, isDestroying, onRequestClose, onCloseComplete }: ToolCallInfoPanelProps) {
+  const isApp = hasAppHtml(toolCallInfo);
+
+  // For non-app tool calls, close immediately when isDestroying becomes true
+  useEffect(() => {
+    if (isDestroying && !isApp) {
+      onCloseComplete?.();
+    }
+  }, [isDestroying, isApp, onCloseComplete]);
+
+  return (
+    <div
+      className={styles.toolCallInfoPanel}
+      style={isDestroying ? { opacity: 0.5, pointerEvents: "none" } : undefined}
+    >
+      {/* For non-app tools, show input/output side by side */}
+      {!isApp && (
+        <div className={styles.inputInfoPanel}>
+          <h2>
+            <span>{toolCallInfo.serverInfo.name}</span>
+            <span className={styles.toolName}>{toolCallInfo.tool.name}</span>
+            {onRequestClose && !isDestroying && (
+              <button
+                className={styles.closeButton}
+                onClick={onRequestClose}
+                title="Close"
+              >
+                ×
+              </button>
+            )}
+          </h2>
+          <JsonBlock value={toolCallInfo.input} />
+        </div>
+      )}
+      <div className={isApp ? styles.appOutputPanel : styles.outputInfoPanel}>
+        {/* For apps, show header above the app: ServerName:tool_name */}
+        {isApp && (
+          <div className={styles.appHeader}>
+            <span>{toolCallInfo.serverInfo.name}:<span className={styles.toolName}>{toolCallInfo.tool.name}</span></span>
+            {onRequestClose && !isDestroying && (
+              <button
+                className={styles.closeButton}
+                onClick={onRequestClose}
+                title="Close"
+              >
+                ×
+              </button>
+            )}
+          </div>
+        )}
+        <ErrorBoundary>
+          <Suspense fallback="Loading...">
+            {
+              isApp
+                ? <AppIFramePanel
+                    toolCallInfo={toolCallInfo}
+                    isDestroying={isDestroying}
+                    onTeardownComplete={onCloseComplete}
+                  />
+                : <ToolResultPanel toolCallInfo={toolCallInfo} />
+            }
+          </Suspense>
+        </ErrorBoundary>
+      </div>
+    </div>
+  );
+}
+
+
+function JsonBlock({ value }: { value: object }) {
+  return (
+    <pre className={styles.jsonBlock}>
+      <code>{JSON.stringify(value, null, 2)}</code>
+    </pre>
+  );
+}
+
+
+interface CollapsiblePanelProps {
+  icon: string;
+  label: string;
+  content: string;
+  badge?: string;
+  defaultExpanded?: boolean;
+}
+function CollapsiblePanel({ icon, label, content, badge, defaultExpanded = false }: CollapsiblePanelProps) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+
+  return (
+    <div
+      className={styles.collapsiblePanel}
+      onClick={() => setExpanded(!expanded)}
+      title={expanded ? "Click to collapse" : "Click to expand"}
+    >
+      <div className={styles.collapsibleHeader}>
+        <span className={styles.collapsibleLabel}>{icon} {label}</span>
+        <span className={styles.collapsibleSize}>
+          {badge ?? `${content.length} chars`}
+        </span>
+        <span className={styles.collapsibleToggle}>
+          {expanded ? "▼" : "▶"}
+        </span>
+      </div>
+      {expanded ? (
+        <pre className={styles.collapsibleFull}>{content}</pre>
+      ) : (
+        <div className={styles.collapsiblePreview}>
+          {content.slice(0, 100)}{content.length > 100 ? "…" : ""}
+        </div>
+      )}
+    </div>
+  );
+}
+
+
+interface AppIFramePanelProps {
+  toolCallInfo: Required<ToolCallInfo>;
+  isDestroying?: boolean;
+  onTeardownComplete?: () => void;
+}
+function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppIFramePanelProps) {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const appBridgeRef = useRef<ReturnType<typeof newAppBridge> | null>(null);
+  const [modelContext, setModelContext] = useState<ModelContext | null>(null);
+  const [toolResult, setToolResult] = useState<object | null>(null);
+  const [messages, setMessages] = useState<AppMessage[]>([]);
+
+  useEffect(() => {
+    const iframe = iframeRef.current!;
+
+    // First get CSP and permissions from resource, then load sandbox
+    // CSP is set via HTTP headers (tamper-proof), permissions via iframe allow attribute
+    toolCallInfo.appResourcePromise.then(({ csp, permissions }) => {
+      loadSandboxProxy(iframe, csp, permissions).then((firstTime) => {
+        // The `firstTime` check guards against React Strict Mode's double
+        // invocation (mount → unmount → remount simulation in development).
+        // Outside of Strict Mode, this `useEffect` runs only once per
+        // `toolCallInfo`.
+        if (firstTime) {
+          const appBridge = newAppBridge(toolCallInfo.serverInfo, iframe, {
+            onContextUpdate: setModelContext,
+            onMessage: (msg) => setMessages((prev) => [...prev, msg]),
+          });
+          appBridgeRef.current = appBridge;
+          initializeApp(iframe, appBridge, toolCallInfo);
+        }
+      });
+    });
+
+    // Track tool result for display
+    toolCallInfo.resultPromise.then(setToolResult).catch(() => {});
+  }, [toolCallInfo]);
+
+  // Graceful teardown: wait for guest to respond before unmounting
+  // This follows the spec: "Host SHOULD wait for a response before tearing
+  // down the resource (to prevent data loss)."
+  useEffect(() => {
+    if (!isDestroying) return;
+
+    if (!appBridgeRef.current) {
+      // Bridge not ready yet (e.g., user closed before iframe loaded)
+      onTeardownComplete?.();
+      return;
+    }
+
+    log.info("Sending teardown notification to MCP App");
+    appBridgeRef.current.teardownResource({})
+      .catch((err) => {
+        log.warn("Teardown request failed (app may have already closed):", err);
+      })
+      .finally(() => {
+        onTeardownComplete?.();
+      });
+  }, [isDestroying, onTeardownComplete]);
+
+  // Format content blocks - handle text, images, resources, etc.
+  const formatContentBlock = (c: { type: string; [key: string]: unknown }) => {
+    switch (c.type) {
+      case "text":
+        return (c as { type: "text"; text: string }).text;
+      case "image":
+        return `<image: ${(c as { mimeType?: string }).mimeType ?? "unknown"}>`;
+      case "audio":
+        return `<audio: ${(c as { mimeType?: string }).mimeType ?? "unknown"}>`;
+      case "resource":
+        return `<resource: ${(c as { resource?: { uri?: string } }).resource?.uri ?? "unknown"}>`;
+      default:
+        return `<${c.type}>`;
+    }
+  };
+
+  // Format context for display
+  const contextText = modelContext?.content?.map(formatContentBlock).join("\n") ?? "";
+  const contextJson = modelContext?.structuredContent
+    ? JSON.stringify(modelContext.structuredContent, null, 2)
+    : "";
+  const fullContext = [contextText, contextJson].filter(Boolean).join("\n\n");
+
+  const inputJson = JSON.stringify(toolCallInfo.input, null, 2);
+  const resultJson = toolResult ? JSON.stringify(toolResult, null, 2) : null;
+
+  // Format messages
+  const formatMessage = (m: AppMessage) => {
+    const content = m.content.map(formatContentBlock).join("\n");
+    return `[${m.role}] ${content}`;
+  };
+  const messagesText = messages.map(formatMessage).join("\n\n");
+
+  return (
+    <div className={styles.appIframePanel}>
+      <CollapsiblePanel icon="📥" label="Tool Input" content={inputJson} />
+      <iframe ref={iframeRef} />
+      {resultJson && (
+        <CollapsiblePanel icon="📤" label="Tool Result" content={resultJson} />
+      )}
+      {messages.length > 0 && (
+        <CollapsiblePanel
+          icon="💬"
+          label="Messages"
+          content={messagesText}
+          badge={`${messages.length} message${messages.length > 1 ? "s" : ""}`}
+        />
+      )}
+      {modelContext && (
+        <CollapsiblePanel icon="📋" label="Model Context" content={fullContext} />
+      )}
+    </div>
+  );
+}
+
+
+interface ToolResultPanelProps {
+  toolCallInfo: ToolCallInfo;
+}
+function ToolResultPanel({ toolCallInfo }: ToolResultPanelProps) {
+  const result = use(toolCallInfo.resultPromise);
+  return <JsonBlock value={result} />;
+}
+
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+}
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: unknown;
+}
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { hasError: false, error: undefined };
+
+  // Called during render phase - must be pure (no side effects)
+  // Note: error is `unknown` because JS allows throwing any value
+  static getDerivedStateFromError(error: unknown): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  // Called during commit phase - can have side effects (logging, etc.)
+  componentDidCatch(error: unknown, errorInfo: ErrorInfo): void {
+    log.error("Caught:", error, errorInfo.componentStack);
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      const { error } = this.state;
+      const message = error instanceof Error ? error.message : String(error);
+      return <div className={styles.error}><strong>ERROR:</strong> {message}</div>;
+    }
+    return this.props.children;
+  }
+}
+
+
+async function connectToAllServers(): Promise<ServerInfo[]> {
+  const serverUrlsResponse = await fetch("/api/servers");
+  const serverUrls = (await serverUrlsResponse.json()) as string[];
+
+  // Use allSettled to be resilient to individual server failures
+  const results = await Promise.allSettled(
+    serverUrls.map((url) => connectToServer(new URL(url)))
+  );
+
+  const servers: ServerInfo[] = [];
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    if (result.status === "fulfilled") {
+      servers.push(result.value);
+    } else {
+      console.warn(`[HOST] Failed to connect to ${serverUrls[i]}:`, result.reason);
+    }
+  }
+
+  if (servers.length === 0 && serverUrls.length > 0) {
+    throw new Error(`Failed to connect to any servers (${serverUrls.length} attempted)`);
+  }
+
+  return servers;
+}
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <ErrorBoundary>
+      <Host serversPromise={connectToAllServers()} />
+    </ErrorBoundary>
+  </StrictMode>,
+);

examples/basic-host/src/sandbox.ts

@@ -0,0 +1,137 @@
+import type { McpUiSandboxProxyReadyNotification, McpUiSandboxResourceReadyNotification } from "../../../dist/src/types";
+import { buildAllowAttribute } from "../../../dist/src/app-bridge";
+
+const ALLOWED_REFERRER_PATTERN = /^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/;
+
+if (window.self === window.top) {
+  throw new Error("This file is only to be used in an iframe sandbox.");
+}
+
+if (!document.referrer) {
+  throw new Error("No referrer, cannot validate embedding site.");
+}
+
+if (!document.referrer.match(ALLOWED_REFERRER_PATTERN)) {
+  throw new Error(
+    `Embedding domain not allowed in referrer ${document.referrer}. (Consider updating the validation logic to allow your domain.)`,
+  );
+}
+
+// Extract the expected host origin from the referrer for origin validation.
+// This is the origin we expect all parent messages to come from.
+const EXPECTED_HOST_ORIGIN = new URL(document.referrer).origin;
+
+const OWN_ORIGIN = new URL(window.location.href).origin;
+
+// Security self-test: verify iframe isolation is working correctly.
+// This MUST throw a SecurityError -- if `window.top` is accessible, the sandbox
+// configuration is dangerously broken and untrusted content could escape.
+try {
+  window.top!.alert("If you see this, the sandbox is not setup securely.");
+  throw "FAIL";
+} catch (e) {
+  if (e === "FAIL") {
+    throw new Error("The sandbox is not setup securely.");
+  }
+
+  // Expected: SecurityError confirms proper sandboxing.
+}
+
+// Double-iframe sandbox architecture: THIS file is the outer sandbox proxy
+// iframe on a separate origin. It creates an inner iframe for untrusted HTML
+// content. Per the specification, the Host and the Sandbox MUST have different
+// origins.
+const inner = document.createElement("iframe");
+inner.style = "width:100%; height:100%; border:none;";
+inner.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms");
+// Note: allow attribute is set later when receiving sandbox-resource-ready notification
+// based on the permissions requested by the app
+document.body.appendChild(inner);
+
+const RESOURCE_READY_NOTIFICATION: McpUiSandboxResourceReadyNotification["method"] =
+  "ui/notifications/sandbox-resource-ready";
+const PROXY_READY_NOTIFICATION: McpUiSandboxProxyReadyNotification["method"] =
+  "ui/notifications/sandbox-proxy-ready";
+
+// Message relay: This Sandbox (outer iframe) acts as a bidirectional bridge,
+// forwarding messages between:
+//
+//   Host (parent window) ↔ Sandbox (outer frame) ↔ Guest UI (inner iframe)
+//
+// Reason: the parent window and inner iframe have different origins and can't
+// communicate directly, so the outer iframe forwards messages in both
+// directions to connect them.
+//
+// Special case: The "ui/notifications/sandbox-proxy-ready" message is
+// intercepted here (not relayed) because the Sandbox uses it to configure and
+// load the inner iframe with the Guest UI HTML content.
+//
+// Security: CSP is enforced via HTTP headers on sandbox.html (set by serve.ts
+// based on ?csp= query param). This is tamper-proof unlike meta tags.
+
+window.addEventListener("message", async (event) => {
+  if (event.source === window.parent) {
+    // Validate that messages from parent come from the expected host origin.
+    // This prevents malicious pages from sending messages to this sandbox.
+    if (event.origin !== EXPECTED_HOST_ORIGIN) {
+      console.error(
+        "[Sandbox] Rejecting message from unexpected origin:",
+        event.origin,
+        "expected:",
+        EXPECTED_HOST_ORIGIN
+      );
+      return;
+    }
+
+    if (event.data && event.data.method === RESOURCE_READY_NOTIFICATION) {
+      const { html, sandbox, permissions } = event.data.params;
+      if (typeof sandbox === "string") {
+        inner.setAttribute("sandbox", sandbox);
+      }
+      // Set Permission Policy allow attribute if permissions are requested
+      const allowAttribute = buildAllowAttribute(permissions);
+      if (allowAttribute) {
+        console.log("[Sandbox] Setting allow attribute:", allowAttribute);
+        inner.setAttribute("allow", allowAttribute);
+      }
+      if (typeof html === "string") {
+        // Use document.write instead of srcdoc (which the CesiumJS Map won't work with)
+        const doc = inner.contentDocument || inner.contentWindow?.document;
+        if (doc) {
+          doc.open();
+          doc.write(html);
+          doc.close();
+        } else {
+          // Fallback to srcdoc if document is not accessible
+          console.warn("[Sandbox] document.write not available, falling back to srcdoc");
+          inner.srcdoc = html;
+        }
+      }
+    } else {
+      if (inner && inner.contentWindow) {
+        inner.contentWindow.postMessage(event.data, "*");
+      }
+    }
+  } else if (event.source === inner.contentWindow) {
+    if (event.origin !== OWN_ORIGIN) {
+      console.error(
+        "[Sandbox] Rejecting message from inner iframe with unexpected origin:",
+        event.origin,
+        "expected:",
+        OWN_ORIGIN
+      );
+      return;
+    }
+    // Relay messages from inner frame to parent window.
+    // Use specific origin instead of "*" to prevent message interception.
+    window.parent.postMessage(event.data, EXPECTED_HOST_ORIGIN);
+  }
+});
+
+// Notify the Host that the Sandbox is ready to receive Guest UI HTML.
+// Use specific origin instead of "*" to ensure only the expected host receives this.
+window.parent.postMessage({
+  jsonrpc: "2.0",
+  method: PROXY_READY_NOTIFICATION,
+  params: {},
+}, EXPECTED_HOST_ORIGIN);

examples/basic-host/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

examples/basic-host/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", "*.ts"]
+}

examples/basic-host/vite.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+const INPUT = process.env.INPUT;
+if (!INPUT) {
+  throw new Error("INPUT environment variable is not set");
+}
+
+const isDevelopment = process.env.NODE_ENV === "development";
+
+export default defineConfig({
+  plugins: [react(), viteSingleFile()],
+  build: {
+    sourcemap: isDevelopment ? "inline" : undefined,
+    cssMinify: !isDevelopment,
+    minify: !isDevelopment,
+    rollupOptions: {
+      input: INPUT,
+    },
+    outDir: `dist`,
+    emptyOutDir: false,
+  },
+});

examples/basic-server-preact/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

examples/basic-server-preact/README.md

@@ -0,0 +1,34 @@
+# Example: Basic Server (Preact)
+
+An MCP App example with a Preact UI.
+
+> [!TIP]
+> Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)!
+
+## 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)
+
+## Key Files
+
+- [`server.ts`](server.ts) - MCP server with tool and resource registration
+- [`mcp-app.html`](mcp-app.html) / [`src/mcp-app.tsx`](src/mcp-app.tsx) - Preact UI using `App` class
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+## How It Works
+
+1. The server registers a `get-time` tool with metadata linking it to a UI HTML resource (`ui://get-time/mcp-app.html`).
+2. When the tool is invoked, the Host renders the UI from the resource.
+3. The UI uses the MCP App SDK API to communicate with the host and call server tools.
+
+## 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.

examples/basic-server-preact/mcp-app.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="color-scheme" content="light dark">
+  <title>Get Time App</title>
+  <link rel="stylesheet" href="/src/global.css">
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/mcp-app.tsx"></script>
+</body>
+</html>

examples/basic-server-preact/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@modelcontextprotocol/server-basic-preact",
+  "version": "0.4.0",
+  "type": "module",
+  "description": "Basic MCP App Server example using Preact",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/modelcontextprotocol/ext-apps",
+    "directory": "examples/basic-server-preact"
+  },
+  "license": "MIT",
+  "main": "server.ts",
+  "files": [
+    "server.ts",
+    "server-utils.ts",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build",
+    "watch": "cross-env INPUT=mcp-app.html vite build --watch",
+    "serve": "bun --watch server.ts",
+    "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'",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^0.4.0",
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "preact": "^10.0.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@preact/preset-vite": "^2.0.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "concurrently": "^9.2.1",
+    "cors": "^2.8.5",
+    "cross-env": "^10.1.0",
+    "express": "^5.1.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.3.0"
+  }
+}

examples/basic-server-preact/server-utils.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared utilities for running MCP servers with Streamable HTTP transport.
+ */
+
+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 cors from "cors";
+import type { Request, Response } from "express";
+
+export interface ServerOptions {
+  port: number;
+  name?: string;
+}
+
+/**
+ * Starts an MCP server with Streamable HTTP transport in stateless mode.
+ *
+ * @param createServer - Factory function that creates a new McpServer instance per request.
+ * @param options - Server configuration options.
+ */
+export async function startServer(
+  createServer: () => McpServer,
+  options: ServerOptions,
+): Promise<void> {
+  const { port, name = "MCP Server" } = options;
+
+  const app = createMcpExpressApp({ host: "0.0.0.0" });
+  app.use(cors());
+
+  app.all("/mcp", async (req: Request, res: Response) => {
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+
+    res.on("close", () => {
+      transport.close().catch(() => {});
+      server.close().catch(() => {});
+    });
+
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      console.error("MCP error:", error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal server error" },
+          id: null,
+        });
+      }
+    }
+  });
+
+  const httpServer = app.listen(port, (err) => {
+    if (err) {
+      console.error("Failed to start server:", err);
+      process.exit(1);
+    }
+    console.log(`${name} listening on http://localhost:${port}/mcp`);
+  });
+
+  const shutdown = () => {
+    console.log("\nShutting down...");
+    httpServer.close(() => process.exit(0));
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}

examples/basic-server-preact/server.ts

@@ -0,0 +1,71 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { startServer } from "./server-utils.js";
+
+const DIST_DIR = path.join(import.meta.dirname, "dist");
+
+/**
+ * Creates a new MCP server instance with tools and resources registered.
+ */
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: "Basic MCP App Server (Preact)",
+    version: "1.0.0",
+  });
+
+  // Two-part registration: tool + resource, tied together by the resource URI.
+  const resourceUri = "ui://get-time/mcp-app.html";
+
+  // Register a tool with UI metadata. When the host calls this tool, it reads
+  // `_meta.ui.resourceUri` to know which resource to fetch and render as an
+  // interactive UI.
+  registerAppTool(server,
+    "get-time",
+    {
+      title: "Get Time",
+      description: "Returns the current server time as an ISO 8601 string.",
+      inputSchema: {},
+      _meta: { ui: { resourceUri } },
+    },
+    async (): Promise<CallToolResult> => {
+      const time = new Date().toISOString();
+      return { content: [{ type: "text", text: time }] };
+    },
+  );
+
+  // Register the resource, which returns the bundled HTML/JavaScript for the UI.
+  registerAppResource(server,
+    resourceUri,
+    resourceUri,
+    { mimeType: RESOURCE_MIME_TYPE },
+    async (): Promise<ReadResourceResult> => {
+      const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
+
+      return {
+        contents: [
+          { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+        ],
+      };
+    },
+  );
+
+  return server;
+}
+
+async function main() {
+  if (process.argv.includes("--stdio")) {
+    await createServer().connect(new StdioServerTransport());
+  } else {
+    const port = parseInt(process.env.PORT ?? "3001", 10);
+    await startServer(createServer, { port, name: "Basic MCP App Server (Preact)" });
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

examples/basic-server-preact/src/global.css

@@ -0,0 +1,12 @@
+* {
+  box-sizing: border-box;
+}
+
+html, body {
+  font-family: system-ui, -apple-system, sans-serif;
+  font-size: 1rem;
+}
+
+code {
+  font-size: 1em;
+}

examples/basic-server-preact/src/mcp-app.module.css

@@ -0,0 +1,65 @@
+.main {
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+  --color-notice-bg: #eff6ff;
+
+  width: 100%;
+  max-width: 425px;
+  box-sizing: border-box;
+
+  > * {
+    margin-top: 0;
+    margin-bottom: 0;
+  }
+
+  > * + * {
+    margin-top: 1.5rem;
+  }
+}
+
+.action {
+  > * {
+    margin-top: 0;
+    margin-bottom: 0;
+    width: 100%;
+  }
+
+  > * + * {
+    margin-top: 0.5rem;
+  }
+
+  /* Consistent font for form inputs (inherits from global.css) */
+  textarea,
+  input {
+    font-family: inherit;
+    font-size: inherit;
+  }
+
+  button {
+    padding: 0.5rem 1rem;
+    border: none;
+    border-radius: 6px;
+    color: white;
+    font-weight: bold;
+    background-color: var(--color-primary);
+    cursor: pointer;
+
+    &:hover,
+    &:focus-visible {
+      background-color: var(--color-primary-hover);
+    }
+  }
+}
+
+.notice {
+  padding: 0.5rem 0.75rem;
+  color: var(--color-primary);
+  text-align: center;
+  font-style: italic;
+  background-color: var(--color-notice-bg);
+
+  &::before {
+    content: "ℹ️ ";
+    font-style: normal;
+  }
+}

examples/basic-server-preact/src/mcp-app.tsx

@@ -0,0 +1,171 @@
+/**
+ * @file App that demonstrates a few features using MCP Apps SDK + Preact.
+ */
+import {
+  App,
+  applyDocumentTheme,
+  applyHostFonts,
+  applyHostStyleVariables,
+  type McpUiHostContext,
+} from "@modelcontextprotocol/ext-apps";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { useCallback, useEffect, useState } from "preact/hooks";
+import { render } from "preact";
+import styles from "./mcp-app.module.css";
+
+function extractTime(callToolResult: CallToolResult): string {
+  const { text } = callToolResult.content?.find((c) => c.type === "text")!;
+  return text;
+}
+
+
+function GetTimeApp() {
+  const [app, setApp] = useState<App | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [toolResult, setToolResult] = useState<CallToolResult | null>(null);
+  const [hostContext, setHostContext] = useState<McpUiHostContext | undefined>();
+
+  // Apply host styles reactively when hostContext 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]);
+
+  useEffect(() => {
+    const instance = new App({ name: "Get Time App", version: "1.0.0" });
+
+    instance.ontoolinput = async (input) => {
+      console.info("Received tool call input:", input);
+    };
+
+    instance.ontoolresult = async (result) => {
+      console.info("Received tool call result:", result);
+      setToolResult(result);
+    };
+
+    instance.ontoolcancelled = (params) => {
+      console.info("Tool call cancelled:", params.reason);
+    };
+
+    instance.onerror = console.error;
+
+    instance.onhostcontextchanged = (params) => {
+      setHostContext((prev) => ({ ...prev, ...params }));
+    };
+
+    instance
+      .connect()
+      .then(() => {
+        setApp(instance);
+        setHostContext(instance.getHostContext());
+      })
+      .catch(setError);
+  }, []);
+
+  if (error) return <div><strong>ERROR:</strong> {error.message}</div>;
+  if (!app) return <div>Connecting...</div>;
+
+  return <GetTimeAppInner app={app} toolResult={toolResult} hostContext={hostContext} />;
+}
+
+
+interface GetTimeAppInnerProps {
+  app: App;
+  toolResult: CallToolResult | null;
+  hostContext?: McpUiHostContext;
+}
+function GetTimeAppInner({ app, toolResult, hostContext }: GetTimeAppInnerProps) {
+  const [serverTime, setServerTime] = useState("Loading...");
+  const [messageText, setMessageText] = useState("This is message text.");
+  const [logText, setLogText] = useState("This is log text.");
+  const [linkUrl, setLinkUrl] = useState("https://modelcontextprotocol.io/");
+
+  useEffect(() => {
+    if (toolResult) {
+      setServerTime(extractTime(toolResult));
+    }
+  }, [toolResult]);
+
+  const handleGetTime = useCallback(async () => {
+    try {
+      console.info("Calling get-time tool...");
+      const result = await app.callServerTool({ name: "get-time", arguments: {} });
+      console.info("get-time result:", result);
+      setServerTime(extractTime(result));
+    } catch (e) {
+      console.error(e);
+      setServerTime("[ERROR]");
+    }
+  }, [app]);
+
+  const handleSendMessage = useCallback(async () => {
+    const signal = AbortSignal.timeout(5000);
+    try {
+      console.info("Sending message text to Host:", messageText);
+      const { isError } = await app.sendMessage(
+        { role: "user", content: [{ type: "text", text: messageText }] },
+        { signal },
+      );
+      console.info("Message", isError ? "rejected" : "accepted");
+    } catch (e) {
+      console.error("Message send error:", signal.aborted ? "timed out" : e);
+    }
+  }, [app, messageText]);
+
+  const handleSendLog = useCallback(async () => {
+    console.info("Sending log text to Host:", logText);
+    await app.sendLog({ level: "info", data: logText });
+  }, [app, logText]);
+
+  const handleOpenLink = useCallback(async () => {
+    console.info("Sending open link request to Host:", linkUrl);
+    const { isError } = await app.openLink({ url: linkUrl });
+    console.info("Open link request", isError ? "rejected" : "accepted");
+  }, [app, linkUrl]);
+
+  return (
+    <main
+      className={styles.main}
+      style={{
+        paddingTop: hostContext?.safeAreaInsets?.top,
+        paddingRight: hostContext?.safeAreaInsets?.right,
+        paddingBottom: hostContext?.safeAreaInsets?.bottom,
+        paddingLeft: hostContext?.safeAreaInsets?.left,
+      }}
+    >
+      <p className={styles.notice}>Watch activity in the DevTools console!</p>
+
+      <div className={styles.action}>
+        <p>
+          <strong>Server Time:</strong> <code id="server-time">{serverTime}</code>
+        </p>
+        <button onClick={handleGetTime}>Get Server Time</button>
+      </div>
+
+      <div className={styles.action}>
+        <textarea value={messageText} onChange={(e) => setMessageText(e.currentTarget.value)} />
+        <button onClick={handleSendMessage}>Send Message</button>
+      </div>
+
+      <div className={styles.action}>
+        <input type="text" value={logText} onChange={(e) => setLogText(e.currentTarget.value)} />
+        <button onClick={handleSendLog}>Send Log</button>
+      </div>
+
+      <div className={styles.action}>
+        <input type="url" value={linkUrl} onChange={(e) => setLinkUrl(e.currentTarget.value)} />
+        <button onClick={handleOpenLink}>Open Link</button>
+      </div>
+    </main>
+  );
+}
+
+
+render(<GetTimeApp />, document.getElementById("root")!);

examples/basic-server-preact/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

examples/basic-server-preact/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "strict": true,
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", "server.ts"]
+}

examples/basic-server-preact/vite.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "vite";
+import preact from "@preact/preset-vite";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+const INPUT = process.env.INPUT;
+if (!INPUT) {
+  throw new Error("INPUT environment variable is not set");
+}
+
+const isDevelopment = process.env.NODE_ENV === "development";
+
+export default defineConfig({
+  plugins: [preact(), viteSingleFile()],
+  build: {
+    sourcemap: isDevelopment ? "inline" : undefined,
+    cssMinify: !isDevelopment,
+    minify: !isDevelopment,
+
+    rollupOptions: {
+      input: INPUT,
+    },
+    outDir: "dist",
+    emptyOutDir: false,
+  },
+});

examples/basic-server-react/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

examples/basic-server-react/README.md

@@ -0,0 +1,36 @@
+# Example: Basic Server (React)
+
+![Screenshot](screenshot.png)
+
+An MCP App example with a React UI.
+
+> [!TIP]
+> Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)!
+
+## 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)
+
+## Key Files
+
+- [`server.ts`](server.ts) - MCP server with tool and resource registration
+- [`mcp-app.html`](mcp-app.html) / [`src/mcp-app.tsx`](src/mcp-app.tsx) - React UI using `useApp()` hook
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+## How It Works
+
+1. The server registers a `get-time` tool with metadata linking it to a UI HTML resource (`ui://get-time/mcp-app.html`).
+2. When the tool is invoked, the Host renders the UI from the resource.
+3. The UI uses the MCP App SDK API to communicate with the host and call server tools.
+
+## 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.

examples/basic-server-react/mcp-app.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="color-scheme" content="light dark">
+  <title>Get Time App</title>
+  <link rel="stylesheet" href="/src/global.css">
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/mcp-app.tsx"></script>
+</body>
+</html>

examples/basic-server-react/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@modelcontextprotocol/server-basic-react",
+  "version": "0.4.0",
+  "type": "module",
+  "description": "Basic MCP App Server example using React",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/modelcontextprotocol/ext-apps",
+    "directory": "examples/basic-server-react"
+  },
+  "license": "MIT",
+  "main": "server.ts",
+  "files": [
+    "server.ts",
+    "server-utils.ts",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build",
+    "watch": "cross-env INPUT=mcp-app.html vite build --watch",
+    "serve": "bun --watch server.ts",
+    "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'",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^0.4.0",
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "concurrently": "^9.2.1",
+    "cors": "^2.8.5",
+    "cross-env": "^10.1.0",
+    "express": "^5.1.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.3.0"
+  }
+}