853c9f749c
Guide: name @modelcontextprotocol/express in the server-author row, say the two SDKs share no types rather than "do not interoperate" (they speak the same wire protocol), note zod 4.0/4.1 lack ~standard.jsonSchema, list the full 1.x-shaped extra, cover tool callbacks in the handler-context bullet, document that the double-registration guard now covers the base Protocol's notifications/progress and notifications/cancelled handlers, mention ResourceNotFoundError, add the Express row to the import map, and add a "What stays the same" section. The @deprecated tag on the legacy setRequestHandler / setNotificationHandler overload sat on the parameter inside an intersection type, which TypeScript does not report. The overload now comes from LegacyRequestHandlerSetter / LegacyNotificationHandlerSetter, named types with a documented call signature, so editors flag the 1.x call and not the 2.x forms. README links to the quickstart use the lowercase slug typedoc emits.
284 lines
18 KiB
Markdown
284 lines
18 KiB
Markdown
<!-- LOGO -->
|
|
<div align="center">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="media/mcp-white.svg">
|
|
<source media="(prefers-color-scheme: light)" srcset="media/mcp.svg">
|
|
<img src="media/mcp.svg" alt="MCP Apps" width="128">
|
|
</picture>
|
|
<h1>MCP Apps</h1>
|
|
<p>
|
|
Build interactive UIs for MCP tools — charts, forms, dashboards — that render inline in Claude, ChatGPT and any other compliant chat client.
|
|
<br /><br />
|
|
<a href="#why-mcp-apps">Why</a>
|
|
·
|
|
<a href="https://apps.extensions.modelcontextprotocol.io/api/documents/quickstart.html">Quickstart</a>
|
|
·
|
|
<a href="https://apps.extensions.modelcontextprotocol.io/api/">API Docs</a>
|
|
·
|
|
<a href="https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx">Spec</a>
|
|
·
|
|
<a href="CONTRIBUTING.md">Contributing</a>
|
|
</p>
|
|
</div>
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/modelcontextprotocol/ext-apps/actions/workflows/ci.yml"><img src="https://github.com/modelcontextprotocol/ext-apps/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
|
|
<a href="https://www.npmjs.com/package/@modelcontextprotocol/ext-apps"><img src="https://img.shields.io/npm/v/@modelcontextprotocol/ext-apps.svg" alt="npm version"></a>
|
|
<a href="https://www.npmjs.com/package/@modelcontextprotocol/ext-apps"><img src="https://img.shields.io/npm/dm/@modelcontextprotocol/ext-apps.svg" alt="npm downloads"></a>
|
|
<a href="https://github.com/modelcontextprotocol/ext-apps"><img src="https://img.shields.io/github/stars/modelcontextprotocol/ext-apps" alt="GitHub stars"></a>
|
|
<a href="https://apps.extensions.modelcontextprotocol.io/api/"><img src="https://img.shields.io/badge/docs-API%20Reference-blue" alt="API Documentation"></a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img src="media/excalidraw.gif" alt="MCP Apps demo" width="600">
|
|
<br><em>Excalidraw built with MCP Apps, running in Claude</em>
|
|
</p>
|
|
|
|
## Table of Contents
|
|
|
|
- [Build with Agent Skills](#build-with-agent-skills)
|
|
- [Supported Clients](#supported-clients)
|
|
- [Why MCP Apps?](#why-mcp-apps)
|
|
- [How It Works](#how-it-works)
|
|
- [Getting Started](#getting-started)
|
|
- [Using the SDK](#using-the-sdk)
|
|
- [Examples](#examples)
|
|
- [Specification](#specification)
|
|
- [Resources](#resources)
|
|
- [Contributing](#contributing)
|
|
|
|
## Build with Agent Skills
|
|
|
|
The fastest way to build an MCP App is to let your AI coding agent do it. This
|
|
repo ships four [Agent Skills](https://agentskills.io/) — install them once,
|
|
then just ask:
|
|
|
|
| Skill | What it does | Try it |
|
|
| --------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------- |
|
|
| [`create-mcp-app`](./plugins/mcp-apps/skills/create-mcp-app/SKILL.md) | Scaffolds a new MCP App with an interactive UI from scratch | _"Create an MCP App"_ |
|
|
| [`migrate-oai-app`](./plugins/mcp-apps/skills/migrate-oai-app/SKILL.md) | Converts an existing OpenAI App to use MCP Apps | _"Migrate from OpenAI Apps SDK"_ |
|
|
| [`add-app-to-server`](./plugins/mcp-apps/skills/add-app-to-server/SKILL.md) | Adds interactive UI to an existing MCP server's tools | _"Add UI to my MCP server"_ |
|
|
| [`convert-web-app`](./plugins/mcp-apps/skills/convert-web-app/SKILL.md) | Turns an existing web app into a hybrid web + MCP App | _"Add MCP App support to my web app"_ |
|
|
|
|
### Install the Skills
|
|
|
|
**Claude Code** — install via the plugin marketplace:
|
|
|
|
```
|
|
/plugin marketplace add modelcontextprotocol/ext-apps
|
|
/plugin install mcp-apps@modelcontextprotocol-ext-apps
|
|
```
|
|
|
|
**Other agents** — any AI coding agent that supports
|
|
[Agent Skills](https://agentskills.io/) can use these skills. See the
|
|
[agent skills guide](./docs/agent-skills.md) for manual installation
|
|
instructions.
|
|
|
|
Once installed, verify by asking your agent _"What skills do you have?"_ — you
|
|
should see `create-mcp-app`, `migrate-oai-app`, `add-app-to-server`, and
|
|
`convert-web-app` in the list. Then just ask it to create or migrate an app and
|
|
it will guide you through the rest.
|
|
|
|
## Supported Clients
|
|
|
|
<p align="center">
|
|
<a href="https://developers.openai.com/apps-sdk/mcp-apps-in-chatgpt/"><img src="https://img.shields.io/badge/ChatGPT-docs-74aa9c?logo=openai&logoColor=white" alt="ChatGPT"></a>
|
|
<a href="https://claude.com/docs/connectors/building/mcp-apps/getting-started"><img src="https://img.shields.io/badge/Claude-docs-d97706?logo=claude&logoColor=white" alt="Claude"></a>
|
|
<a href="https://code.visualstudio.com/blogs/2026/01/26/mcp-apps-support"><img src="https://img.shields.io/badge/VS_Code-docs-007ACC?logo=visualstudiocode&logoColor=white" alt="VS Code"></a>
|
|
<a href="https://block.github.io/goose/docs/tutorials/building-mcp-apps/"><img src="https://img.shields.io/badge/Goose-docs-000000?logo=goose&logoColor=white" alt="Goose"></a>
|
|
<a href="https://learning.postman.com/docs/postman-ai/mcp-requests/interact"><img src="https://img.shields.io/badge/Postman-docs-FF6C37?logo=postman&logoColor=white" alt="Postman"></a>
|
|
<a href="https://www.mcpjam.com/blog/mcp-apps-example"><img src="https://img.shields.io/badge/MCPJam-docs-8B5CF6" alt="MCPJam"></a>
|
|
<a href="https://manufact.com/inspector"><img src="https://img.shields.io/badge/mcp--use-inspector-E5F3FD" alt="mcp-use"></a>
|
|
<a href="https://docs.alpic.ai/distribution/playground"><img src="https://img.shields.io/badge/Alpic-playground-E90060?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAMAAABHPGVmAAAAKlBMVEUKDhz%2F%2F%2F%2BjpaogJDFBRE%2Fw8PHHyMvh4eNmaHF1d4CUlpuFho2ztLhWWWP5YkbJAAAACXBIWXMAAAsTAAALEwEAmpwYAAAB1klEQVR42u2Y0ZKDIAxFBQQF8f9%2FdyW7dhAu7U7Iy87mzvShGfXU3CTGLotKpVKpVCqV6h%2FI2VuxfF3tUwcdVEccA2LNS%2BWCq2mUykG%2BCtg5iNmv76mllOApCPHrFQgNxJf8HHIQs10XdFtDKcEKPQ0x4brg6htKWGr0PIR8jq0tj4oQgJiIzD8rtATErMAWMj%2FxIYcBPjuPgoENcW3Jks%2BdLeXS32jLmise%2BZxQ8GRD%2BkkCbSlByi0Pgm3p0P6nJ1meXJ%2F8K1tKo7qUOFM4wdxEMMS4iSp9sqFJQrZ4hOZBTEa5gbaQ%2BTwI%2FcCu8TOq482xIWZkSx8MfAi0xcOEJTZkULKohXjm29epGU2SIGK%2BfT9J%2Bjre%2BRBYsiUYBSHkaEI2B0EInRx%2BkbApiB89EaMgBNdx7u5vDoJH79ne3yQElqxvEzYLKY%2Bl81PCZiFUsvlDwqYhw80uSkJg4z8Ttsss3OltwgQgMGGPlpSAwITVM0wCgius6iARCGzJcn%2BHJCSMXraCIATPsPW2SggCh364a1sIgveUew%2BTgtBGsuE9zDspyLBZ3M5aVCOCUDFlqXUbrm8j7%2FnvJ2B9G3kf%2BZBlt0iu%2Fr%2BNxHqRU6lUKpVKpVL9UX0BOrAPfcbTY8UAAAAASUVORK5CYII%3D" alt="Alpic Playground"></a>
|
|
</p>
|
|
|
|
> [!NOTE]
|
|
> MCP Apps is an extension to the
|
|
> [core MCP specification](https://modelcontextprotocol.io/specification). Host
|
|
> support varies — see the
|
|
> [clients page](https://modelcontextprotocol.io/clients) for the full list.
|
|
|
|
## Why MCP Apps?
|
|
|
|
MCP tools return text and structured data. That works for many cases, but not
|
|
when you need an interactive UI, like a chart, form, design canvas or video player.
|
|
|
|
MCP Apps provide a standardized way to deliver interactive UIs from MCP servers.
|
|
Your UI renders inline in the conversation, in context, in any compliant host.
|
|
|
|
## How It Works
|
|
|
|
MCP Apps extend the Model Context Protocol by letting tools declare UI
|
|
resources:
|
|
|
|
1. **Tool definition** — Your tool declares a `ui://` resource containing its
|
|
HTML interface
|
|
2. **Tool call** — The LLM calls the tool on your server
|
|
3. **Host renders** — The host fetches the resource and displays it in a
|
|
sandboxed iframe
|
|
4. **Bidirectional communication** — The host passes tool data to the UI via
|
|
notifications, and the UI can call other tools through the host
|
|
|
|
## Getting Started
|
|
|
|
Requires Node.js 20+. The base MCP SDK packages are `^2.0.0` peers of
|
|
`ext-apps` (`@modelcontextprotocol/core` is a required peer that `client` already depends on, so npm installs it for you).
|
|
|
|
For a View or host:
|
|
|
|
```bash
|
|
npm install -S @modelcontextprotocol/ext-apps \
|
|
@modelcontextprotocol/client@^2.0.0 \
|
|
zod@^4.2.0
|
|
```
|
|
|
|
For an MCP server, add the server package (and, for HTTP transports, the Node
|
|
and Express adapters):
|
|
|
|
```bash
|
|
npm install -S @modelcontextprotocol/ext-apps \
|
|
@modelcontextprotocol/client@^2.0.0 \
|
|
@modelcontextprotocol/server@^2.0.0 \
|
|
@modelcontextprotocol/node@^2.0.0 \
|
|
@modelcontextprotocol/express@^2.0.0 \
|
|
zod@^4.2.0
|
|
```
|
|
|
|
The wire protocol is unchanged between `ext-apps` 1.x and 2.x: a 2.x View works
|
|
in a 1.x host and a 2.x host renders 1.x Views. See the
|
|
[migration guide](https://apps.extensions.modelcontextprotocol.io/api/documents/migrate-to-v2.html)
|
|
when upgrading from 1.x.
|
|
|
|
**New here?** Start with the
|
|
[Quickstart Guide](https://apps.extensions.modelcontextprotocol.io/api/documents/quickstart.html)
|
|
to build your first MCP App.
|
|
|
|
## Using the SDK
|
|
|
|
The SDK serves three roles: app developers building interactive Views, host
|
|
developers embedding those Views, and MCP server authors registering tools with
|
|
UI metadata.
|
|
|
|
| Package | Purpose | Docs |
|
|
| ------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
| `@modelcontextprotocol/ext-apps` | Build interactive Views (App class, PostMessageTransport) | [API Docs →](https://apps.extensions.modelcontextprotocol.io/api/modules/app.html) |
|
|
| `@modelcontextprotocol/ext-apps/react` | React hooks for Views (useApp, useHostStyles, etc.) | [API Docs →](https://apps.extensions.modelcontextprotocol.io/api/modules/_modelcontextprotocol_ext-apps_react.html) |
|
|
| `@modelcontextprotocol/ext-apps/app-bridge` | Embed and communicate with Views in your chat client | [API Docs →](https://apps.extensions.modelcontextprotocol.io/api/modules/app-bridge.html) |
|
|
| `@modelcontextprotocol/ext-apps/server` | Register tools and resources on your MCP server | [API Docs →](https://apps.extensions.modelcontextprotocol.io/api/modules/server-helpers.html) |
|
|
|
|
There's no _supported_ host implementation in this repo (beyond the
|
|
[examples/basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host)
|
|
example).
|
|
|
|
The [MCP-UI](https://github.com/idosal/mcp-ui) client SDK offers a
|
|
fully-featured MCP Apps framework used by a few hosts. Clients may choose to use
|
|
it or roll their own implementation.
|
|
|
|
## Examples
|
|
|
|
The
|
|
[`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples)
|
|
directory contains demo apps showcasing real-world use cases.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
| | | |
|
|
|:---:|:---:|:---:|
|
|
| [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/threejs-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server) |
|
|
| [**Map**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) | [**Three.js**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/threejs-server) | [**ShaderToy**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server) |
|
|
| [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/sheet-music-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/wiki-explorer-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/cohort-heatmap-server) |
|
|
| [**Sheet Music**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/sheet-music-server) | [**Wiki Explorer**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/wiki-explorer-server) | [**Cohort Heatmap**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/cohort-heatmap-server) |
|
|
| [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/scenario-modeler-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/budget-allocator-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/customer-segmentation-server) |
|
|
| [**Scenario Modeler**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/scenario-modeler-server) | [**Budget Allocator**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/budget-allocator-server) | [**Customer Segmentation**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/customer-segmentation-server) |
|
|
| [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/system-monitor-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/transcript-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/video-resource-server) |
|
|
| [**System Monitor**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/system-monitor-server) | [**Transcript**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/transcript-server) | [**Video Resource**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/video-resource-server) |
|
|
| [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server) | [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/say-server) |
|
|
| [**PDF Server**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server) | [**QR Code (Python)**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server) | [**Say Demo**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/say-server) |
|
|
|
|
### Starter Templates
|
|
|
|
| | |
|
|
|:---:|:---|
|
|
| [](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) | The same app built with different frameworks — pick your favorite!<br><br>[React](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) · [Vue](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vue) · [Svelte](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-svelte) · [Preact](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-preact) · [Solid](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-solid) · [Vanilla JS](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) |
|
|
<!-- prettier-ignore-end -->
|
|
|
|
### Running the Examples
|
|
|
|
#### With basic-host
|
|
|
|
To run all examples locally using
|
|
[basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host)
|
|
(the reference host implementation included in this repo):
|
|
|
|
```bash
|
|
git clone https://github.com/modelcontextprotocol/ext-apps.git
|
|
cd ext-apps
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
Then open http://localhost:8080/.
|
|
|
|
#### With MCP Clients
|
|
|
|
Every Node.js example is published as `@modelcontextprotocol/server-<name>`. To
|
|
add one to an MCP client that supports stdio (Claude Desktop, VS Code, etc.),
|
|
use this pattern:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"<name>": {
|
|
"command": "npx",
|
|
"args": ["-y", "@modelcontextprotocol/server-<name>", "--stdio"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
For example, to add the map server: `@modelcontextprotocol/server-map`. The
|
|
Python examples (`qr-server`, `say-server`) use `uv run` instead — see their
|
|
READMEs for details.
|
|
|
|
#### Local Development
|
|
|
|
To test local modifications with an MCP client, clone the repo, install, then
|
|
point your client at a local build:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"<name>": {
|
|
"command": "bash",
|
|
"args": [
|
|
"-c",
|
|
"cd ~/code/ext-apps/examples/<name>-server && npm run build >&2 && node dist/index.js --stdio"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Specification
|
|
|
|
<div align="center">
|
|
|
|
| Version | Status | Link |
|
|
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **2026-01-26** | Stable | [specification/2026-01-26/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) |
|
|
| **draft** | Development | [specification/draft/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) |
|
|
|
|
</div>
|
|
|
|
## Resources
|
|
|
|
- [Quickstart Guide](https://apps.extensions.modelcontextprotocol.io/api/documents/quickstart.html)
|
|
- [API Documentation](https://apps.extensions.modelcontextprotocol.io/api/)
|
|
- [Specification (2026-01-26)](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)
|
|
([Draft](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx))
|
|
- [SEP-1865 Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
|
|
guidelines on how to get started, submit pull requests, and report issues.
|