Skip to content

Use public Protocol with isolated SDK role peers #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
tonxxd wants to merge 6 commits into
base: codex/mcp-sdk-v2-beta4-migration
Choose a base branch
from
Draft

Use public Protocol with isolated SDK role peers #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ccae093
Port App and AppBridge to the public v2 Protocol base class
felixweinberger Jul 15, 2026
43eed45
Point SDK packages at the pkg.pr.new preview of typescript-sdk#2501
felixweinberger Jul 15, 2026
7664bb1
test: isolate optional SDK role dependencies
tonxxd Jul 20, 2026
e7ffe7c
chore: update MCP SDK packages to beta.5
tonxxd Jul 22, 2026
c847bc0
docs: align Protocol and role-specific setup
tonxxd Jul 22, 2026
4e4886c
chore: update MCP SDK packages to stable 2.0.0
tonxxd Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,8 @@ rm -fR package-lock.json node_modules && \

### Key Source Files

- `src/app.ts` - `App` subclasses the base MCP SDK `Client`, handles View initialization, tool calls, and messaging
- `src/app-bridge.ts` - `AppBridge` subclasses the base MCP SDK `Server` for the inner iframe channel and proxies through a separate outer `Client`
- `src/app.ts` - `App` subclasses the base MCP SDK `Protocol`, handles View initialization, tool calls, and messaging
- `src/app-bridge.ts` - `AppBridge` subclasses the base MCP SDK `Protocol` for the iframe channel and proxies through a separate outer `Client`
- `src/server/index.ts` - Helpers for MCP servers to register tools/resources with UI metadata
- `src/types.ts` - Protocol types re-exported from `spec.types.ts` and Zod schemas from `generated/schema.ts` (auto-generated during build)
- `src/message-transport.ts` - `PostMessageTransport` for iframe communication
Expand All @@ -70,12 +70,12 @@ rm -fR package-lock.json node_modules && \
### Protocol Flow

```
View (App/Client) <--PostMessageTransport--> Host (AppBridge/Server) <--separate MCP Client--> MCP Server
View (App/Protocol) <--PostMessageTransport--> Host (AppBridge/Protocol) <--separate MCP Client--> MCP Server
```

1. Host creates iframe with view HTML
2. View creates `App` instance and calls `connect()` with `PostMessageTransport`
3. View and Host complete the temporary inner base MCP handshake, then the View sends `ui/initialize` and receives authoritative Apps capabilities and context
3. View sends `ui/initialize` (the only handshake on the iframe channel) and receives authoritative Apps capabilities and context
4. Host sends `sendToolInput()` with tool arguments after initialization
5. View can call server tools via `app.callServerTool()` or send messages via `app.sendMessage()`
6. Host sends `sendToolResult()` when tool execution completes
Expand Down
22 changes: 16 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.5 \
@modelcontextprotocol/core@2.0.0-beta.5 \
zod@^4.2.0
```

For an MCP server:

```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/server@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.
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)
Expand Down
5 changes: 4 additions & 1 deletion build.bun.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
#!/usr/bin/env bun
import { $ } from "bun";
import { cpSync, mkdirSync } from "node:fs";
import { cpSync, mkdirSync, rmSync } from "node:fs";

// Avoid publishing artifacts left behind by an earlier build or branch.
rmSync("dist", { recursive: true, force: true });

