> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-b-sync-npm-packages-docs-bf03420.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP-UI Architecture

> Architecture and communication flow for bidirectional AI-app integration using IframeParentTransport and IframeChildTransport for parent-child tool communication.

## 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

<Card title="Build Your First App" icon="rocket" href="/building-mcp-ui-apps">
  Ready to build? Follow the step-by-step implementation guide with code examples.
</Card>

## The Core Workflow

```mermaid theme={null}
sequenceDiagram
    participant AI as AI Assistant
    participant MCP as MCP Server
    participant Chat as Chat UI
    participant App as Embedded App

    AI->>MCP: Call tool "showTicTacToeGame"
    MCP-->>Chat: Return UI resource (iframe URL)
    Chat->>App: Load iframe & establish transport
    App->>Chat: Register "tictactoe_move" tool
    App->>Chat: Register "tictactoe_reset" tool
    Chat-->>AI: Tools now available
    AI->>Chat: Call "tictactoe_move" with position
    Chat->>App: Execute tool via postMessage
    App-->>Chat: Return game state
    Chat-->>AI: Tool result with updated state
```

## 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:

```mermaid theme={null}
graph TB
    subgraph "Chat UI"
        A[HTTP MCP Client] -->|Connects to| B[Remote MCP Server]
        C[WebMCP Manager] -->|Manages| D[Iframe Tools]
        E[Router] -->|Routes calls| A
        E -->|Routes calls| C
        F[Iframe Lifecycle] -->|Establishes| G[IframeParentTransport]
    end

    style A fill:#4B7BFF
    style C fill:#50C878
    style E fill:#FFB84D
```

**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:

```mermaid theme={null}
graph TB
    subgraph "Embedded App (Iframe)"
        A[React Component] -->|Uses| B[useWebMCP Hook]
        B -->|Registers via| C[navigator.modelContext]
        C -->|Polyfilled by| D[@mcp-b/global]
        D -->|Communicates via| E[IframeChildTransport]
        E <-->|postMessage| F[Parent Window]
    end

    style A fill:#4B7BFF
    style B fill:#50C878
    style D fill:#FFB84D
```

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

```mermaid theme={null}
sequenceDiagram
    participant A as AI Assistant
    participant C as Chat UI
    participant M as MCP Server
    participant I as Iframe App

    Note over A,I: Initial Tool Call
    A->>C: Call "showTicTacToeGame"
    C->>M: Forward via HTTP MCP
    M-->>C: Return UI resource
    C->>I: Render iframe with URL

    Note over C,I: WebMCP Transport Setup
    I->>C: postMessage: "ui-lifecycle-iframe-ready"
    C-->>I: postMessage: "parent-ready"

    Note over I,A: Dynamic Tool Registration
    I->>C: Register "tictactoe_move" via postMessage
    I->>C: Register "tictactoe_reset" via postMessage
    C-->>A: Update available tools

    Note over A,I: Tool Execution
    A->>C: Call "tictactoe_move"
    C->>I: postMessage with tool call
    I->>I: Execute handler
    I-->>C: postMessage with result
    C-->>A: Return tool result
```

## 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

## Related Topics

<CardGroup cols={2}>
  <Card title="Build Your First App" icon="hammer" href="/building-mcp-ui-apps">
    Step-by-step implementation guide with code examples
  </Card>

  <Card title="WebMCP Architecture" icon="diagram-project" href="/concepts/architecture">
    Overall WebMCP system architecture
  </Card>

  <Card title="Transports" icon="tower-broadcast" href="/concepts/transports">
    Deep dive into transport layer communication
  </Card>

  <Card title="Examples & Source Code" icon="github" href="https://github.com/WebMCP-org/mcp-ui-webmcp">
    TicTacToe game and template repository
  </Card>
</CardGroup>