# modelcontextprotocol/ext-apps architecture

> Architecture diagram of the GitHub repository modelcontextprotocol/ext-apps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modelcontextprotocol/ext-apps
- Repository: https://github.com/modelcontextprotocol/ext-apps

## Overview

MCP Apps is a TypeScript SDK for serving interactive UI resources through MCP tools and connecting those UIs to compliant chat hosts. The main workflow is server-side tool/resource registration, tool invocation, host resource loading and iframe rendering, then bidirectional communication between the UI and host. The SDK also exposes host-context, display-mode, teardown, model-context, and sizing features, plus optional React hooks for connection, resizing, and host styling. The tree and excerpts support these major boundaries; some internal wiring, especially in the bridge and transport, is not shown.

Main entry points: [`src/app.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/app.ts) (App Protocol Client), [`src/react/useApp.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useApp.tsx) (React App Hook), [`src/server/index.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/server/index.ts) (UI Resource Registration), [`src/react/useHostStyles.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useHostStyles.ts) (Host Style Hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server Integration"]
  node_register["Tool Registration<br/>[index.ts]"]
  node_resource["UI Resource Registration<br/>[index.ts]"]
end

subgraph group_runtime["App Runtime"]
  node_app["App Protocol Client<br/>[app.ts]"]
  node_transport["PostMessage Transport"]
  node_bridge["App Bridge<br/>[app-bridge.ts]"]
end

subgraph group_react["React Integration"]
  node_reactapp["React App Hook<br/>[useApp.tsx]"]
  node_resize["Resize Hook<br/>[useAutoResize.ts]"]
  node_hoststyles["Host Style Hooks<br/>[useHostStyles.ts]"]
  node_theme["Document Theme Hook"]
end

subgraph group_shared["Protocol and Styling"]
  node_events["Event Dispatch<br/>[events.ts]"]
  node_validation["Schema Validation<br/>[standard-schema.ts]"]
  node_types["Protocol Types<br/>[types.ts]"]
  node_styles["Host Style Application<br/>[styles.ts]"]
end

node_developer(("MCP App Developer"))
node_server["MCP Server"]
node_model(("LLM Tool Caller"))
node_host(("Compliant Host"))
node_iframe["Sandboxed UI"]

node_developer -->|"registers tools"| node_register
node_developer -->|"registers resources"| node_resource
node_register -->|"registers with"| node_server
node_resource -->|"registers with"| node_server
node_model -->|"calls tool"| node_server
node_server -->|"returns tool result"| node_host
node_host -->|"fetches UI resource"| node_resource
node_host -->|"renders resource"| node_iframe
node_iframe -.->|"mounts hook"| node_reactapp
node_reactapp -->|"creates and connects"| node_app
node_reactapp -->|"creates transport"| node_transport
node_app -->|"communicates through"| node_transport
node_app -->|"requests and notifies"| node_host
node_host -->|"sends context and tool data"| node_app
node_app -->|"dispatches events"| node_events
node_app -->|"validates tool data"| node_validation
node_bridge -.->|"bridges app protocol"| node_app
node_app -->|"uses protocol definitions"| node_types
node_resize -->|"sets up size reporting"| node_app
node_hoststyles -->|"observes host context"| node_app
node_hoststyles -->|"applies host styles"| node_styles
node_theme -->|"reads document theme"| node_styles

click node_register "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/server/index.ts"
click node_resource "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/server/index.ts"
click node_app "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/app.ts"
click node_transport "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/message-transport.ts"
click node_bridge "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/app-bridge.ts"
click node_events "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/events.ts"
click node_validation "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/standard-schema.ts"
click node_types "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/types.ts"
click node_styles "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/styles.ts"
click node_reactapp "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useApp.tsx"
click node_resize "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useAutoResize.ts"
click node_hoststyles "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useHostStyles.ts"
click node_theme "https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useDocumentTheme.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_register,node_resource,node_iframe toneBlue
class node_app,node_transport,node_bridge toneAmber
class node_reactapp,node_resize,node_hoststyles,node_theme,node_server toneMint
class node_events,node_validation,node_types,node_styles toneRose
class node_developer,node_model,node_host toneIndigo
```

## Components

### Server Integration

- [Tool Registration](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/server/index.ts): `src/server/index.ts`
- [UI Resource Registration](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/server/index.ts): `src/server/index.ts`

### App Runtime

- [App Protocol Client](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/app.ts): `src/app.ts`
- [PostMessage Transport](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/message-transport.ts): `src/message-transport.ts`
- [App Bridge](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/app-bridge.ts): `src/app-bridge.ts`

### React Integration

- [React App Hook](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useApp.tsx): `src/react/useApp.tsx`
- [Resize Hook](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useAutoResize.ts): `src/react/useAutoResize.ts`
- [Host Style Hooks](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useHostStyles.ts): `src/react/useHostStyles.ts`
- [Document Theme Hook](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useDocumentTheme.ts): `src/react/useDocumentTheme.ts`

### Protocol and Styling

- [Event Dispatch](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/events.ts): `src/events.ts`
- [Schema Validation](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/standard-schema.ts): `src/standard-schema.ts`
- [Protocol Types](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/types.ts): `src/types.ts`
- [Host Style Application](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/styles.ts): `src/styles.ts`

### Other components

- **MCP App Developer**
- **MCP Server**
- **LLM Tool Caller**
- **Compliant Host**
- **Sandboxed UI**

## Connections

- MCP App Developer → Tool Registration: registers tools
- MCP App Developer → UI Resource Registration: registers resources
- Tool Registration → MCP Server: registers with
- UI Resource Registration → MCP Server: registers with
- LLM Tool Caller → MCP Server: calls tool
- MCP Server → Compliant Host: returns tool result
- Compliant Host → UI Resource Registration: fetches UI resource
- Compliant Host → Sandboxed UI: renders resource
- Sandboxed UI → React App Hook: mounts hook
- React App Hook → App Protocol Client: creates and connects
- React App Hook → PostMessage Transport: creates transport
- App Protocol Client → PostMessage Transport: communicates through
- App Protocol Client → Compliant Host: requests and notifies
- Compliant Host → App Protocol Client: sends context and tool data
- App Protocol Client → Event Dispatch: dispatches events
- App Protocol Client → Schema Validation: validates tool data
- App Bridge → App Protocol Client: bridges app protocol
- App Protocol Client → Protocol Types: uses protocol definitions
- Resize Hook → App Protocol Client: sets up size reporting
- Host Style Hooks → App Protocol Client: observes host context
- Host Style Hooks → Host Style Application: applies host styles
- Document Theme Hook → Host Style Application: reads document theme