ext-apps

ext-apps provides tooling and libraries to build and render interactive MCP UIs (views) directly inside chat hosts like Claude, ChatGPT, and other compliant clients. This MCP App framework supplies components for building App classes, post-message transport, and React-based hooks to manage host styling and UI embedding. Developers can scaffold new MCP Apps, migrate existing OpenAI Apps, or add UIs to existing MCP servers using a consistent kit of skills and APIs. To use it, install the package in your project, register your app definitions and UI resources via the SDK, and rely on the host to render the UI resources declared by your tools. The server-side aspect handles tool definitions and their associated ui:// resources, while the UI runs inside the host sandbox and communicates back and forth with your server through the provided transport layer.

Typical workflows include building an interactive Excalidraw-like canvas, charts, or forms as MCP Apps, then attaching these UIs to your MCP server’s tools. The SDK exposes an app class and a bridge module to embed and communicate with the UI, plus React hooks for building and styling the Views. Hosts render the declared UI resources, fetch them via the tool calls, and provide bidirectional messaging to update the UI state.

Prerequisites:

• Node.js (LTS) and npm/yarn installed on your development machine
• Basic knowledge of MCP and creating tools with UI metadata

Installation steps:

1. Create your project or navigate to your MCP server project directory
2. Install the ext-apps package:

npm install -S @modelcontextprotocol/ext-apps

3. If you plan to use React hooks and app-bridge components, install the related packages (examples):

npm install -S @modelcontextprotocol/ext-apps @modelcontextprotocol/ext-apps/react @modelcontextprotocol/ext-apps/app-bridge

4. Initialize your MCP App definitions and UI resources following the Quickstart guide linked in the README
5. Start or deploy your MCP server according to your project setup (e.g., node server.js or your existing startup script)

Notes:

• This package is published as an npm module; you typically integrate it into a Node.js project that serves MCP Tools and UI metadata.
• Refer to the API docs in the repository for details on App class usage and transport interfaces.

Tips and common issues:

• Ensure your UI resources use the ui:// scheme and are declared for each tool you expose via the server.
• When integrating with hosts (Claude, ChatGPT), validate that your tool payloads and UI updates conform to the host’s sandboxing and notification model.
• If you upgrade the ext-apps package, review breaking changes in the API docs and adjust your App class usage accordingly.
• Environment variables you might encounter include endpoints for UI resources, authentication tokens for any external services, and host-specific configuration; keep them in a .env file or your deployment environment as appropriate.