Skip to main content

​
Overview

MCP-UI + WebMCP creates bidirectional AI integration: AI agents invoke tools that render interactive web applications, and those embedded apps dynamically register new tools back to the AI. The pattern combines:
  • MCP-UI: Tools that return visual interfaces (UI resources with iframes)
  • WebMCP: Embedded apps registering tools via navigator.modelContext
  • IframeTransports: Bidirectional MCP communication between parent and iframe

Build Your First App

Ready to build? Follow the step-by-step implementation guide with code examples.

​
The Core Workflow

​
Architecture Components

This pattern involves three main components working together:

​
1. Chat UI (Parent Context)

The parent application that hosts the AI conversation and manages embedded apps: Responsibilities:
  • Connects to remote MCP servers via HTTP/SSE
  • Manages iframe lifecycle and transport channels
  • Routes tool calls to appropriate clients (HTTP MCP or WebMCP)
  • Displays AI conversation and embedded apps

​
2. Embedded Apps (Iframe Context)

Mini-applications that run in iframes and register tools dynamically: Apps register tools via navigator.modelContext.provideContext(), which is polyfilled by @mcp-b/global until native browser support is available.

​
3. MCP Server

Remote server that exposes initial tools returning UI resources with createUIResource() from @mcp-ui/server.

​
Communication Flow

​
MCP UI Resource Types

UI resources can be rendered three ways:
  • externalUrl: Load a complete web app in iframe (most common for interactive apps)
  • rawHtml: Inject sanitized HTML directly (simple widgets)
  • remoteDom: Stream dynamic DOM updates (real-time data)

​
WebMCP vs MCP-B

  • WebMCP: W3C standard specification defining navigator.modelContext API
  • MCP-B: Reference implementation (@mcp-b/* packages) providing polyfills before native browser support

​
Why This Pattern?

Dynamic Tool Discovery: AI automatically discovers tools as they become available based on app state. Separation of Concerns: UI logic stays in embedded app, parent manages conversation flow. Security Isolation: Iframes provide security boundaries with controlled postMessage communication. Progressive Enhancement: Apps work standalone and gain AI capabilities when embedded.

​
Common Use Cases

  • Interactive Games: AI plays games via dynamically registered move tools
  • Data Visualization: Charts with filtering/manipulation tools
  • Form Builders: Forms with validation and submission tools
  • Configuration UIs: Settings panels with AI-controlled configuration
  • Real-time Dashboards: Live data with AI-controlled filters

Build Your First App

Step-by-step implementation guide with code examples

WebMCP Architecture

Overall WebMCP system architecture

Transports

Deep dive into transport layer communication

Examples & Source Code

TicTacToe game and template repository