// Run TypeScript compiler for type declarations
await $`tsc`;
Expand Down
12 changes: 6 additions & 6 deletions docs/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -97,7 +97,7 @@ sequenceDiagram
```

1. **Discovery** — The Host learns about tools and their UI resources when connecting to the server.
2. **Initialization** — When a UI tool is called, the Host renders the iframe. The SDK first completes its temporary inner base MCP handshake, then the View sends `ui/initialize` and receives host context (theme, capabilities, container dimensions). `ui/initialize` remains authoritative for Apps capabilities and identity, and `ui/notifications/initialized` remains the public View-ready signal.
2. **Initialization** — When a UI tool is called, the Host renders the iframe. The View sends `ui/initialize` (the only handshake on the iframe channel) and receives host context (theme, capabilities, container dimensions). `ui/initialize` is authoritative for Apps capabilities and identity, and `ui/notifications/initialized` is the public View-ready signal.
3. **Data delivery** — The Host sends tool arguments and, once available, tool results to the View. Results include both `content` (text for the model's context) and optionally `structuredContent` (data optimized for UI rendering). This separation lets servers provide rich data to the UI without bloating the model's context.
4. **Interactive phase** — The user interacts with the View. The View can call tools, send messages, or update context.
5. **Teardown** — Before unmounting, the Host notifies the View so it can save state or release resources.
Expand Down
2 changes: 1 addition & 1 deletion docs/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down
2 changes: 1 addition & 1 deletion examples/basic-host/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"react": "^19.2.0",
"react-dom": "^19.2.0",
"zod": "^4.1.13"
Expand Down
8 changes: 4 additions & 4 deletions examples/basic-server-preact/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,11 @@
"prepublishOnly": "npm run build"
},
"dependencies": {
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"preact": "^10.0.0",
Expand Down
8 changes: 4 additions & 4 deletions examples/basic-server-react/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,11 @@
"prepublishOnly": "npm run build"
},
"dependencies": {
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"react": "^19.2.0",
Expand Down
8 changes: 4 additions & 4 deletions examples/basic-server-solid/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,11 @@
"prepublishOnly": "npm run build"
},
"dependencies": {
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"solid-js": "1.9.10",
Expand Down
8 changes: 4 additions & 4 deletions examples/basic-server-svelte/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,11 @@
"prepublishOnly": "npm run build"
},
"dependencies": {
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"svelte": "^5.0.0",
Expand Down
8 changes: 4 additions & 4 deletions examples/basic-server-vanillajs/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,11 @@
"prepublishOnly": "npm run build"
},
"dependencies": {
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"zod": "^4.1.13"
Expand Down
8 changes: 4 additions & 4 deletions examples/basic-server-vue/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,11 @@
"prepublishOnly": "npm run build"
},
"dependencies": {
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"vue": "^3.5.0",
Expand Down
6 changes: 3 additions & 3 deletions examples/budget-allocator-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"chart.js": "^4.4.0",
"cors": "^2.8.5",
"express": "^5.1.0",
Expand Down
6 changes: 3 additions & 3 deletions examples/cohort-heatmap-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"react": "^19.2.0",
Expand Down
6 changes: 3 additions & 3 deletions examples/customer-segmentation-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"chart.js": "^4.4.0",
"cors": "^2.8.5",
"express": "^5.1.0",
Expand Down
6 changes: 3 additions & 3 deletions examples/debug-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"zod": "^4.1.13"
},
"devDependencies": {
Expand Down
8 changes: 4 additions & 4 deletions examples/integration-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@
"serve": "bun --watch main.ts"
},
"dependencies": {
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"react": "^19.2.0",
Expand Down
4 changes: 2 additions & 2 deletions examples/lazy-auth-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"jose": "^6.0.0",
Expand Down
8 changes: 4 additions & 4 deletions examples/map-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@
"serve": "bun --watch main.ts"
},
"dependencies": {
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"zod": "^4.1.13"
Expand Down
8 changes: 4 additions & 4 deletions examples/pdf-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@
},
"dependencies": {
"@cantoo/pdf-lib": "^2.6.5",
"@modelcontextprotocol/client": "2.0.0-beta.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"pdfjs-dist": "^5.0.0",
Expand Down
6 changes: 3 additions & 3 deletions examples/quickstart/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"zod": "^4.1.13"
Expand Down
6 changes: 3 additions & 3 deletions examples/scenario-modeler-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"chart.js": "^4.4.0",
"cors": "^2.8.5",
"express": "^5.1.0",
Expand Down
6 changes: 3 additions & 3 deletions examples/shadertoy-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"cors": "^2.8.5",
"express": "^5.1.0",
"zod": "^4.1.13"
Expand Down
6 changes: 3 additions & 3 deletions examples/sheet-music-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"abcjs": "^6.4.4",
"cors": "^2.8.5",
"express": "^5.1.0",
Expand Down
6 changes: 3 additions & 3 deletions examples/system-monitor-server/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "^1.7.0",
"@modelcontextprotocol/express": "2.0.0-beta.4",
"@modelcontextprotocol/node": "2.0.0-beta.4",
"@modelcontextprotocol/server": "2.0.0-beta.4",
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"chart.js": "^4.4.0",
"cors": "^2.8.5",
"express": "^5.1.0",
Expand Down
Loading