---

name: mcp-apps-ts description: Build interactive HTML UIs for MCP servers using the MCP Apps extension (SEP-1865). Covers server-side tool registration with UI resources, client-side App lifecycle, and host integration via AppBridge. Use when creating visual interfaces for MCP tools.

TypeScript MCP Apps Builder

Build interactive HTML UIs for MCP tools using the MCP Apps extension (SEP-1865).

This is an experimental extension. MCP Apps enables servers to deliver interactive HTML UIs that run in sandboxed iframes, allowing rich visual interfaces while maintaining security.

Tip: Stay up to date! MCP Apps is under active development. Before starting, check the ext-apps repository for:

• Open Pull Requests - upcoming changes
• Issues - known bugs and feature requests
• Recent Commits - latest changes
• Releases - version history

How It Works

1. Browse the snippet catalog below or in snippets/
2. Identify your role: server developer, app developer, or host integrator
3. Copy the snippets you need into your project
4. Customize the copied code for your use case

---

Quick Start Decision Trees

What Role Are You Building?

CopyWant a complete, runnable starter project?
  -> Copy a SCAFFOLD (new!)
      - scaffold-vanilla-server: Full server + vanilla JS UI
        Copy the directory, run npm install && npm run dev
        See snippets/scaffold/vanilla-server/README.md

Building an MCP server that provides tools with UIs?
  -> Start with SERVER snippets
      - tool-with-ui: Register tool with associated HTML UI
      - tool-with-structured: Return structured content
      - resource-with-csp: Add Content Security Policy
      - server-with-private-tools: Hide tools from model (NEW!)

Building the HTML UI that displays to users?
  -> Start with APP snippets
      - app-vanilla-basic: Simple App class setup (vanilla JS)
      - app-vanilla-full: Full lifecycle handlers (vanilla JS)
      - app-react-basic: React hooks integration
      - app-react-with-styles: React with host styling (NEW!)
      - tool-calling: Call back to server tools
      - app-with-display-mode: Request fullscreen/pip (NEW!)
      - app-with-model-context: Update model context (NEW!)

Building a host/client that embeds MCP app UIs?
  -> Start with HOST snippets
      - host-full-integration: Complete end-to-end flow (single server)
      - host-multi-server: Connect to multiple servers with UI routing
      - sandbox-proxy: Required for security
      - app-bridge-basic: Just the AppBridge setup
      - app-bridge-handlers: Full handlers setup

Which App Framework Should I Use?

CopyMinimal dependencies, simple UI?
  -> Use Vanilla JS snippets
      - app-vanilla-basic for getting started
      - app-vanilla-full for full control

React-based UI with state management?
  -> Use React snippets
      - app-react-basic for hooks integration
      - app-react-with-styles for host styling

---

Phase 1: Research

1.1 Understand MCP Apps Architecture

MCP Apps uses a two-part registration pattern: Tool + UI Resource.

1.2 Key Concepts

• ui:// URI Scheme: Tools reference UI resources via ui://tool-name/app.html URIs
• RESOURCE_URI_META_KEY: Constant for linking tools to UIs in _meta
• RESOURCE_MIME_TYPE: text/html;profile=mcp-app identifies MCP App resources
• PostMessageTransport: Communication between app iframe and host
• Double-iframe Sandboxing: Outer iframe isolates, inner iframe runs app with allow-scripts
• Host Context: Theme, locale, styles, and safe area information from the host
• Display Modes: Inline, fullscreen, or picture-in-picture display options

1.3 Browse Available Snippets

---

Phase 2: Implement

2.1 Server-Side: Register Tool with UI

Copynpm install @modelcontextprotocol/sdk @modelcontextprotocol/ext-apps zod

Copy the tool-with-ui snippet and customize:

1. Define your tool's input schema
2. Create the UI resource HTML content
3. Link tool to UI via ui:// URI and _meta.ui.resourceUri

For tools that should only be callable by the UI (not the model), use server-with-private-tools:

Copy_meta: { ui: { resourceUri: "ui://...", visibility: ["app"] } }

See also: For MCP server basics (transports, tool registration patterns), refer to the mcp-server-ts skill.

2.2 App-Side: Build the UI

Vanilla JS:

Copynpm install @modelcontextprotocol/ext-apps

React:

Copynpm install @modelcontextprotocol/ext-apps react react-dom

Copy the appropriate app snippet and implement:

