pi-mcp-adapter 2.19.0 → 2.20.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.20.0] - 2026-08-04
+
+### Added
+- Added an MCP tool approval broker event so permission extensions can allow, deny, or abstain on proxy, direct, `mcpScript`, resource, and iframe-originated MCP calls before the built-in `approveTools` prompt runs. Thanks @geshido for issue #279.
+- Added opt-in per-server MCP protocol selection with `protocolVersion: "legacy" | "auto" | "2026-07-28"`. Legacy remains the default; auto negotiates the modern era with conservative legacy fallback, while the pinned mode fails instead of falling back. Thanks @mjfaga for PR #272.
+- Added a strict TypeScript typecheck command and CI gate.
+
+### Changed
+- Migrated the MCP client from the monolithic SDK v1 package to the stable modular `@modelcontextprotocol/client` and `@modelcontextprotocol/core` v2 packages. The stable release restores conservative legacy discovery fallback and declared JSON Schema dialect support while retaining strict OAuth issuer validation.
+
+### Fixed
+- Renamed the MCP scripting tool to camel-case `mcpScript` because Anthropic rejects the previous underscore-form name. Thanks @ritvij14 for issue #278 and @wierdbytes for confirmation and the workaround.
+- Pinned the Chrome DevTools setup preset and README examples to `chrome-devtools-mcp@1.6.0` instead of `@latest`, so reviewed scaffolded commands stay stable. Thanks @fitchmultz for issue #274.
+- Removed the adapter's throwaway Streamable HTTP initialize probe. HTTP connections now initialize once on the real client and use narrowly classified SSE fallback, avoiding duplicate sessions and preventing authentication, cancellation, timeout, negotiation, and server failures from being misclassified as transport incompatibility.
+- Stopped tokenless discovery requests, sandboxed MCP app documents, unrelated child windows, and app-opened popups from gaining session authority; discovery now serves a non-sensitive landing page, app HTML loads with a separate resource-only token, host messages accept only the app frame as their source, and the app response enforces sandboxing even when opened as a top-level page.
+
 ## [2.19.0] - 2026-08-03
 
 ### Added

package/README.md

@@ -45,7 +45,7 @@ Preferred project config: `.mcp.json`
   "mcpServers": {
     "chrome-devtools": {
       "command": "npx",
-      "args": ["-y", "chrome-devtools-mcp@latest"]
+      "args": ["-y", "chrome-devtools-mcp@1.6.0"]
     }
   }
 }
@@ -191,6 +191,7 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `lifecycle` | `"lazy"` (default), `"eager"`, `"keep-alive"`, or `"lazy-keep-alive"` |
 | `idleTimeout` | Minutes before idle disconnect (overrides global) |
 | `requestTimeoutMs` | Request timeout in milliseconds for live MCP calls (overrides global; if omitted or `<= 0`, the MCP SDK default timeout is used) |
+| `protocolVersion` | `"legacy"` (default), `"auto"`, or `"2026-07-28"`; modern negotiation is opt-in |
 | `exposeResources` | Expose MCP resources as tools (default: true) |
 | `directTools` | `true`, `string[]`, or `false` — register tools individually instead of through proxy |
 | `toolPrefix` | Override global `settings.toolPrefix` for this server (`"server"`, `"short"`, `"none"`, or `"mcp"`) |
@@ -200,6 +201,16 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `trace` | Enable metadata-only JSONL protocol tracing for this server; payloads, prompts, tool arguments/results, authorization data, and URLs are never persisted |
 | `disabled` | Keep the server visible in config and status, but prevent connections, authentication, tools, and resource calls (only literal `true` disables it) |
 
