ext-apps

Renders HTML-based user interfaces in sandboxed iframes that communicate bidirectionally with MCP hosts via JSON-RPC 2.0 over postMessage. The protocol enforces strict message validation, capability negotiation during initialization, and secure request/response routing between View (iframe) and Host layers without direct DOM access or network exposure. Uses a three-party architecture where MCP servers declare ui:// URI resources that hosts fetch and render, with the View layer isolated from host context except through explicit RPC calls.

Enables MCP servers to declare interactive HTML resources using the ui:// URI scheme and link them to specific tools via _meta.ui.resourceUri metadata. The server SDK provides helper functions to register UI resources with MIME type text/html, versioning, and optional display mode hints (inline, modal, sidebar). When a tool is executed, the host automatically fetches the linked UI resource and renders it in an iframe, establishing the communication channel between the View and the server's tool execution context.

Provides APIs for Views to send log messages and events to the host via JSON-RPC notifications. Views can emit structured log messages with severity levels (debug, info, warn, error) and arbitrary event data. The host collects these messages and can display them in a debug console, forward them to a logging service, or use them for monitoring. Messages are sent as one-way notifications (no response expected), reducing latency compared to request-response patterns. The SDK provides logging utilities that format messages consistently.

Provides server-side helper functions (JavaScript/TypeScript and Python) for registering UI resources, declaring tool-UI linkage, and managing tool metadata. Helpers simplify the process of adding ui:// resources to the MCP server's resource list and linking them to tools via _meta.ui.resourceUri. The SDK validates resource declarations against the SEP-1865 specification and provides TypeScript types for tool metadata. Helpers support both inline HTML (as strings) and file-based resources.

Defines the complete MCP Apps Extension protocol (SEP-1865) with detailed message schemas, initialization handshake, tool lifecycle, and error handling. The specification is published as a formal document (specification/2026-01-26/apps.mdx) and includes JSON Schema definitions for all message types. The SDK generates TypeScript types and validation code from these schemas, enabling compile-time and runtime validation of messages. The specification covers three-party architecture, security model, display modes, and capability negotiation.

Provides production-ready example servers demonstrating real-world MCP Apps use cases (map viewer, PDF viewer, system monitor, data explorer, etc.) and AI agent skills for scaffolding new Views and servers. Examples include both basic framework examples (minimal setup) and domain-specific examples (complex interactions). The repository includes build configuration (Vite), test infrastructure, and development tools for building and testing MCP Apps locally. Agent skills enable developers to generate boilerplate code for new Views and servers.

Provides the App class (View-side SDK) that manages the iframe lifecycle, initializes communication with the host via postMessage, and exposes methods to call server tools with typed parameters and receive results. The App class handles initialization handshake (exchanging protocol versions and capabilities), maintains a request-response mapping for async tool calls, and provides hooks for lifecycle events (onReady, onClose). Tool calls are wrapped in JSON-RPC requests with automatic ID generation and timeout handling, with results returned as Promise-based responses.

Provides React hooks (useApp, useAppBridge) that wrap the App and AppBridge classes, enabling declarative tool calling and host integration within React components. The useApp hook returns the initialized App instance with automatic cleanup on unmount, while useAppBridge provides host-side access to the bridge for managing Views and forwarding requests. Hooks handle the initialization timing, ensuring the App is ready before components attempt tool calls, and provide TypeScript support for tool schemas and parameters.

Provides the AppBridge class (Host-side SDK) that manages iframe lifecycle, forwards tool requests from Views to MCP servers, and handles capability negotiation during initialization. AppBridge intercepts JSON-RPC requests from Views, validates them against declared tool schemas, forwards them to the appropriate MCP server, and returns results back to the View. It also manages host context (styling, display mode) and sends notifications to Views. Capability negotiation ensures both View and Host agree on protocol version and supported features before tool execution begins.

Provides a PostMessageTransport class that abstracts the low-level postMessage API into a JSON-RPC 2.0 transport layer. It handles message serialization/deserialization, request-response correlation via message IDs, error handling, and timeout management. The transport validates incoming messages against the JSON-RPC 2.0 spec, maintains a pending request map, and routes responses to the correct handlers. It supports both request-response patterns (for tool calls) and one-way notifications (for logs, events).

Enables hosts to send context information (theme, display mode, viewport size) and CSS styling to Views via JSON-RPC messages. The host can declare supported display modes (inline, modal, sidebar) and the View can query or subscribe to host context changes. The SDK provides styling utilities that generate CSS variables and theme classes based on host context, allowing Views to adapt their appearance to the host's design system. Context is propagated during initialization and can be updated dynamically.

Supports progressive rendering where server tools can send partial results to Views via streaming or chunked responses. The View can display intermediate results as they arrive, improving perceived performance for long-running operations. The protocol supports both complete responses (single JSON-RPC response) and streaming responses (multiple messages with a completion marker). The SDK provides utilities for handling streaming results and updating the UI incrementally.

Provides patterns and utilities for Views to persist state locally (in browser storage) or request persistence from the server. Views can store UI state (form inputs, scroll position, selected items) locally to survive iframe reloads, or request the server to store application state. The SDK provides helper functions for serializing/deserializing state and managing storage quotas. State can be scoped to the View instance or shared across multiple Views of the same type.

Enables MCP servers to control which tools are visible to which Views via tool metadata and visibility rules. Tools can be marked as hidden, visible only in certain display modes, or visible only to specific View types. The host respects these visibility rules when forwarding requests and rendering UIs. Views can query the host for available tools and their visibility status, allowing them to conditionally render UI elements based on tool availability. This enables servers to provide different tool sets to different Views without duplicating tool definitions.