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
For a View or host:
```bash
npm install -S @modelcontextprotocol/ext-apps \
@modelcontextprotocol/client@2.0.0-beta.4 \
@modelcontextprotocol/server@2.0.0-beta.4 \
@modelcontextprotocol/core@2.0.0-beta.4 \
@modelcontextprotocol/client@2.0.0-beta.5 \
@modelcontextprotocol/core@2.0.0-beta.5 \
zod@^4.2.0
```
This release uses the split base MCP SDK v2 packages. Install all three at the
exact published beta.4 version so the Apps SDK and your MCP client/server share
one compatible protocol implementation.
For an MCP server:
```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
[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.
- **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`
subclasses the base MCP SDK `Server` for the inner iframe channel, while a
separate outer `Client` connects the Host to the actual MCP Server. Keeping
those two connections separate prevents iframe negotiation and capabilities
from leaking into the server connection.
The View's `App` and the Host's `AppBridge` both subclass the base MCP SDK's
public `Protocol` for the iframe channel. A separate outer `Client` connects
the Host to the actual MCP Server. Keeping those two connections separate
preserves the Apps-only iframe handshake and prevents iframe capabilities from
leaking into the server connection.
## Lifecycle

2
docs/quickstart.md
View file

@ -37,7 +37,7 @@ Install the dependencies you'll need:
```bash
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
```

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
```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
```

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
```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
```

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:
```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
```

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`}).
*
* `AppBridge` extends the base MCP SDK's public `Server` class and acts as a proxy between
* the host application and a view running in an iframe. When an MCP client
* is provided to the constructor, it automatically forwards MCP server capabilities
* (tools, resources, prompts) to the view. It also handles the initialization
* handshake.
* `AppBridge` extends the base MCP SDK's public `Protocol` class and acts as a
* proxy between the host application and a view running in an iframe. When a
* separate MCP client is provided to the constructor, it automatically forwards
* MCP server capabilities (tools, resources, prompts) to the view. It also
* handles the Apps initialization handshake.
*
* ## 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
* 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
*
@ -314,9 +315,11 @@ export type AppEventMap = {
*
* ## 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
* - `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)
* - `removeEventListener()` - Remove a previously added listener
*