+#### Protocol version negotiation
+
+The adapter defaults to `protocolVersion: "legacy"`. Omitting the field uses the classic MCP initialize sequence without `server/discover` or 2026 headers, preserving compatibility with deployed 2025-era servers.
+
+Use `"auto"` to probe for MCP 2026-07-28 and conservatively fall back to the classic handshake when the server provides legacy evidence. For stdio servers, the SDK probes with a short-lived sibling process before starting the session process, so each fresh auto connection adds one process spawn and can wait for the configured request timeout. Explicit Unix sockets are custom transports and probe in place. HTTP auto negotiation uses the actual Streamable HTTP connection; the adapter falls back to legacy SSE only when the endpoint definitively rejects Streamable HTTP (for example 404/405/406/415), never for authentication failures, cancellation, timeouts, or server errors.
+
+Use `"2026-07-28"` to pin that revision. Pinning has no legacy or SSE fallback and fails if the server does not offer the requested version.
+
+The stable SDK handles era-specific request envelopes, result decoding, list-changed subscriptions, cancellation, and multi-round-trip sampling/elicitation. The adapter keeps strict OAuth issuer validation in every mode. Adapter-level roots support, standard MCP logging presentation, and configuration/UI for protocol cache hints are not yet implemented.
+
 For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact callback registered with the provider, for example `"http://localhost:3118/callback"`. Dynamic clients normally omit it and use a lazy OS-assigned localhost callback port.
 
 Secret values in `headers`, `bearerToken`, `oauth.clientSecret`, and stdio `env` may use a leading `!command` to obtain their value at connection or authentication time. The command runs with stdin and stderr suppressed, stdout is limited to 1 MiB and trimmed, and it must finish within 10 seconds with non-empty output; failures stop the connection or authentication flow. Commands are not run during OAuth discovery or while reading, merging, previewing, hashing, or rendering configuration. Use `!!` to escape a literal leading `!`; ordinary and escaped values retain environment interpolation.
@@ -288,7 +299,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `mcpServers.<name>.oauth.authorizationParams` | Extra authorization URL parameters for provider-specific OAuth extensions. Flow-owned parameters such as `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `response_type`, and `resource` cannot be overridden. |
 | `directTools` | Global default for all servers (default: false). Per-server overrides this. |
 | `freezeDirectTools` | Keep direct-tool registration stable after the initial sync so automatic reconnects and list-change notifications do not rebuild the system prompt. Use `mcp({ connect: "server" })` or `/mcp reconnect <server>` to refresh deliberately. Default: false. |
-| `scriptMode` | Register the MCP-only `mcp_script` plain-JavaScript tool (default: true). Set to `false` to hide it. |
+| `scriptMode` | Register the MCP-only `mcpScript` plain-JavaScript tool (default: true). Set to `false` to hide it. |
 | `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. |
 | `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
 | `sampling` | Allow MCP servers to sample through Pi models, honoring `modelPreferences.hints` before current/default fallback (default: true when UI approval is available). |
@@ -317,6 +328,23 @@ Use `approveTools` when a tool should stay visible but not run without confirmat
 
 When a matching tool is called from the proxy tool, a direct MCP tool, a resource call, or an MCP UI iframe, Pi asks: **Allow once**, **Allow for session**, or **Deny**. Session approvals are kept in memory only. In headless sessions, matching calls fail closed with an `approval_required` result instead of running. `excludeTools` still removes tools entirely; `approveTools` only gates visible tools at call time.
 
+Permission extensions can broker these decisions by listening on `pi-mcp-adapter:tool-approval-request` and claiming the request synchronously:
+
+```ts
+import {
+  MCP_TOOL_APPROVAL_REQUEST_EVENT,
+  type McpToolApprovalRequest,
+} from "pi-mcp-adapter";
+
+pi.events.on(MCP_TOOL_APPROVAL_REQUEST_EVENT, (request: McpToolApprovalRequest) => {
+  request.claim(async () => {
+    return "allow_once"; // "allow_for_session" | "deny" | "abstain"
+  });
+});
+```
+
+The request includes `serverName`, `originalToolName`, `prefixedToolName`, `args`, `origin`, and optional `signal`. The first synchronous claim wins. `allow_for_session` updates the same in-memory approval cache as the built-in dialog; `deny` blocks the MCP call; `abstain` or no claim preserves the fallback behavior above. Brokered approval runs for every uncached MCP call regardless of `approveTools` configuration, across proxy, direct, `mcpScript`, resource, and iframe origins.
+
 ### Output Guard
 
 Oversized MCP tool/resource results are guarded by default so a single huge response can't blow up the model context window or the session file:
@@ -339,7 +367,7 @@ Set `"outputGuard": false` — or the env kill switch `MCP_OUTPUT_GUARD=0` — t
 
 ### MCP Scripting
 
-For multi-call MCP work, write ordinary JavaScript: discover, inspect, call, loop, filter, chain, or fan out, then return one result. Run that code with the default-on `mcp_script` tool. For a single MCP call, search, describe, status check, or auth action, use `mcp` instead. Set `settings.scriptMode` to `false` to hide the scripting tool.
+For multi-call MCP work, write ordinary JavaScript: discover, inspect, call, loop, filter, chain, or fan out, then return one result. Run that code with the default-on `mcpScript` tool. For a single MCP call, search, describe, status check, or auth action, use `mcp` instead. Set `settings.scriptMode` to `false` to hide the scripting tool.
 
 The bundled `mcp-scripting` skill is a separate Pi package resource. To hide that skill while keeping the adapter extension installed, replace the package entry in Pi settings with the object form and disable package skills:
 
@@ -353,7 +381,7 @@ The bundled `mcp-scripting` skill is a separate Pi package resource. To hide tha
 
 Preserve any version pin in `source` if your existing package entry has one. You can also disable package resources through `pi config`.
 
-For example, this is the JavaScript passed as the `code` argument to `mcp_script`:
+For example, this is the JavaScript passed as the `code` argument to `mcpScript`:
 
 ```js
 const { items } = await tools.search({ query: "search issues", server: "github" });