1. Initialize App with name and version
2. Register handlers BEFORE calling connect()
3. Handle ontoolresult for tool execution results
4. Handle ontoolcancelled for cancellation
5. Handle onhostcontextchanged for theme/style changes
6. Call tools via app.callServerTool()

2.3 Host Context & Styling

Apps can access host context for theme, styles, and safe areas:

Copyconst context = app.getHostContext();
// {
//   theme: "light" | "dark",
//   locale: "en-US",
//   styles: { variables: { ... }, css: { fonts: "..." } },
//   safeAreaInsets: { top, right, bottom, left },
//   availableDisplayModes: ["inline", "fullscreen", "pip"]
// }

React: Use useHostStyleVariables() and useHostFonts() hooks to automatically apply host styles.

2.4 Display Modes

Apps can request different display modes:

Copy// Check if fullscreen is available
if (context?.availableDisplayModes?.includes("fullscreen")) {
  await app.requestDisplayMode({ mode: "fullscreen" });
}

2.5 Model Context Updates

Apps can update the model's context with state information:

Copyawait app.updateModelContext({
  content: [{ type: "text", text: "User selected 3 items" }],
  structuredContent: { items: 3, total: 150.00 }
});

2.6 Host-Side: Embed Apps (Optional)

Copynpm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk

Copy the host-full-integration snippet for the complete flow, or start with app-bridge-basic for just the AppBridge setup:

1. Connect MCP client to server (see mcp-client-ts skill)
2. Create AppBridge with the connected client
3. Set up sandbox proxy iframe (use sandbox-proxy snippet)
4. Register handlers before connecting
5. Load UI resource and initialize app

Critical: The App initiates ui/initialize, the Host responds! If building without AppBridge SDK, you must handle the request/response correctly. See "Common Pitfalls" in the Architecture reference.

See also: For MCP client basics (connecting to servers, calling tools), refer to the mcp-client-ts skill.

---

Phase 3: Test

3.1 Build All Components

Copy# Build UI (using Vite with vite-plugin-singlefile)
npm run build

# Start MCP server
npm run serve

3.2 Test with Reference Host

Copy# Clone ext-apps repo for test host
git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps/examples/basic-host
npm install && npm start
# Open http://localhost:8080

3.3 Quality Checklist

• Tool correctly registers with ui:// resource
• RESOURCE_MIME_TYPE is text/html;profile=mcp-app
• App initializes without errors
• Handlers registered BEFORE connect()
• ontoolresult receives tool execution results
• ontoolcancelled handles cancellation gracefully
• onhostcontextchanged responds to theme changes
• callServerTool() successfully calls server
• CSP is properly declared (if using)

3.4 Common Gotchas

1. Always describe your UI in content: The model doesn't see the visual UI - only the tool result content. Always include a text description of what was rendered:

Copyreturn {
  content: [{ type: "text", text: "Displayed weather widget showing 72°F, sunny conditions" }],
  structuredContent: { temp: 72, condition: "sunny" }
};

2. Data flow to model context:

• content and structuredContent → sent to model context
• _meta → NOT sent to model (only for host/UI metadata)
• Don't put large base64 data in structuredContent - use content with resource references

3. Check for UI support before registering (coming soon): Once PR #313 merges, use hasUiSupport() to conditionally register UI tools:

Copyserver.oninitialized = ({ clientCapabilities }) => {
  if (hasUiSupport(clientCapabilities)) {
    registerAppTool(server, "weather", { /* ... */ }, handler);
  }
};

---

Available Snippets Catalog

Scaffold (Complete Starter Projects)

Quick Start with Scaffold:

Copy# Copy the scaffold to your project
cp -r snippets/scaffold/vanilla-server ./my-mcp-app

# Install and run
cd my-mcp-app
npm install
npm run dev

Server runs at http://localhost:3102/mcp. Test with the basic-host example.

Server (MCP Server with UI)

App (HTML UI in iframe)

Host (Embedding Apps)

---

Reference Files

For deeper guidance, load these reference documents:

• MCP Apps Architecture - Component overview, data flow, security, common pitfalls, open PRs/issues
• MCP Apps API Reference - Full API documentation

Important: Read the "Common Pitfalls" section in the Architecture doc before implementing a host. Key issues include srcdoc iframe origins, protocol direction, message sequencing, and handler overwrite bugs.

---

SDK Packages

---

External Resources

• MCP Apps SDK Repository
• Quickstart Guide
• API Documentation
• SEP-1865 Specification
• MCP TypeScript SDK