- 
- 
> [!NOTE]
@@ -122,36 +120,12 @@ resources:
## 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
+npm install -S @modelcontextprotocol/ext-apps
```
-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)
+[Quickstart Guide](https://apps.extensions.modelcontextprotocol.io/api/documents/Quickstart.html)
to build your first MCP App.
## Using the SDK
@@ -165,7 +139,7 @@ UI metadata.
| `@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) |
+| `@modelcontextprotocol/ext-apps/server` | Register tools and resources on your MCP server | [API Docs →](https://apps.extensions.modelcontextprotocol.io/api/modules/server.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)
@@ -272,7 +246,7 @@ point your client at a local build:
## Resources
-- [Quickstart Guide](https://apps.extensions.modelcontextprotocol.io/api/documents/quickstart.html)
+- [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))
diff --git a/build.bun.ts b/build.bun.ts
index 61361e6..a129d5d 100644
--- a/build.bun.ts
+++ b/build.bun.ts
@@ -1,9 +1,6 @@
#!/usr/bin/env bun
import { $ } from "bun";
-import { cpSync, mkdirSync, rmSync } from "node:fs";
-
-// Avoid publishing artifacts left behind by an earlier build or branch.
-rmSync("dist", { recursive: true, force: true });
+import { cpSync, mkdirSync } from "node:fs";
// Run TypeScript compiler for type declarations
await $`tsc`;
@@ -34,15 +31,9 @@ function buildJs(
});
}
-// Peer dependencies stay external in the standard entry points so consumers
-// share one base MCP SDK and Zod instance. The *-with-deps entry points keep
-// bundling these dependencies for standalone browser use.
-const PEER_EXTERNALS = [
- "@modelcontextprotocol/client",
- "@modelcontextprotocol/core",
- "@modelcontextprotocol/server",
- "zod",
-];
+// zod is a peerDependency — keep it external so consumers share a single
+// zod instance (instanceof ZodError / schema.extend() break with duplicate copies).
+const PEER_EXTERNALS = ["@modelcontextprotocol/sdk", "zod"];
await Promise.all([
buildJs("src/app.ts", {
diff --git a/docs/authorization.md b/docs/authorization.md
index df7adc6..59fc26c 100644
--- a/docs/authorization.md
+++ b/docs/authorization.md
@@ -150,7 +150,7 @@ registerAppTool(
"get_account_balance",
{
description: "Get account balance",
- inputSchema: z.object({ accountId: z.string() }),
+ inputSchema: { accountId: z.string() },
},
async ({ accountId }) => {
if (!authInfo) {
diff --git a/docs/migrate-to-2.md b/docs/migrate-to-2.md
deleted file mode 100644
index f9341d0..0000000
--- a/docs/migrate-to-2.md
+++ /dev/null
@@ -1,130 +0,0 @@
----
-title: Migrate to v2
-group: Getting Started
-description: Upgrade from ext-apps 1.x to 2.x — new base MCP SDK peer packages, API changes for Views and hosts, and what stays wire-compatible.
----
-
-# Migrating from ext-apps 1.x to 2.x
-
-ext-apps 2.x is built on the base MCP TypeScript SDK 2.x, which replaced the
-single `@modelcontextprotocol/sdk` package with `@modelcontextprotocol/client`,
-`server`, `core`, `node` and `express`. The MCP Apps wire protocol did not
-change; the breaking changes are in dependencies and in the TypeScript API.
-
-## Host compatibility
-
-The `ui/*` messages exchanged over the iframe channel are byte-identical to
-1.x. A 2.x View runs in a 1.x host and a 2.x host renders 1.x Views. The only
-host-side deltas are in error responses (see below).
-
-## What stays the same
-
-`App` / `AppBridge` constructors, the `on*` setters, `addEventListener`,
-`callServerTool`, `readServerResource`, `registerAppResource`, the React hooks
-and the `_meta.ui.resourceUri` handling are unchanged. Published `.d.ts` files
-now resolve under `moduleResolution: NodeNext` / `Node16` without workarounds
-(#705).
-
-## Peer dependencies by role
-
-| Role | Install |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| View author | `@modelcontextprotocol/ext-apps`, `@modelcontextprotocol/client@^2.0.0`, `zod@^4.2.0` (+ `react`/`react-dom` for `./react`) |
-| Host author | same as View author |
-| MCP server author | View author packages + `@modelcontextprotocol/server@^2.0.0`; for HTTP transports also `@modelcontextprotocol/node@^2.0.0` (`NodeStreamableHTTPServerTransport`) and `@modelcontextprotocol/express@^2.0.0` (`createMcpExpressApp`, which peers on `express`) |
-| CDN / `*-with-deps` | nothing extra: `./app-with-deps` and `./react-with-deps` bundle client, core and zod (about 25% larger than the 1.x bundles) |
-
-`@modelcontextprotocol/client` is a required peer (`App` and `AppBridge` extend
-its `Protocol` class); `@modelcontextprotocol/core` is a required peer that `client` already depends on, so npm installs it without you listing it;
-`@modelcontextprotocol/server` stays optional and is only needed for the
-`./server` helpers. Node.js 20+ is required.
-
-## Breaking changes
-
-- **Peer packages.** `@modelcontextprotocol/sdk@^1` is replaced by the split
- 2.x packages above, all at `^2.0.0`. Remove the 1.x package from your
- project: the two SDKs share no classes or types (a 1.x `McpError` or
- `Client` cannot be passed to 2.x code), even though they speak the same
- wire protocol.
-- **zod 3 dropped.** The peer range is `zod@^4.2.0`. Tool schemas must
- implement Standard JSON Schema (`~standard.jsonSchema`): zod 4.2+, ArkType,
- Valibot. zod 4.0 and 4.1 do not expose `~standard.jsonSchema` and are
- rejected too. Raw zod shapes (`{ q: z.string() }`) still work with
- `registerAppTool` but are deprecated; wrap them with `z.object({...})`.
-- **`App` / `AppBridge` extend `Protocol` from `@modelcontextprotocol/client`.**
- `ProtocolWithEvents` is gone; use the SDK's `Protocol`. The `AppRequest`,
- `AppNotification` and `AppResult` unions are kept as deprecated type
- aliases (nothing in 2.x consumes them) and will be removed in 3.0.
-- **Handler context.** Custom request handlers, `registerAppTool` callbacks
- (server) and `app.registerTool` callbacks (View) receive the SDK 2.x
- context: `extra.signal` → `extra.mcpReq.signal`, `extra.requestId` →
- `extra.mcpReq.id`; `extra.sessionId` is unchanged and `extra.authInfo`
- moved to `extra.http?.authInfo`.
-- **`setRequestHandler` / `setNotificationHandler` take method names.**
- `app.setRequestHandler(SomeRequestSchema, handler)` becomes
- `app.setRequestHandler("some/method", { params: SomeParamsSchema }, (params, ctx) => …)`
- for custom methods (the handler receives the parsed params); the two-argument
- `setRequestHandler("tools/call", handler)` form exists only for spec-defined
- method names. The 1.x `(Schema, handler)` form still works on `App` and
- `AppBridge` as a deprecated overload: it logs a one-time warning, hands the
- handler the whole `{ method, params }` message as before, and gives request
- handlers a 1.x-shaped `extra` (`signal`, `requestId`, `sessionId`, `_meta`,
- `sendRequest`, `sendNotification`, `authInfo`; exported as
- `LegacyRequestHandlerExtra`). It will be removed in 3.0.
-- **Double-registration guard covers the SDK's own handlers.** Registering a
- handler for `notifications/progress` or `notifications/cancelled` (which
- the base `Protocol` already owns) now throws `already registered`, as
- `ping` and the `on*`-owned methods did in 1.x. Use `addEventListener` or
- the SDK's progress callbacks instead of replacing these.
-- **Errors.** Remote JSON-RPC errors are `ProtocolError` (numeric `code`);
- local conditions are `SdkError` with a string `code`: request timeout →
- `"REQUEST_TIMEOUT"`, connection closed → `"CONNECTION_CLOSED"`. Cancelling a
- request with an `AbortSignal` also rejects with `"REQUEST_TIMEOUT"` (the
- message is the abort reason). Messages no longer carry the `MCP error N:`
- prefix.
- A resource-not-found reply that carries `data.uri` arrives as
- `ResourceNotFoundError` (a `ProtocolError` subclass, `code` `-32602`, with a
- `.uri` getter).
-
-## Host-side wire deltas
-
-Observed when a 2.x `AppBridge` answers a View; a 1.x View sees these too.
-
-| Situation | 1.x host | 2.x host |
-| --------------------------------------------------------- | ------------------------------ | --------------------------------------------------- |
-| A handler throws `-32002` (resource not found) | `error.code: -32002` | `error.code: -32602` (the SDK never emits `-32002`) |
-| Invalid params on a `ui/*` request | `-32603` with a zod issue dump | `-32602 Invalid params for
- No auth was needed to render this view. Click below to invoke the
- protected
- get_secret tool — the host will run the OAuth flow on 401
- and retry.
-
An application is requesting access:
-${escapeHtml(id)}
You can close this tab. The tool will succeed on the next retry.
`, - ); - }); - - // Simple landing page - app.get("/", (req, res) => { - const base = publicBaseHref(req); - res - .type("text/plain") - .send( - `Lazy Auth Demo — MCP server\n\n` + - ` MCP endpoint: ${base}/mcp\n` + - ` ${base}/ttl/