modelcontextprotocol/ext-apps
Watch
1
0
Fork
You've already forked ext-apps
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Mirror of https://github.com/modelcontextprotocol/ext-apps — Official repo for spec & SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers
276 commits 1 branch 37 tags 25 MiB
  • TypeScript 76.4%
  • MDX 19.3%
  • JavaScript 4.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Jonathan Hefner 2a3c2ce034 Add "How It Works" section to README 
Provides a concise 4-step overview of the MCP Apps architecture:
tool call → `ui://` resource → sandboxed iframe → bidirectional
communication via notifications.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-08 13:58:34 -06:00
.github/workflows Fix build errors in examples (#180) 2025-12-18 11:17:23 +00:00
.husky Add pre-commit check for private registry URLs in package-lock.json (#133) 2025-12-16 13:41:50 +00:00
docs docs: fix tsc command to use tsconfig.json (#188) 2025-12-20 17:39:34 +02:00
examples Add basic-server-* examples for Vue, Svelte, Preact, and Solid (#141) 2026-01-08 18:44:36 +00:00
scripts chore: bump to 0.2.2 + make Zod schemas version-agnostic (v3.25+/v4) (#178) 2025-12-17 20:55:59 +00:00
specification/draft Remove viewport 2025-12-31 21:36:29 -08:00
src Make ui.resourceUri optional (for tools that just need visibility) (#210) 2026-01-08 17:05:00 +00:00
tests/e2e Add basic-server-* examples for Vue, Svelte, Preact, and Solid (#141) 2026-01-08 18:44:36 +00:00
.gitattributes fix: Windows compatibility - bun as optional dep, cross-env for examples (#145) 2025-12-16 14:07:38 +00:00
.gitignore tests: add Playwright E2E tests with screenshot golden testing (+ fix examples session handling) (#115) 2025-12-13 20:57:27 +00:00
.prettierignore Add basic-server-* examples for Vue, Svelte, Preact, and Solid (#141) 2026-01-08 18:44:36 +00:00
.prettierrc.json api: optional Client in AppBridge (allow custom forwarding), better protocol types (AppRequest, AppNotification, AppResult) (#146) 2025-12-13 21:07:13 +00:00
build.bun.ts feat: make MCP SDK a peer dependency (#168) 2025-12-16 22:09:59 +00:00
CONTRIBUTING.md tests: add Playwright E2E tests with screenshot golden testing (+ fix examples session handling) (#115) 2025-12-13 20:57:27 +00:00
LICENSE add license (#96) 2025-12-08 21:51:19 +01:00
package-lock.json Add basic-server-* examples for Vue, Svelte, Preact, and Solid (#141) 2026-01-08 18:44:36 +00:00
package.json Add npm start alias for examples:start (#183) 2025-12-19 11:36:02 +00:00
playwright.config.ts fix: ensure E2E screenshot tests work consistently across CI and local (#150) 2025-12-15 15:12:36 +00:00
README.md Add "How It Works" section to README 2026-01-08 13:58:34 -06:00
tsconfig.json Initial commit 2025-11-21 11:56:27 +00:00
typedoc.json Add Quickstart guide for building MCP Apps 2025-12-04 14:28:55 -06:00

README.md

@modelcontextprotocol/ext-apps

npm version API Documentation

This repo contains the SDK and specification for MCP Apps Extension (SEP-1865).

MCP Apps are a proposed standard inspired by MCP-UI and OpenAI's Apps SDK to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots.

How It Works

MCP Apps extend the Model Context Protocol to let servers deliver interactive UIs to MCP hosts. Here's how it works:

  1. Tool call — The LLM calls a tool on your server
  2. UI Resource — The tool's definition links to a predeclared ui:// resource containing its HTML interface
  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

This enables dashboards, forms, visualizations, and other rich experiences inside chat interfaces.

Overview

This SDK serves two audiences:

App Developers

Build interactive UIs that run inside MCP-enabled chat clients.

  • SDK for Apps: @modelcontextprotocol/ext-apps — API Docs
  • React hooks: @modelcontextprotocol/ext-apps/react — API Docs

Host Developers

Embed and communicate with MCP Apps in your chat application.

  • SDK for Hosts: @modelcontextprotocol/ext-apps/app-bridge — API Docs

There's no supported host implementation in this repo (beyond the examples/basic-host example).

We have contributed a tentative implementation of hosting / iframing / sandboxing logic to the MCP-UI repository, and expect OSS clients may use it, while other clients might roll their own hosting logic.

Installation

npm install -S @modelcontextprotocol/ext-apps

Or edit your package.json manually:

{
  "dependencies": {
    "@modelcontextprotocol/ext-apps": "^0.0.1"
  }
}

Examples

Start with these foundational examples to learn the SDK:

The examples/ directory contains additional demo apps showcasing real-world use cases.

To run all examples together:

npm install
npm start

Then open http://localhost:8080/.

Resources