modelcontextprotocol/ext-apps
Watch
1
0
Fork
You've already forked ext-apps
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: align Protocol and role-specific setup

Browse source
This commit is contained in:
Enrico 2026-07-22 15:37:22 -07:00
commit c847bc0887
8 changed files with 35 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

22
README.md
View file

@ -121,17 +121,27 @@ resources:
## Getting Started ## Getting Started
For a View or host:
```bash ```bash
npm install -S @modelcontextprotocol/ext-apps \ npm install -S @modelcontextprotocol/ext-apps \
@modelcontextprotocol/client@2.0.0-beta.4 \ @modelcontextprotocol/client@2.0.0-beta.5 \
@modelcontextprotocol/server@2.0.0-beta.4 \ @modelcontextprotocol/core@2.0.0-beta.5 \
@modelcontextprotocol/core@2.0.0-beta.4 \
zod@^4.2.0 zod@^4.2.0
``` ```
This release uses the split base MCP SDK v2 packages. Install all three at the For an MCP server:
exact published beta.4 version so the Apps SDK and your MCP client/server share
one compatible protocol implementation. ```bash
npm install -S @modelcontextprotocol/ext-apps \
@modelcontextprotocol/server@2.0.0-beta.5 \
@modelcontextprotocol/core@2.0.0-beta.5 \
zod@^4.2.0
```
Applications that implement both roles should install both `client` and
`server`. Keep all installed base MCP SDK packages on the exact same published
beta so they share one compatible protocol implementation.
**New here?** Start with the **New here?** Start with the
[Quickstart Guide](https://apps.extensions.modelcontextprotocol.io/api/documents/Quickstart.html) [Quickstart Guide](https://apps.extensions.modelcontextprotocol.io/api/documents/Quickstart.html)

10
docs/overview.md
View file

@ -56,11 +56,11 @@ flowchart LR
- **Host** — The chat client (e.g., Claude Desktop) that connects to servers, embeds Views in iframes, and proxies communication between them. - **Host** — The chat client (e.g., Claude Desktop) that connects to servers, embeds Views in iframes, and proxies communication between them.
- **View** — The UI running inside a sandboxed iframe. It receives tool data from the Host and can call server tools or send messages back to the chat. - **View** — The UI running inside a sandboxed iframe. It receives tool data from the Host and can call server tools or send messages back to the chat.
The View's `App` subclasses the base MCP SDK `Client`. The Host's `AppBridge` The View's `App` and the Host's `AppBridge` both subclass the base MCP SDK's
subclasses the base MCP SDK `Server` for the inner iframe channel, while a public `Protocol` for the iframe channel. A separate outer `Client` connects
separate outer `Client` connects the Host to the actual MCP Server. Keeping the Host to the actual MCP Server. Keeping those two connections separate
those two connections separate prevents iframe negotiation and capabilities preserves the Apps-only iframe handshake and prevents iframe capabilities from
from leaking into the server connection. leaking into the server connection.
## Lifecycle ## Lifecycle

2
docs/quickstart.md
View file

@ -37,7 +37,7 @@ Install the dependencies you'll need:
```bash ```bash
npm init -y npm init -y
npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.4 @modelcontextprotocol/core@2.0.0-beta.4 @modelcontextprotocol/server@2.0.0-beta.4 @modelcontextprotocol/node@2.0.0-beta.4 @modelcontextprotocol/express@2.0.0-beta.4 zod@^4.2.0 express cors npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.5 @modelcontextprotocol/core@2.0.0-beta.5 @modelcontextprotocol/server@2.0.0-beta.5 @modelcontextprotocol/node@2.0.0-beta.5 @modelcontextprotocol/express@2.0.0-beta.5 zod@^4.2.0 express cors
npm install -D typescript vite vite-plugin-singlefile @types/express @types/cors @types/node tsx concurrently cross-env npm install -D typescript vite vite-plugin-singlefile @types/express @types/cors @types/node tsx concurrently cross-env
``` ```

2
plugins/mcp-apps/skills/add-app-to-server/SKILL.md
View file

@ -77,7 +77,7 @@ Before writing any code, analyze the server's existing tools and determine which
## Step 2: Add Dependencies ## Step 2: Add Dependencies
```bash ```bash
npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.4 @modelcontextprotocol/core@2.0.0-beta.4 @modelcontextprotocol/server@2.0.0-beta.4 zod@^4.2.0 npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.5 @modelcontextprotocol/core@2.0.0-beta.5 @modelcontextprotocol/server@2.0.0-beta.5 zod@^4.2.0
npm install -D vite vite-plugin-singlefile npm install -D vite vite-plugin-singlefile
``` ```

2
plugins/mcp-apps/skills/convert-web-app/SKILL.md
View file

@ -115,7 +115,7 @@ Create a new MCP server with tool and resource registration. This wraps the exis
### Dependencies ### Dependencies
```bash ```bash
npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.4 @modelcontextprotocol/core@2.0.0-beta.4 @modelcontextprotocol/server@2.0.0-beta.4 zod@^4.2.0 npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.5 @modelcontextprotocol/core@2.0.0-beta.5 @modelcontextprotocol/server@2.0.0-beta.5 zod@^4.2.0
npm install -D tsx vite vite-plugin-singlefile npm install -D tsx vite vite-plugin-singlefile
``` ```

2
plugins/mcp-apps/skills/create-mcp-app/SKILL.md
View file

@ -110,7 +110,7 @@ See `/tmp/mcp-ext-apps/docs/patterns.md` for detailed recipes:
**Always** use `npm install` to add dependencies rather than manually writing version numbers: **Always** use `npm install` to add dependencies rather than manually writing version numbers:
```bash ```bash
npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.4 @modelcontextprotocol/core@2.0.0-beta.4 @modelcontextprotocol/server@2.0.0-beta.4 @modelcontextprotocol/node@2.0.0-beta.4 @modelcontextprotocol/express@2.0.0-beta.4 zod@^4.2.0 express cors npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.5 @modelcontextprotocol/core@2.0.0-beta.5 @modelcontextprotocol/server@2.0.0-beta.5 @modelcontextprotocol/node@2.0.0-beta.5 @modelcontextprotocol/express@2.0.0-beta.5 zod@^4.2.0 express cors
npm install -D typescript vite vite-plugin-singlefile concurrently cross-env @types/node @types/express @types/cors npm install -D typescript vite vite-plugin-singlefile concurrently cross-env @types/node @types/express @types/cors
``` ```

10
src/app-bridge.ts
View file

@ -241,11 +241,11 @@ export type AppBridgeEventMap = {
/** /**
* Host-side bridge for communicating with a single View ({@link app!App `App`}). * Host-side bridge for communicating with a single View ({@link app!App `App`}).
* *
* `AppBridge` extends the base MCP SDK's public `Server` class and acts as a proxy between * `AppBridge` extends the base MCP SDK's public `Protocol` class and acts as a
* the host application and a view running in an iframe. When an MCP client * proxy between the host application and a view running in an iframe. When a
* is provided to the constructor, it automatically forwards MCP server capabilities * separate MCP client is provided to the constructor, it automatically forwards
* (tools, resources, prompts) to the view. It also handles the initialization * MCP server capabilities (tools, resources, prompts) to the view. It also
* handshake. * handles the Apps initialization handshake.
* *
* ## Architecture * ## Architecture
* *

7
src/app.ts
View file

@ -297,7 +297,8 @@ export type AppEventMap = {
* *
* The `App` class provides a framework-agnostic way to build interactive MCP Apps * The `App` class provides a framework-agnostic way to build interactive MCP Apps
* that run inside host applications. It extends the base MCP SDK's public * that run inside host applications. It extends the base MCP SDK's public
* `Client` class and adds the Apps handshake, lifecycle, and high-level APIs. * `Protocol` class, composes an {@link EventDispatcher}, and adds the Apps
* handshake, lifecycle, and high-level APIs.
* *
* ## Architecture * ## Architecture
* *
@ -314,9 +315,11 @@ export type AppEventMap = {
* *
* ## Protocol and event methods * ## Protocol and event methods
* *
* As a subclass of the base MCP SDK's `Client`, `App` provides: * From the base MCP SDK's `Protocol`, `App` provides:
* - `setRequestHandler()` - Register handlers for requests from host * - `setRequestHandler()` - Register handlers for requests from host
* - `setNotificationHandler()` - Register handlers for notifications from host * - `setNotificationHandler()` - Register handlers for notifications from host
*
* From its composed {@link EventDispatcher}, `App` also provides:
* - `addEventListener()` - Append a listener for a notification event (multi-listener) * - `addEventListener()` - Append a listener for a notification event (multi-listener)
* - `removeEventListener()` - Remove a previously added listener * - `removeEventListener()` - Remove a previously added listener
* *