iframe-sandboxed ui rendering with postmessage json-rpc protocol
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.
Unique: Implements a three-party architecture (Server → Host → View) with explicit capability negotiation and tool-UI linkage via ui:// URI scheme, rather than generic iframe embedding. Uses JSON-RPC 2.0 over postMessage with strict message validation and initialization handshake, ensuring both parties agree on supported capabilities before communication begins.
vs alternatives: More secure and standardized than ad-hoc iframe communication because it enforces protocol versioning, capability negotiation, and explicit tool linking rather than relying on window.parent references or global message listeners.
ui resource declaration and server-side tool-ui linkage
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.
Unique: Uses a declarative ui:// URI scheme with tool metadata linking rather than imperative iframe creation. Servers declare resources once; hosts handle fetching, sandboxing, and lifecycle management. This separates concerns: servers focus on tool logic and UI content, hosts handle rendering and security.
vs alternatives: Cleaner than embedding UI URLs in tool responses because the UI is declared upfront with versioning support, allowing hosts to pre-fetch and cache resources, and enabling capability negotiation before tool execution.
logging and message event streaming from views to host
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.
Unique: Provides structured logging via JSON-RPC notifications with severity levels and event data, rather than relying on console.log which may not be visible in sandboxed iframes. One-way notifications reduce latency compared to request-response logging.
vs alternatives: More reliable than console.log because messages are guaranteed to reach the host via the JSON-RPC protocol. More structured than string-based logging because it supports severity levels and arbitrary event data.
server sdk helpers for ui resource registration and tool metadata
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.
Unique: Provides language-specific helper functions (TypeScript and Python) that abstract away the details of resource registration and tool metadata construction. Helpers validate declarations against the SEP-1865 specification and provide TypeScript types for compile-time checking.
vs alternatives: More convenient than manual resource object construction because helpers handle validation and type checking. More maintainable than hardcoded resource declarations because helpers can be updated to support new specification versions.
protocol specification and message schema validation
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.
Unique: Provides a formal, versioned protocol specification (SEP-1865) with JSON Schema definitions and generated TypeScript types, rather than relying on informal documentation or examples. Schema validation is built into the SDK, enabling both compile-time and runtime checking.
vs alternatives: More rigorous than informal protocol documentation because it uses JSON Schema for formal specification. More maintainable than hardcoded message handling because schema changes can be applied consistently across the SDK.
example gallery and scaffolding tools for rapid prototyping
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.
Unique: Provides both production-ready examples and AI agent skills for scaffolding, enabling developers to learn from working code and rapidly generate new projects. Examples cover diverse domains (maps, PDFs, monitoring) rather than generic hello-world patterns.
vs alternatives: More practical than documentation-only approaches because developers can run and modify working examples. More efficient than starting from scratch because scaffolding tools generate boilerplate automatically.
app class lifecycle management with server tool invocation
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.
Unique: Implements a Promise-based async tool calling API with automatic request ID generation and response correlation, rather than callback-based patterns. The App class handles the full lifecycle from initialization handshake through tool invocation to cleanup, abstracting away JSON-RPC details from the developer.
vs alternatives: Simpler than raw postMessage usage because it provides typed tool calling, automatic error handling, and lifecycle hooks. More flexible than framework-specific solutions because it works with vanilla JavaScript, React, Vue, or any framework.
react integration with useapp and useappbridge hooks
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.
Unique: Provides React hooks that abstract away postMessage and JSON-RPC details while maintaining full TypeScript type safety for tool schemas. The hooks handle initialization timing and cleanup automatically, reducing boilerplate compared to manual App class usage.
vs alternatives: More idiomatic for React developers than imperative App class usage because it follows React hooks patterns. Provides better TypeScript support than generic postMessage wrappers because it can infer tool parameter types from MCP server schemas.
+6 more capabilities