@@ -371,9 +399,9 @@ return result.data;
 
 See the bundled `mcp-scripting` skill for the complete workflow guide. The API is `await tools.search({ query, server?, limit?, offset? })`, `await tools.describe({ path })`, `tools.call(path, args)`, direct flat calls, `emit(value)`, and a captured `console`. Use ordinary JavaScript loops and Promise utilities for composition; fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` are not provided. MCP calls return `{ ok: true, data }` or `{ ok: false, error: { code, message } }`, so a failed call does not stop the rest of the script. Result details include a concise `calls` trace with each operation, its path or query, outcome, and duration. Emitted values and console output appear before the script's final return value, and the combined result uses the normal MCP output guard. The default timeout is 30 seconds; each script runs in a worker thread that is terminated at the deadline, including for infinite loops.
 
-For a tool-restricted subagent, launch the child Pi with its tool allowlist set to `["mcp_script"]`. Have the parent discover MCP tool names with `mcp({ search: "..." })` and include the relevant prefixed names in the child's task; the child can then loop, filter, and chain those MCP calls without filesystem, shell, or edit tools. The adapter's ordinary lazy connection, authentication, output guard, abort handling, and approval gates still apply to every call.
+For a tool-restricted subagent, launch the child Pi with its tool allowlist set to `["mcpScript"]`. Have the parent discover MCP tool names with `mcp({ search: "..." })` and include the relevant prefixed names in the child's task; the child can then loop, filter, and chain those MCP calls without filesystem, shell, or edit tools. The adapter's ordinary lazy connection, authentication, output guard, abort handling, and approval gates still apply to every call.
 
-`mcp_script` is a trusted agent-authored MCP scripting layer, not an isolation boundary. If you need isolation, run Pi in an isolated environment. It is distinct from Pi's code-mode skill: Pi's skill batches general Pi tools, while `mcp_script` exposes MCP calls only and can be the child's sole tool.
+`mcpScript` is a trusted agent-authored MCP scripting layer, not an isolation boundary. If you need isolation, run Pi in an isolated environment. It is distinct from Pi's code-mode skill: Pi's skill batches general Pi tools, while `mcpScript` exposes MCP calls only and can be the child's sole tool.
 
 ### MCP Prompts
 
@@ -404,7 +432,7 @@ Per-server:
   "mcpServers": {
     "chrome-devtools": {
       "command": "npx",
-      "args": ["-y", "chrome-devtools-mcp@latest"],
+      "args": ["-y", "chrome-devtools-mcp@1.6.0"],
       "directTools": true
     },
     "github": {

package/commands.ts

@@ -277,8 +277,8 @@ export async function authenticateServer(
           "info"
         );
       },
-      signal,
-      runtime,
+      ...(signal ? { signal } : {}),
+      ...(runtime ? { runtime } : {}),
     });
     if (signal?.aborted) signal.throwIfAborted();
 

package/config.ts

@@ -56,7 +56,7 @@ export const KNOWN_SERVER_PRESETS: readonly KnownServerPreset[] = [
     id: "chrome-devtools",
     name: "Chrome DevTools",
     summary: "Inspect and automate a local Chrome browser.",
-    entry: { command: "npx", args: ["-y", "chrome-devtools-mcp@latest"] },
+    entry: { command: "npx", args: ["-y", "chrome-devtools-mcp@1.6.0"] },
   },
 ];
 
@@ -417,10 +417,12 @@ function getConfigSources(overridePath?: string, cwd = process.cwd()): ConfigSou
 }
 
 function mergeConfigs(base: McpConfig, next: McpConfig): McpConfig {
+  const imports = mergeImports(base.imports, next.imports);
+  const settings = next.settings ? { ...base.settings, ...next.settings } : base.settings;
   return {
     mcpServers: mergeServerMaps(base.mcpServers, next.mcpServers),
-    imports: mergeImports(base.imports, next.imports),
-    settings: next.settings ? { ...base.settings, ...next.settings } : base.settings,
+    ...(imports !== undefined ? { imports } : {}),
+    ...(settings !== undefined ? { settings } : {}),
   };
 }
 
@@ -499,7 +501,7 @@ function expandImports(config: McpConfig, cwd = process.cwd()): McpConfig {
 
   return {
     imports: config.imports,
-    settings: config.settings,
+    ...(config.settings !== undefined ? { settings: config.settings } : {}),
     mcpServers: mergeServerMaps(importedServers, config.mcpServers),
   };
 }
@@ -609,8 +611,8 @@ function validateConfig(raw: unknown): McpConfig {
 
   return {
     mcpServers: servers as Record<string, ServerEntry>,
-    imports: Array.isArray(obj.imports) ? (obj.imports as ImportKind[]) : undefined,
-    settings: obj.settings as McpSettings | undefined,
+    ...(Array.isArray(obj.imports) ? { imports: obj.imports as ImportKind[] } : {}),
+    ...(obj.settings !== undefined ? { settings: obj.settings as McpSettings } : {}),
   };
 }
 
@@ -708,8 +710,10 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
 
       if (raw.type === "local" && Array.isArray(raw.command) && raw.command.length > 0 && raw.command.every((value): value is string => typeof value === "string")) {
         const env = toStringRecord(raw.environment);
+        const command = raw.command[0];
+        if (command === undefined) continue;
         const mapped: ServerEntry = {
-          command: raw.command[0],
+          command,
           args: raw.command.slice(1),
           ...(env ? { env } : {}),
           ...(typeof raw.cwd === "string" ? { cwd: raw.cwd } : {}),
@@ -789,9 +793,12 @@ function buildUnifiedDiff(beforeText: string, afterText: string): string {
 
   for (let i = rows - 1; i >= 0; i--) {
     for (let j = cols - 1; j >= 0; j--) {
-      lcs[i][j] = before[i] === after[j]
-        ? lcs[i + 1][j + 1] + 1
-        : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+      const row = lcs[i];
+      const nextRow = lcs[i + 1];
+      if (!row || !nextRow) continue;
+      row[j] = before[i] === after[j]
+        ? (nextRow[j + 1] ?? 0) + 1
+        : Math.max(nextRow[j] ?? 0, row[j + 1] ?? 0);
     }
   }
 
@@ -805,7 +812,7 @@ function buildUnifiedDiff(beforeText: string, afterText: string): string {
       j++;
       continue;
     }
-    if (j < cols && (i === rows || lcs[i][j + 1] >= lcs[i + 1][j])) {
+    if (j < cols && (i === rows || (lcs[i]?.[j + 1] ?? 0) >= (lcs[i + 1]?.[j] ?? 0))) {
       lines.push(`+ ${after[j]}`);
       j++;
       continue;
@@ -1108,7 +1115,7 @@ export function getServerProvenance(overridePath?: string, cwd = process.cwd()):
       provenance.set(name, {
         path: source.writePath,
         kind: source.kind,
-        importKind: source.importKind,
+        ...(source.importKind !== undefined ? { importKind: source.importKind } : {}),
       });
     }
   }

package/direct-tools.ts

@@ -1,5 +1,5 @@
 import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { UrlElicitationRequiredError } from "@modelcontextprotocol/sdk/types.js";
+import { UrlElicitationRequiredError, type Client } from "@modelcontextprotocol/client";
 import type { McpExtensionState } from "./state.ts";
 import type { DirectToolSpec, McpConfig, McpContent, ToolPrefix } from "./types.ts";
 import type { MetadataCache } from "./metadata-cache.ts";
@@ -19,6 +19,8 @@ import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session
 import { combineAbortSignals, isAbortError } from "./runtime-owner.ts";
 import { ensureToolCallApproved } from "./tool-approval.ts";
 
+type ClientCallToolResult = Awaited<ReturnType<Client["callTool"]>>;
+
 const BUILTIN_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
 const INSTRUCTIONS_SNIPPET_LENGTH = 150;
 export const DIRECT_TOOLS_ADVISORY_THRESHOLD = 75;
@@ -92,7 +94,10 @@ async function attemptDirectAutoAuth(
           : { authStorageOptions: state.authStorageOptions, runtime: state.oauthRuntime },
       );
     } else {
-      await authenticate(serverName, serverUrl, definition, { signal, runtime: state.oauthRuntime });
+      await authenticate(serverName, serverUrl, definition, {
+        ...(signal ? { signal } : {}),
+        runtime: state.oauthRuntime,
+      });
     }
     return { status: "success" };
   } catch (error) {
@@ -162,9 +167,9 @@ export function resolveDirectTools(
         originalName: tool.name,
         prefixedName,
         description: tool.description ?? "",
-        inputSchema: tool.inputSchema,
-        uiResourceUri: tool.uiResourceUri,
-        uiStreamMode: tool.uiStreamMode,
+        ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
+        ...(tool.uiResourceUri !== undefined ? { uiResourceUri: tool.uiResourceUri } : {}),
+        ...(tool.uiStreamMode !== undefined ? { uiStreamMode: tool.uiStreamMode } : {}),
       });
     }
 
@@ -207,7 +212,7 @@ export function buildProxyDescription(
   directSpecs: DirectToolSpec[],
 ): string {
   const prefix = config.settings?.toolPrefix ?? "server";
-  let desc = `MCP gateway — server status, tool search/describe, auth, and single MCP tool calls. When one request needs several MCP calls with logic between them, use mcp_script. Non-MCP Pi tools should be called directly, not through mcp.\n`;
+  let desc = `MCP gateway — server status, tool search/describe, auth, and single MCP tool calls. When one request needs several MCP calls with logic between them, use mcpScript. Non-MCP Pi tools should be called directly, not through mcp.\n`;
 
   const directByServer = new Map<string, number>();
   for (const spec of directSpecs) {
@@ -223,7 +228,7 @@ export function buildProxyDescription(
   const serverSummaries: string[] = [];
   for (const serverName of Object.keys(config.mcpServers)) {
     const definition = config.mcpServers[serverName];
-    if (isServerDisabled(definition)) continue;
+    if (!definition || isServerDisabled(definition)) continue;
     const entry = cache?.servers?.[serverName];
     const effectivePrefix = resolveToolPrefix(definition, prefix);
     const toolCount = (entry?.tools ?? []).filter(
@@ -377,11 +382,11 @@ export function createDirectToolExecutor(
       name: spec.prefixedName,
       originalName: spec.originalName,
       description: spec.description,
-      inputSchema: spec.inputSchema,
-      resourceUri: spec.resourceUri,
-      uiResourceUri: spec.uiResourceUri,
-      uiStreamMode: spec.uiStreamMode,
-    }, params, ownedSignal);
+      ...(spec.inputSchema !== undefined ? { inputSchema: spec.inputSchema } : {}),
+      ...(spec.resourceUri !== undefined ? { resourceUri: spec.resourceUri } : {}),
+      ...(spec.uiResourceUri !== undefined ? { uiResourceUri: spec.uiResourceUri } : {}),
+      ...(spec.uiStreamMode !== undefined ? { uiStreamMode: spec.uiStreamMode } : {}),
+    }, params, ownedSignal, spec.resourceUri ? "resource" : "direct");
     if (approval.ok === false) {
       const denied = approval.reason === "denied";
       const message = denied
@@ -431,7 +436,12 @@ export function createDirectToolExecutor(
 
       if (spec.resourceUri) {
         const result = await withSessionRecovery(
-          { manager: state.manager, config: state.config, signal: ownedSignal, onNeedsAuth: recoverAuthConnection },
+          {
+            manager: state.manager,
+            config: state.config,
+            ...(ownedSignal ? { signal: ownedSignal } : {}),
+            onNeedsAuth: recoverAuthConnection,
+          },
           spec.serverName,
           (conn) => conn.client.readResource({ uri: spec.resourceUri! }, requestOptions),
         );
@@ -453,22 +463,27 @@ export function createDirectToolExecutor(
             toolName: spec.originalName,
             toolArgs: params ?? {},
             uiResourceUri: spec.uiResourceUri!,
-            streamMode: spec.uiStreamMode,
-            signal,
+            ...(spec.uiStreamMode !== undefined ? { streamMode: spec.uiStreamMode } : {}),
+            ...(signal ? { signal } : {}),
             onNeedsAuth: recoverAuthConnection,
           })
         : null;
 
-      const result = await withSessionRecovery(
-        { manager: state.manager, config: state.config, signal: ownedSignal, onNeedsAuth: recoverAuthConnection },
+      const result = await withSessionRecovery<ClientCallToolResult>(
+        {
+          manager: state.manager,
+          config: state.config,
+          ...(ownedSignal ? { signal: ownedSignal } : {}),
+          onNeedsAuth: recoverAuthConnection,
+        },
         spec.serverName,
         (conn) => abortable(conn.client.callTool({
           name: spec.originalName,
           arguments: params ?? {},
           _meta: uiSession?.requestMeta,
-        }, undefined, requestOptions), ownedSignal),
+        }, requestOptions), ownedSignal),
       );
-      uiSession?.sendToolResult(result as unknown as import("@modelcontextprotocol/sdk/types.js").CallToolResult);
+      uiSession?.sendToolResult(result as unknown as import("@modelcontextprotocol/client").CallToolResult);
 
       if (result.isError) {
         const mcpContent = (result.content ?? []) as McpContent[];

package/elicitation-handler.ts

@@ -1,16 +1,15 @@
 import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Client } from "@modelcontextprotocol/client";
 import {
-  ElicitRequestSchema,
-  ErrorCode,
-  McpError,
+  ProtocolError,
+  ProtocolErrorCode,
   type ElicitRequest,
   type ElicitRequestFormParams,
   type ElicitRequestURLParams,
   type ElicitResult,
-} from "@modelcontextprotocol/sdk/types.js";
-import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
-import type { JsonSchemaType } from "@modelcontextprotocol/sdk/validation/types.js";
+} from "@modelcontextprotocol/client";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/client/validators/ajv";
+import type { JsonSchemaType } from "@modelcontextprotocol/client";
 import open from "open";
 
 export type ElicitationValue = string | number | boolean | string[] | undefined;
@@ -28,7 +27,7 @@ export interface ElicitationHandlerOptions {
 export type ServerElicitationConfig = Omit<ElicitationHandlerOptions, "serverName" | "onUrlAccepted">;
 
 export function registerElicitationHandler(client: Client, options: ElicitationHandlerOptions): void {
-  client.setRequestHandler(ElicitRequestSchema, request =>
+  client.setRequestHandler("elicitation/create", request =>
     handleElicitationRequest(options, request));
 }
 
@@ -305,16 +304,16 @@ export async function handleUrlElicitation(
   options: ElicitationHandlerOptions,
   params: ElicitRequestURLParams,
 ): Promise<ElicitResult> {
-  if (!options.allowUrl) throw new McpError(ErrorCode.InvalidParams, "URL elicitation is not supported");
+  if (!options.allowUrl) throw new ProtocolError(ProtocolErrorCode.InvalidParams, "URL elicitation is not supported");
 
   let parsed: URL;
   try {
     parsed = new URL(params.url);
   } catch {
-    throw new McpError(ErrorCode.InvalidParams, "URL elicitation supplied an invalid URL");
+    throw new ProtocolError(ProtocolErrorCode.InvalidParams, "URL elicitation supplied an invalid URL");
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new McpError(ErrorCode.InvalidParams, "URL elicitation only supports HTTP and HTTPS URLs");
+    throw new ProtocolError(ProtocolErrorCode.InvalidParams, "URL elicitation only supports HTTP and HTTPS URLs");
   }
 
   const decision = await options.ui.select([

package/errors.ts

@@ -17,8 +17,8 @@ export interface McpUiErrorContext {
 export class McpUiError extends Error {
   readonly code: string;
   readonly context: McpUiErrorContext;
-  readonly recoveryHint?: string;
-  readonly cause?: Error;
+  readonly recoveryHint: string | undefined;
+  readonly cause: Error | undefined;
 
   constructor(
     message: string,
@@ -65,9 +65,9 @@ export class ResourceFetchError extends McpUiError {
   ) {
     super(`Failed to fetch UI resource "${uri}": ${reason}`, {
       code: "RESOURCE_FETCH_ERROR",
-      context: { uri, server: options?.server },
+      context: { uri, ...(options?.server !== undefined ? { server: options.server } : {}) },
       recoveryHint: "Check that the MCP server is connected and the resource URI is valid.",
-      cause: options?.cause,
+      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
     });
     this.name = "ResourceFetchError";
   }
@@ -84,7 +84,11 @@ export class ResourceParseError extends McpUiError {
   ) {
     super(`Invalid UI resource "${uri}": ${reason}`, {
       code: "RESOURCE_PARSE_ERROR",
-      context: { uri, server: options?.server, mimeType: options?.mimeType },
+      context: {
+        uri,
+        ...(options?.server !== undefined ? { server: options.server } : {}),
+        ...(options?.mimeType !== undefined ? { mimeType: options.mimeType } : {}),
+      },
       recoveryHint: "Ensure the resource returns valid HTML with the correct MIME type.",
     });
     this.name = "ResourceParseError";
@@ -98,9 +102,9 @@ export class BridgeConnectionError extends McpUiError {
   constructor(reason: string, options?: { session?: string; cause?: Error }) {
     super(`AppBridge connection failed: ${reason}`, {
       code: "BRIDGE_CONNECTION_ERROR",
-      context: { session: options?.session },
+      context: options?.session !== undefined ? { session: options.session } : {},
       recoveryHint: "Check browser console for detailed errors. The iframe may have failed to load.",
-      cause: options?.cause,
+      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
     });
     this.name = "BridgeConnectionError";
   }
@@ -142,9 +146,9 @@ export class SessionError extends McpUiError {
   ) {
     super(`Session error: ${reason}`, {
       code: "SESSION_ERROR",
-      context: { session: options?.session },
+      context: options?.session !== undefined ? { session: options.session } : {},
       recoveryHint: "The session may have expired or been closed. Try opening the UI again.",
-      cause: options?.cause,
+      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
     });
     this.name = "SessionError";
   }
@@ -160,9 +164,9 @@ export class ServerError extends McpUiError {
   ) {
     super(`UI server error: ${reason}`, {
       code: "SERVER_ERROR",
-      context: { port: options?.port },
+      context: options?.port !== undefined ? { port: options.port } : {},
       recoveryHint: "Check if the port is available. Another process may be using it.",
-      cause: options?.cause,
+      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
     });
     this.name = "ServerError";
   }
@@ -179,9 +183,9 @@ export class McpServerError extends McpUiError {
   ) {
     super(`MCP server "${server}" error: ${reason}`, {
       code: "MCP_SERVER_ERROR",
-      context: { server, tool: options?.tool },
+      context: { server, ...(options?.tool !== undefined ? { tool: options.tool } : {}) },
       recoveryHint: "Check that the MCP server is running and responsive.",
-      cause: options?.cause,
+      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
     });
     this.name = "McpServerError";
   }
@@ -196,8 +200,8 @@ export function wrapError(error: unknown, context?: McpUiErrorContext): McpUiErr
     return new McpUiError(error.message, {
       code: error.code,
       context: { ...error.context, ...context },
-      recoveryHint: error.recoveryHint,
-      cause: error.cause,
+      ...(error.recoveryHint !== undefined ? { recoveryHint: error.recoveryHint } : {}),
+      ...(error.cause !== undefined ? { cause: error.cause } : {}),
     });
   }
 
@@ -206,8 +210,8 @@ export function wrapError(error: unknown, context?: McpUiErrorContext): McpUiErr
 
   return new McpUiError(message, {
     code: "UNKNOWN_ERROR",
-    context,
-    cause,
+    ...(context !== undefined ? { context } : {}),
+    ...(cause !== undefined ? { cause } : {}),
   });
 }
 

package/host-html-template.ts

@@ -2,9 +2,11 @@ import type { UiHostContext, UiResourceContent, UiResourceCsp } from "./types.ts
 
 // Use locally bundled AppBridge to avoid CDN Zod bundling issues
 const DEFAULT_APP_BRIDGE_MODULE_URL = "/app-bridge.bundle.js";
+const APP_SANDBOX = "allow-scripts allow-forms allow-modals allow-popups allow-downloads";
 
 export interface HostHtmlTemplateInput {
   sessionToken: string;
+  uiResourceToken: string;
   serverName: string;
   toolName: string;
   toolArgs: Record<string, unknown>;
@@ -20,6 +22,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
   const hostContext = input.hostContext ?? {};
 
   const sessionToken = safeInlineJSON(input.sessionToken);
+  const uiResourceToken = safeInlineJSON(input.uiResourceToken);
   const toolArgs = safeInlineJSON(input.toolArgs);
   const serverName = safeInlineJSON(input.serverName);
   const toolName = safeInlineJSON(input.toolName);
@@ -109,7 +112,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
     </div>
   </header>
   <main>
-    <iframe id="mcp-app" sandbox="allow-scripts allow-forms allow-modals allow-popups allow-popups-to-escape-sandbox allow-downloads" referrerpolicy="no-referrer"></iframe>
+    <iframe id="mcp-app" sandbox="${APP_SANDBOX}" referrerpolicy="no-referrer"></iframe>
   </main>
   <div class="overlay" id="error-overlay">
     <div class="panel">
@@ -127,6 +130,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
     import { AppBridge, PostMessageTransport } from ${moduleUrl};
 
     const SESSION_TOKEN = ${sessionToken};
+    const UI_RESOURCE_TOKEN = ${uiResourceToken};
     const SERVER_NAME = ${serverName};
     const TOOL_NAME = ${toolName};
     const TOOL_ARGS = ${toolArgs};
@@ -236,6 +240,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
     // Also listen for raw postMessage events with custom types (notify, prompt, intent, etc.)
     // These bypass the AppBridge protocol but are used by some MCP UI implementations
     window.addEventListener("message", async (event) => {
+      if (event.source !== iframe.contentWindow) return;
       const data = event.data;
       if (!data || typeof data !== "object") return;
       
@@ -300,7 +305,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
 
     // Connect bridge BEFORE loading iframe to ensure we're listening when the app sends ui/initialize
     try {
-      const transport = new PostMessageTransport(iframe.contentWindow, null);
+      const transport = new PostMessageTransport(iframe.contentWindow, iframe.contentWindow);
       await bridge.connect(transport);
     } catch (error) {
       console.error("[host] Bridge connection failed:", error);
@@ -310,7 +315,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
     const iframeLoaded = new Promise((resolve) => {
       iframe.onload = resolve;
     });
-    iframe.src = "/ui-app?session=" + encodeURIComponent(SESSION_TOKEN);
+    iframe.src = "/ui-app?resource=" + encodeURIComponent(UI_RESOURCE_TOKEN);
     await iframeLoaded;
 
     const eventSource = new EventSource("/events?session=" + encodeURIComponent(SESSION_TOKEN));
@@ -399,6 +404,7 @@ export function buildCspMetaContent(csp: UiResourceCsp | undefined): string {
 
   return [
     "default-src 'none'",
+    `sandbox ${APP_SANDBOX}`,
     toDirective("script-src", ["'self'", "'unsafe-inline'"], resourceDomains),
     toDirective("style-src", ["'self'", "'unsafe-inline'"], resourceDomains),
     toDirective("font-src", ["'self'"], resourceDomains),