@agent-native/core 0.112.0 → 0.114.0

package/src/mcp/build-server.ts

@@ -0,0 +1,2356 @@
+/**
+ * Shared MCP server builder.
+ *
+ * Extracted from `server.ts` so the stateless Streamable-HTTP mount
+ * (`mountMCP`) and the stdio transport (`runMCPStdio --standalone`) build the
+ * *same* MCP server from the *same* `ActionEntry` registry. Both surfaces:
+ *
+ *   - expose every action as an MCP tool (+ the `ask-agent` meta-tool),
+ *   - append the framework deep-link block / `_meta` to every tool result,
+ *   - wrap `run()` / `askAgent()` in `runWithRequestContext` so per-user /
+ *     per-org scoping (accessFilter, resolveCredential, MCP visibility) is
+ *     honoured.
+ *
+ * `server.ts` re-exports `createMCPServerForRequest` and the auth helpers so
+ * any (future) external importer of `@agent-native/core/mcp` keeps resolving.
+ *
+ * Node-only at the SDK level, but this module itself has no Node-only imports
+ * — it can be bundled into the serverless function alongside `mountMCP`.
+ */
+
+import {
+  MCP_APP_EXTENSION_ID,
+  MCP_APP_MIME_TYPE,
+  MCP_APP_RESOURCE_URI_META_KEY,
+  type ActionMcpAppCsp,
+  type ActionMcpAppResourceConfig,
+} from "../action.js";
+import type { ActionEntry } from "../agent/production-agent.js";
+import { isMcpActionResult } from "../mcp-client/app-result.js";
+import { getConfiguredAppBasePath } from "../server/app-base-path.js";
+import {
+  buildDeepLink,
+  toAbsoluteOpenUrl,
+  toDesktopOpenUrl,
+  toVsCodeOpenUrl,
+} from "../server/deep-link.js";
+import {
+  getRequestContext,
+  getRequestOrgId,
+  getRequestUserEmail,
+  runWithRequestContext,
+} from "../server/request-context.js";
+import {
+  isAgentNativeOpenDeepLink,
+  withCollapsedAgentSidebarParam,
+} from "../shared/agent-sidebar-url.js";
+import { MCP_APP_CHAT_BRIDGE_QUERY_PARAM } from "../shared/embed-auth.js";
+import { getBuiltinCrossAppTools } from "./builtin-tools.js";
+import {
+  MCP_CONNECT_OAUTH_CLIENT_ID,
+  MCP_CONNECT_SCOPE,
+} from "./connect-store.js";
+import { MCP_APP_REQUEST_ORIGIN_CSP_SOURCE } from "./embed-app.js";
+import type { ExternalAgentPolicy } from "./external-agent-policy.js";
+import {
+  MCP_OAUTH_SCOPES,
+  hasMcpOAuthScope,
+  verifyMcpOAuthAccessToken,
+} from "./oauth-token.js";
+
+export interface MCPConfig {
+  /** App name shown in MCP server info */
+  name: string;
+  /** Optional human-facing app title shown by MCP hosts that support titles. */
+  title?: string;
+  /**
+   * Canonical app id (directory under `apps/`, e.g. `mail`) this MCP server
+   * is mounted for. Optional & back-compat: when omitted the builtin
+   * cross-app tools fall back to lowercasing `name`. Used by `open_app` /
+   * `ask_app` / `create_workspace_app` to tell "this app" from a cross-app
+   * target so they resolve the *target* app's origin rather than echoing the
+   * current request origin.
+   */
+  appId?: string;
+  /** App description */
+  description: string;
+  /** Optional canonical website URL for hosts that surface MCP app details. */
+  websiteUrl?: string;
+  /** Optional app icons for MCP hosts that render server branding. */
+  icons?: Array<{
+    src: string;
+    mimeType?: string;
+    sizes?: string[];
+    theme?: "light" | "dark";
+  }>;
+  /** Version string (default "1.0.0") */
+  version?: string;
+  /** Action registry — same as agent chat and A2A */
+  actions: Record<string, ActionEntry>;
+  /**
+   * Full ("production") action surface served to an **authenticated real
+   * caller** — a connect-minted token, an `agent-native mcp install` stdio
+   * proxy (owner-email header / `AGENT_NATIVE_OWNER_EMAIL`), or a deployed /
+   * `AGENT_MODE=production` app. In local dev `actions` is intentionally the
+   * sparse, dev-toggled surface (builtins + read-only public-agent actions)
+   * so the local agent chat and unauthenticated dev probes don't see every
+   * mutating tool; but per the external-agents contract a real caller that
+   * connected with a token MUST get the full surface even in dev. When unset
+   * (production, where `actions` already IS the full set) the swap is a
+   * no-op. See `external-agents` skill, "Dev vs production tool surface".
+   */
+  productionActions?: Record<string, ActionEntry>;
+  /** Handler for the ask-agent meta-tool — runs the full agent loop */
+  askAgent?: (message: string) => Promise<string>;
+  /**
+   * Disable the generic cross-app builtin tools (`list_apps`, `open_app`,
+   * `ask_app`, `create_workspace_app`, `list_templates`). They are merged in
+   * by default so external agents get a stable verb set; a template action of
+   * the same name always wins (template precedence). Set to `false` only for
+   * a constrained / locked-down mount.
+   */
+  builtinCrossAppTools?: boolean;
+  /**
+   * Curated allow-list of action names served to **external connector** clients
+   * on a hosted multi-tenant deployment.
+   *
+   * Whenever this list is non-empty it is active by default for **every**
+   * caller — hosted connectors, code/stdio clients, and the local CLI alike.
+   * The MCP server trims both the advertised tool list *and* the callable
+   * surface to exactly these names (plus any builtin cross-app tools such as
+   * `list_apps` / `open_app`). Any tool call for a name **not** in the list is
+   * rejected — it is not merely hidden. This prevents the ~105-tool full
+   * catalog from landing in every external agent's context window and removes
+   * footguns (db-exec, seed-*, extension tools, browser-session tools, etc.)
+   * from connectors. It is no longer gated behind an environment variable, and
+   * the catalog is never inferred from the client name/user-agent.
+   *
+   * `tool-search` stays available in the compact catalog for discovery. A
+   * searched action still needs the connector catalog or authenticated-read
+   * policy before `tools/call`; callers who need the full surface up front opt in
+   * explicitly with `agent-native connect --full-catalog` (embeds a
+   * `catalog_scope: "full"` claim in the connect-minted JWT) or the
+   * deployment-wide `AGENT_NATIVE_MCP_FULL_CATALOG=1` env override.
+   *
+   * Declare this in your template's `createAgentChatPlugin` options rather than
+   * setting it on `MCPConfig` directly; the plugin copies it through.
+   */
+  connectorCatalog?: string[];
+  /**
+   * Optional policy for automatically exposing explicitly annotated,
+   * authenticated read actions to external MCP callers.
+   */
+  externalAgents?: ExternalAgentPolicy;
+}
+
+/**
+ * Identity extracted from a verified MCP bearer token / JWT. Used to wrap
+ * `entry.run()` and `config.askAgent()` calls in `runWithRequestContext`
+ * so downstream tools (db-query, accessFilter, resolveCredential) honour
+ * per-user / per-org scoping. Without this wrap the MCP endpoint would
+ * silently bypass tenant isolation. See finding #6 in
+ * /tmp/security-audit/12-mcp-a2a-agent.md.
+ */
+export interface MCPCallerIdentity {
+  userEmail: string | undefined;
+  orgId?: string | undefined;
+  orgDomain: string | undefined;
+  /** Present only for standard remote MCP OAuth access tokens. */
+  oauthScopes?: string[];
+  /** Present only for standard remote MCP OAuth access tokens. */
+  oauthClientId?: string;
+  /** Present only for framework-minted first-party MCP client tokens. */
+  firstPartyMcp?: boolean;
+}
+
+/** Per-request context used to turn an action's relative deep link into the
+ *  absolute web URL (and desktop `agentnative://` URL) the external agent
+ *  surfaces. Derived from the inbound request headers in `mountMCP`, or from
+ *  the resolved local app origin in the stdio standalone path. */
+export interface MCPRequestMeta {
+  /** Origin of the running app, e.g. `http://localhost:8100`. */
+  origin?: string;
+  /** Optional mount prefix for path-mounted apps, e.g. `/mail`. */
+  basePath?: string;
+  /** Optional client preference for which URL the *markdown* link uses. */
+  target?: "browser" | "desktop" | "terminal";
+  /**
+   * Best-effort caller label derived from MCP transport headers. Chat-style
+   * remote hosts should stay on the compact catalog; code/stdio clients can
+   * explicitly identify themselves to keep the full action surface.
+   */
+  clientName?: string;
+  /** Explicit framework client hint from `x-agent-native-mcp-client`. */
+  clientHint?: string;
+  /** Explicit opt-in to the full tool catalog for code/stdio style clients. */
+  fullCatalog?: boolean;
+  /**
+   * The caller authenticated with a real credential (verified A2A/connect
+   * JWT, matching ACCESS_TOKEN, or a forwarded owner-email header from
+   * `agent-native mcp install`) — not the unauthenticated local dev-open
+   * path. When true, `createMCPServerForRequest` serves
+   * `config.productionActions` (the full surface) instead of the sparse dev
+   * `config.actions`. Set by `mountMCP` from `verifyAuth`.
+   */
+  fullSurface?: boolean;
+  /**
+   * Whether this request may receive inline MCP App embeds (the `ui://`
+   * resource reference hosts render in an iframe). Resolved once per request by
+   * `createMCPServerForRequest` from `isMcpAppsInlineEnabled(identity)` — the
+   * deploy-toggleable kill switch. When `false`, no MCP App resource is
+   * advertised or referenced and tool results fall back to their deep-link
+   * text. Defaults to disabled when unset.
+   */
+  inlineMcpApps?: boolean;
+}
+
+const ASK_AGENT_DEFAULT_INLINE_WAIT_MS = 20_000;
+const ASK_AGENT_MAX_INLINE_WAIT_MS = 25_000;
+
+function boundedAskAgentWaitMs(raw: unknown): number {
+  if (raw == null || raw === "") return ASK_AGENT_DEFAULT_INLINE_WAIT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return ASK_AGENT_DEFAULT_INLINE_WAIT_MS;
+  return Math.max(
+    0,
+    Math.min(ASK_AGENT_MAX_INLINE_WAIT_MS, Math.trunc(parsed)),
+  );
+}
+
+function isExplicitAsyncAskAgent(raw: unknown): boolean {
+  return raw === true || raw === "true" || raw === 1 || raw === "1";
+}
+
+function formatAskAgentResult(result: unknown): string {
+  if (typeof result === "string") return result;
+  if (result && typeof result === "object") {
+    const record = result as Record<string, unknown>;
+    if (record.status === "completed" && typeof record.response === "string") {
+      return record.response;
+    }
+  }
+  const serialized = JSON.stringify(result);
+  return serialized === undefined ? String(result) : serialized;
+}
+
+/**
+ * Deploy-toggleable kill switch for inline MCP App embeds — the `ui://`
+ * resource reference hosts like Codex / Cursor / ChatGPT render in a sandboxed
+ * iframe. **Off by default**, so a not-yet-verified inline embed never reaches
+ * normal users; flip it on per environment with `AGENT_NATIVE_MCP_APPS_INLINE=1`
+ * and a redeploy. While the global switch is off, accounts listed in
+ * `AGENT_NATIVE_MCP_APPS_INLINE_ALLOW_EMAILS` (comma/space separated) still get
+ * inline embeds, so you can keep verifying a fix in production before enabling
+ * it for everyone. Requires no skills/instructions change — when disabled, tool
+ * results simply fall back to their deep-link text.
+ */
+export function isMcpAppsInlineEnabled(
+  identity: MCPCallerIdentity | undefined,
+): boolean {
+  const flag = process.env.AGENT_NATIVE_MCP_APPS_INLINE?.trim().toLowerCase();
+  if (flag === "1" || flag === "true" || flag === "yes" || flag === "on") {
+    return true;
+  }
+  const email = identity?.userEmail?.trim().toLowerCase();
+  if (email) {
+    const allowed = (
+      process.env.AGENT_NATIVE_MCP_APPS_INLINE_ALLOW_EMAILS ?? ""
+    )
+      .split(/[\s,]+/)
+      .map((value) => value.trim().toLowerCase())
+      .filter(Boolean);
+    if (allowed.includes(email)) return true;
+  }
+  return false;
+}
+
+type McpOAuthScope = (typeof MCP_OAUTH_SCOPES)[number];
+
+function isActionVisibleForOAuthScope(
+  entry: ActionEntry,
+  scopes: string[] | undefined,
+): boolean {
+  if (!scopes) return true;
+  const required: McpOAuthScope =
+    entry.readOnly === true ? "mcp:read" : "mcp:write";
+  return hasMcpOAuthScope(scopes, required);
+}
+
+const COMPACT_MCP_APP_CATALOG_BUILTINS = new Set([
+  "list_apps",
+  "open_app",
+  "ask_app",
+  "ask_app_status",
+  "create_embed_session",
+  // `tool-search` MUST stay in every compact/connector surface: it is how a
+  // compacted client discovers and loads any action on demand, which is what
+  // makes "small catalog by default" safe instead of limiting.
+  "tool-search",
+]);
+
+function isActionAdvertisedInCompactMcpAppCatalog(
+  name: string,
+  entry: ActionEntry,
+  config: MCPConfig,
+): boolean {
+  if (COMPACT_MCP_APP_CATALOG_BUILTINS.has(name)) return true;
+  if (
+    (entry.mcpApp as { compactCatalog?: unknown } | undefined)
+      ?.compactCatalog === true
+  ) {
+    return true;
+  }
+  if (config.builtinCrossAppTools === false && entry.mcpApp?.resource) {
+    return true;
+  }
+  return false;
+}
+
+function explicitlyRequestsFullMcpCatalog(
+  requestMeta: MCPRequestMeta | undefined,
+): boolean {
+  // Full catalog is a deliberate, rare opt-in — NEVER a default, and NEVER
+  // inferred from the client name / user-agent. It is reached only by an
+  // explicit deployment env or a token minted with
+  // `agent-native connect --full-catalog` (which embeds `catalog_scope: "full"`,
+  // surfaced here as requestMeta.fullCatalog). Dumping ~105 tool schemas
+  // (100k+ tokens) into a context window just because a client called itself
+  // "code"/"cursor"/"codex" was a recurring footgun. Everything else gets the
+  // connector/compact catalog plus `tool-search`, which keeps every tool
+  // discoverable; only permitted actions are callable without full opt-in.
+  if (process.env.AGENT_NATIVE_MCP_FULL_CATALOG === "1") return true;
+  return requestMeta?.fullCatalog === true;
+}
+
+const warnedFullCatalogKeys = new Set<string>();
+
+/**
+ * Loud, deduped warning emitted whenever the full MCP catalog is actually
+ * served. Full catalog is a deliberate, rare opt-in (env or a `--full-catalog`
+ * token claim); logging it makes an accidental ~100k-token tool dump visible
+ * instead of silent, so a regression can't quietly reintroduce the footgun.
+ */
+function warnFullCatalogServed(toolCount: number): void {
+  const source =
+    process.env.AGENT_NATIVE_MCP_FULL_CATALOG === "1"
+      ? "AGENT_NATIVE_MCP_FULL_CATALOG=1"
+      : "a token minted with --full-catalog (catalog_scope:full)";
+  const key = `${source}:${toolCount}`;
+  if (warnedFullCatalogKeys.has(key)) return;
+  warnedFullCatalogKeys.add(key);
+  console.warn(
+    `[agent-native] Serving the FULL MCP tool catalog (${toolCount} tools) via ${source}. ` +
+      `This is a large context payload meant to be a rare, explicit opt-in — most ` +
+      `clients should use the default compact/connector catalog + tool-search instead.`,
+  );
+}
+
+export function isAuthenticatedReadAction(entry: ActionEntry): boolean {
+  return (
+    entry.http !== false &&
+    entry.http?.method === "GET" &&
+    entry.readOnly === true &&
+    entry.publicAgent?.expose === true &&
+    entry.publicAgent.readOnly === true &&
+    entry.publicAgent.requiresAuth === true
+  );
+}
+
+/**
+ * Hard exclusion list for the `authenticatedReads: "auto"` derivation ONLY
+ * (see `autoAuthenticatedReadNames` below). Explicit `connectorCatalog`
+ * entries are a deliberate, reviewed choice made by the app and are NOT
+ * affected by this list — an app can still list any of these names in
+ * `connectorCatalog` on purpose.
+ *
+ * These are the footgun families this file's other comments already call
+ * out ("removes footguns (db-exec, seed-*, extension tools, browser-session
+ * tools, etc.)" above, and "keeps db-exec / seed-* / extension /
+ * browser-session footguns off the external surface" near the connector
+ * tier below): generic core SQL access, template demo/seed data, the
+ * extension-management suite, live browser-session control, and Context
+ * X-Ray internals. `isAuthenticatedReadAction` only inspects action
+ * metadata (http/readOnly/publicAgent flags) — nothing stops a future
+ * change from mis-annotating one of these with that exact flag set again,
+ * the way `db-query`/`db-schema` were briefly (and accidentally) annotated
+ * before it was caught in review. These names can never be auto-derived
+ * from metadata alone; exposing one to external callers requires an
+ * explicit `connectorCatalog` entry.
+ */
+const AUTO_READ_EXCLUDED_ACTION_NAMES = new Set([
+  "db-query",
+  "db-schema",
+  "db-exec",
+  "db-patch",
+  "context-manifest-get",
+  "context-preview-get",
+  "context-pin",
+  "context-evict",
+  "context-restore",
+  "context-report",
+]);
+
+/**
+ * Substring/prefix patterns for excluded name *families* that aren't a
+ * fixed, enumerable set: `seed-*` varies per app/template, and the
+ * extension-management and browser-session tool suites use varying verb
+ * prefixes around a shared noun (e.g. `list-extensions`, `create-extension`,
+ * `hide-extension`; `list-browser-sessions`, `run-browser-session-action`) —
+ * so a leading-prefix match alone would miss most of them.
+ */
+const AUTO_READ_EXCLUDED_ACTION_PATTERNS: RegExp[] = [
+  /^seed-/,
+  /extension/,
+  /browser-session/,
+];
+
+export function isAutoReadExcludedActionName(name: string): boolean {
+  return (
+    AUTO_READ_EXCLUDED_ACTION_NAMES.has(name) ||
+    AUTO_READ_EXCLUDED_ACTION_PATTERNS.some((pattern) => pattern.test(name))
+  );
+}
+
+function autoAuthenticatedReadNames(
+  actions: Record<string, ActionEntry>,
+  config: MCPConfig,
+): Set<string> {
+  if (config.externalAgents?.authenticatedReads !== "auto") return new Set();
+  return new Set(
+    Object.entries(actions)
+      .filter(
+        ([name, entry]) =>
+          isAuthenticatedReadAction(entry) &&
+          !isAutoReadExcludedActionName(name),
+      )
+      .map(([name]) => name),
+  );
+}
+
+function externalAgentDenySet(config: MCPConfig): Set<string> {
+  return new Set(
+    (config.externalAgents?.denyActions ?? [])
+      .map((name) => name.trim())
+      .filter(Boolean),
+  );
+}
+
+function externalAgentWritesAreAskAppOnly(config: MCPConfig): boolean {
+  return (
+    config.externalAgents?.writes === "ask_app_only" ||
+    (config.externalAgents?.authenticatedReads === "auto" &&
+      config.externalAgents?.writes !== "allowlisted")
+  );
+}
+
+interface ResolvedMcpAppResource {
+  uri: string;
+  legacyUris?: string[];
+  name: string;
+  title?: string;
+  description?: string;
+  html: ActionMcpAppResourceConfig["html"];
+  mimeType: typeof MCP_APP_MIME_TYPE;
+  _meta?: Record<string, unknown>;
+}
+
+interface McpAppResourceContext {
+  actionName: string;
+  appId?: string;
+  requestOrigin?: string;
+}
+
+interface VersionedMcpAppResourceUri {
+  uri: string;
+  legacyUris?: string[];
+}
+
+function metadataObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function originString(value: unknown): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  try {
+    return new URL(value).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+function hostSpecificDomainString(value: unknown): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const trimmed = value.trim();
+  try {
+    new URL(trimmed);
+    return undefined;
+  } catch {
+    return trimmed;
+  }
+}
+
+function withMcpChatBridgeParam(urlOrPath: string): string {
+  try {
+    const base = "http://agent-native.invalid";
+    const url = urlOrPath.startsWith("/")
+      ? new URL(urlOrPath, base)
+      : new URL(urlOrPath);
+    url.searchParams.set(MCP_APP_CHAT_BRIDGE_QUERY_PARAM, "1");
+    return urlOrPath.startsWith("/")
+      ? `${url.pathname}${url.search}${url.hash}`
+      : url.toString();
+  } catch {
+    return urlOrPath;
+  }
+}
+
+function isEmbedStartUrl(value: string): boolean {
+  try {
+    const base = "http://agent-native.invalid";
+    const url = value.startsWith("/") ? new URL(value, base) : new URL(value);
+    return url.pathname.includes("/_agent-native/embed/start");
+  } catch {
+    return value.includes("/_agent-native/embed/start");
+  }
+}
+
+function routePathFromOpenUrl(value: string): string | null {
+  try {
+    const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+    const url = hasScheme
+      ? new URL(value)
+      : new URL(value, "http://agent-native.invalid");
+    const route = `${url.pathname}${url.search}${url.hash}`;
+    if (!route.startsWith("/") || route.startsWith("//")) return null;
+    if (route.startsWith("/\\")) return null;
+    if (/^\/[a-z][a-z0-9+.-]*:/i.test(route)) return null;
+    return route;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Recursively redact embed-ticket-bearing URLs from any value before it gets
+ * serialized into a model-visible text payload. Embed start URLs carry a
+ * single-use ticket that grants iframe access to the user's session — they
+ * MUST stay in `_meta` (where the embed runtime can consume them) and never
+ * appear in `content[].text` for the LLM. This is the generic safety net for
+ * actions that return `{ embedStartUrl, ... }` without declaring
+ * `mcpApp.resource` (the resource path already strips them via
+ * `mcpAppStructuredContent`).
+ *
+ * Circular structures are replaced with a marker. Strings that embed an
+ * `isEmbedStartUrl` substring (e.g. a longer message that includes the URL)
+ * are replaced with `[hidden embed URL]`. Credential-like `ticket` fields are
+ * removed only inside an embed-signaled object/branch, so ordinary business
+ * fields from unrelated read actions remain faithful.
+ */
+const EMBED_RESULT_SENSITIVE_KEYS = new Set([
+  "embedTargetPath",
+  "embedExpiresAt",
+  "embedTicket",
+]);
+
+function isEmbedCredentialKey(key: string): boolean {
+  return key === "ticket" || /Ticket$/.test(key);
+}
+
+function containsEmbedRoutingSignal(
+  value: unknown,
+  seen = new WeakSet<object>(),
+): boolean {
+  if (typeof value === "string") return isEmbedStartUrl(value);
+  if (!value || typeof value !== "object") return false;
+  if (seen.has(value)) return false;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = value.some((item) => containsEmbedRoutingSignal(item, seen));
+    seen.delete(value);
+    return result;
+  }
+  for (const [key, val] of Object.entries(value)) {
+    if (EMBED_RESULT_SENSITIVE_KEYS.has(key)) {
+      seen.delete(value);
+      return true;
+    }
+    if (containsEmbedRoutingSignal(val, seen)) {
+      seen.delete(value);
+      return true;
+    }
+  }
+  seen.delete(value);
+  return false;
+}
+
+function purgeEmbedStartUrls(
+  value: unknown,
+  seen = new WeakSet<object>(),
+  embedContext = false,
+): unknown {
+  if (typeof value === "string") {
+    return isEmbedStartUrl(value) ? "[hidden embed URL]" : value;
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return "[circular result]";
+    seen.add(value);
+    // An embed marker in one array item puts the whole result in the embed
+    // routing context. Credential fields in sibling items must not survive
+    // just because the marker lives elsewhere in the array.
+    const arrayEmbedContext = embedContext || containsEmbedRoutingSignal(value);
+    const out = value.map((item) =>
+      purgeEmbedStartUrls(item, seen, arrayEmbedContext),
+    );
+    seen.delete(value);
+    return out;
+  }
+  if (value && typeof value === "object") {
+    if (seen.has(value)) return "[circular result]";
+    seen.add(value);
+    const entries = Object.entries(value as Record<string, unknown>);
+    const localEmbedContext = embedContext || containsEmbedRoutingSignal(value);
+    const out: Record<string, unknown> = {};
+    for (const [key, val] of entries) {
+      if (
+        EMBED_RESULT_SENSITIVE_KEYS.has(key) ||
+        (localEmbedContext && isEmbedCredentialKey(key))
+      ) {
+        continue;
+      }
+      if (typeof val === "string" && isEmbedStartUrl(val)) {
+        // Drop the key entirely for object-typed inputs so a tool result like
+        // `{ embedStartUrl: "..." }` does not appear at all in the LLM text.
+        continue;
+      }
+      out[key] = purgeEmbedStartUrls(val, seen, localEmbedContext);
+    }
+    seen.delete(value);
+    return out;
+  }
+  return value;
+}
+
+// True when a tool result carries SOME content. An errored/no-plan result comes
+// back empty (`{}` / null) and would render an empty embed box. We gate on "has
+// content", not "has a URL" — valid embeds often carry data but no URL (the
+// shell mints the embed-start itself).
+function mcpResultHasContent(result: unknown): boolean {
+  if (result == null) return false;
+  if (typeof result === "string") return result.trim().length > 0;
+  if (Array.isArray(result)) return result.length > 0;
+  if (typeof result === "object") return Object.keys(result).length > 0;
+  return Boolean(result);
+}
+
+function mcpAppEmbedOpenLinkMeta(
+  result: unknown,
+  resource: ResolvedMcpAppResource,
+  meta: MCPRequestMeta | undefined,
+): Record<string, unknown> {
+  const out = metadataObject(result);
+  const embedStartUrl =
+    typeof out.embedStartUrl === "string"
+      ? out.embedStartUrl
+      : out.embed === true &&
+          typeof out.url === "string" &&
+          out.url.includes("/_agent-native/embed/start")
+        ? out.url
+        : null;
+  if (!embedStartUrl) return {};
+
+  const webUrl = toAbsoluteOpenUrl(
+    withMcpChatBridgeParam(embedStartUrl),
+    meta?.origin,
+  );
+  const deepLinkUrl =
+    typeof out.deepLinkUrl === "string" ? out.deepLinkUrl : null;
+  const fallbackLabel = resource.title ?? resource.name ?? "app";
+  const label =
+    typeof out.app === "string" && out.app.trim()
+      ? `Open ${out.app.trim()}`
+      : fallbackLabel;
+  const view =
+    typeof out.view === "string" && out.view.trim()
+      ? out.view.trim()
+      : typeof out.path === "string" && out.path.trim()
+        ? out.path.trim()
+        : undefined;
+  // Only fabricate an open URL when there is a real path-like value: an
+  // explicit deepLinkUrl, or a non-embed `out.url`, or a leading-slash
+  // `view`/`path` that's already a route. Bare view-name strings like
+  // "inbox" or "deck" must NOT be turned into `${origin}/inbox` — apps
+  // route views at app-specific paths (e.g. slides routes `view: "deck"`
+  // at `/deck/:id`), so a synthesized origin-relative URL is just a 404.
+  // In that case omit `openLink` entirely; the embedStart meta carries
+  // the actual launch reference.
+  const pathFromRouteLike =
+    view && view.startsWith("/")
+      ? view
+      : typeof out.path === "string" && out.path.trim().startsWith("/")
+        ? out.path.trim()
+        : undefined;
+  const explicitOpenUrl = deepLinkUrl
+    ? deepLinkUrl
+    : typeof out.url === "string" && !isEmbedStartUrl(out.url)
+      ? out.url
+      : pathFromRouteLike;
+  const safeOpenUrl = explicitOpenUrl
+    ? toAbsoluteOpenUrl(explicitOpenUrl, meta?.origin)
+    : null;
+  // Embed open links expose the safe browser target in `webUrl`, but the
+  // desktop URL must enter the app through the registered scheme so Electron
+  // can focus the right webview. Preserve the full route/query in the `to`
+  // param; focus ids are often only present on `url`, not `out.params`.
+  const desktopDeepLinkUrl = (() => {
+    if (!safeOpenUrl) return null;
+    const app =
+      typeof out.app === "string" && out.app.trim()
+        ? out.app.trim()
+        : undefined;
+    if (!app) return safeOpenUrl;
+    if (isAgentNativeOpenDeepLink(safeOpenUrl)) {
+      return toDesktopOpenUrl(safeOpenUrl);
+    }
+    const targetRoute = routePathFromOpenUrl(safeOpenUrl);
+    if (!targetRoute) return safeOpenUrl;
+    const viewParam =
+      typeof out.view === "string" && out.view.trim() ? out.view.trim() : "";
+    const params =
+      out.params && typeof out.params === "object" && !Array.isArray(out.params)
+        ? (out.params as Record<
+            string,
+            string | number | boolean | null | undefined
+          >)
+        : undefined;
+    return toDesktopOpenUrl(
+      buildDeepLink({
+        app,
+        view: viewParam,
+        to: targetRoute,
+        ...(params ? { params } : {}),
+      }),
+    );
+  })();
+
+  return {
+    "agent-native/embedStart": {
+      startUrl: webUrl,
+      ...(typeof out.embedExpiresAt === "number"
+        ? { expiresAt: out.embedExpiresAt }
+        : {}),
+    },
+    ...(safeOpenUrl
+      ? {
+          "agent-native/openLink": {
+            label,
+            ...(view ? { view } : {}),
+            webUrl: safeOpenUrl,
+            desktopUrl: desktopDeepLinkUrl ?? safeOpenUrl,
+            vscodeUrl: toVsCodeOpenUrl(safeOpenUrl),
+          },
+        }
+      : {}),
+  };
+}
+
+async function withServerMintedMcpAppEmbedStart(
+  result: unknown,
+  meta: MCPRequestMeta | undefined,
+): Promise<unknown> {
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    return result;
+  }
+
+  const out = result as Record<string, unknown>;
+  if (out.embed !== true) return result;
+  if (typeof out.embedStartUrl === "string" && out.embedStartUrl.trim()) {
+    return result;
+  }
+  if (
+    typeof out.url === "string" &&
+    out.url.trim() &&
+    isEmbedStartUrl(out.url)
+  ) {
+    return result;
+  }
+
+  const candidate = [out.url, out.path, out.deepLinkUrl].find(
+    (value): value is string =>
+      typeof value === "string" && value.trim().length > 0,
+  );
+  if (!candidate) return result;
+
+  const trimmed = candidate.trim();
+  const isPath = trimmed.startsWith("/") && !trimmed.startsWith("//");
+  const isAbsoluteHttp = /^https?:\/\//i.test(trimmed);
+  if (!isPath && !isAbsoluteHttp) return result;
+  if (isAbsoluteHttp && !meta?.origin) return result;
+
+  const ctx = getRequestContext();
+  const ownerEmail = ctx?.userEmail?.trim();
+  if (!ownerEmail) return result;
+
+  const { normalizeEmbedTargetPath, createEmbedSessionTicket } =
+    await import("../server/embed-session.js");
+  const { buildEmbedStartPath } = await import("../server/embed-route.js");
+  const targetPath = normalizeEmbedTargetPath(
+    withMcpChatBridgeParam(trimmed),
+    meta?.origin,
+  );
+  if (!targetPath) return result;
+
+  const ticket = await createEmbedSessionTicket({
+    ownerEmail,
+    orgId: ctx?.orgId,
+    targetPath,
+    scope: typeof out.chrome === "string" ? out.chrome : null,
+  });
+  const startPath = buildEmbedStartPath(ticket.ticket);
+  const embedStartUrl = meta?.origin
+    ? new URL(startPath, meta.origin).toString()
+    : startPath;
+
+  return {
+    ...out,
+    embedStartUrl,
+    embedTargetPath: targetPath,
+    embedExpiresAt: ticket.expiresAt,
+  };
+}
+
+/**
+ * Build the deep-link content block + structured `_meta` for a tool result.
+ * Best-effort: any throw / nullish link is swallowed so a bad `link` builder
+ * never fails the tool call.
+ */
+export function buildLinkArtifacts(
+  entry: ActionEntry,
+  args: Record<string, any>,
+  result: any,
+  meta: MCPRequestMeta | undefined,
+): {
+  block?: { type: "text"; text: string };
+  _meta?: Record<string, unknown>;
+} {
+  if (typeof entry.link !== "function") return {};
+  try {
+    const lk = entry.link({ args: args ?? {}, result });
+    if (!lk?.url) return {};
+    const linkUrl = isAgentNativeOpenDeepLink(lk.url)
+      ? withCollapsedAgentSidebarParam(lk.url)
+      : lk.url;
+    const webUrl = toAbsoluteOpenUrl(linkUrl, meta?.origin);
+    const desktopUrl = toDesktopOpenUrl(linkUrl);
+    const vscodeUrl = toVsCodeOpenUrl(webUrl);
+    const markdownUrl = meta?.target === "desktop" ? desktopUrl : webUrl;
+    return {
+      block: { type: "text", text: `\n\n[${lk.label} →](${markdownUrl})` },
+      _meta: {
+        "agent-native/openLink": {
+          label: lk.label,
+          view: lk.view,
+          webUrl,
+          desktopUrl,
+          vscodeUrl,
+        },
+      },
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge the generic cross-app builtin tools into the config's action
+ * registry. **Template actions take precedence**: if a template defines an
+ * action with the same name as a builtin (e.g. its own `list_apps`), the
+ * template entry wins and the builtin is dropped. This mirrors the
+ * template-over-workspace-core precedence in `autoDiscoverActions`.
+ *
+ * The builtins are pure-ish navigators / scaffolders; they call back into the
+ * same `config.actions` / `config.askAgent` so there is no second agent loop.
+ */
+function mergeBuiltinTools(
+  config: MCPConfig,
+  baseActions: Record<string, ActionEntry>,
+  requestMeta?: MCPRequestMeta,
+): Record<string, ActionEntry> {
+  if (config.builtinCrossAppTools === false) return baseActions;
+  const builtins = getBuiltinCrossAppTools(config, requestMeta);
+  const merged: Record<string, ActionEntry> = { ...builtins };
+  // Template / app actions overwrite same-named builtins.
+  for (const [name, entry] of Object.entries(baseActions)) {
+    merged[name] = entry;
+  }
+  return merged;
+}
+
+function absoluteMetadataUrl(
+  value: string | undefined,
+  requestMeta?: MCPRequestMeta,
+): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  try {
+    if (requestMeta?.origin) {
+      const basePath = requestMeta.basePath ?? getConfiguredAppBasePath();
+      const appBase = `${requestMeta.origin.replace(/\/+$/, "")}${basePath}/`;
+      const appLocalValue =
+        trimmed.startsWith("/") && !trimmed.startsWith("//")
+          ? trimmed.replace(/^\/+/, "")
+          : trimmed;
+      return new URL(appLocalValue, appBase).href;
+    }
+    return new URL(trimmed).href;
+  } catch {
+    return trimmed;
+  }
+}
+
+function mcpServerInfo(config: MCPConfig, requestMeta?: MCPRequestMeta) {
+  const websiteUrl = absoluteMetadataUrl(config.websiteUrl, requestMeta);
+  const icons = config.icons
+    ?.map((icon) => {
+      const src = absoluteMetadataUrl(icon.src, requestMeta);
+      if (!src) return null;
+      return {
+        src,
+        ...(icon.mimeType ? { mimeType: icon.mimeType } : {}),
+        ...(icon.sizes?.length ? { sizes: icon.sizes } : {}),
+        ...(icon.theme ? { theme: icon.theme } : {}),
+      };
+    })
+    .filter((icon): icon is NonNullable<typeof icon> => Boolean(icon));
+  return {
+    name: config.name,
+    version: config.version ?? "1.0.0",
+    ...(config.title?.trim() ? { title: config.title.trim() } : {}),
+    ...(config.description?.trim()
+      ? { description: config.description.trim() }
+      : {}),
+    ...(websiteUrl ? { websiteUrl } : {}),
+    ...(icons?.length ? { icons } : {}),
+  };
+}
+
+function safeUiSegment(value: string | undefined, fallback: string): string {
+  const normalized = (value || fallback)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || fallback;
+}
+
+// ChatGPT and Claude cache MCP App resource HTML by `ui://` URI. Bump this
+// when the shared shell changes in a way that must invalidate host caches.
+const MCP_APP_RESOURCE_SHELL_VERSION = "shell-v64";
+
+function legacyDefaultMcpAppUri(config: MCPConfig, actionName: string): string {
+  const app = safeUiSegment(config.appId ?? config.name, "agent-native");
+  const action = safeUiSegment(actionName, "tool");
+  return `ui://${app}/${action}`;
+}
+
+function versionMcpAppResourceUri(
+  rawUri: string,
+): VersionedMcpAppResourceUri | null {
+  const uri = rawUri.trim();
+  if (!uri.startsWith("ui://")) return null;
+  const versionSuffix = `/${MCP_APP_RESOURCE_SHELL_VERSION}`;
+  let versionedUri: string;
+  try {
+    const parsed = new URL(uri);
+    const path = parsed.pathname.replace(/\/+$/g, "");
+    parsed.pathname = /\/shell-v\d+$/.test(path)
+      ? path.replace(/\/shell-v\d+$/, versionSuffix)
+      : `${path}${versionSuffix}`;
+    versionedUri = parsed.toString();
+  } catch {
+    return null;
+  }
+  return {
+    uri: versionedUri,
+    ...(versionedUri !== uri ? { legacyUris: [uri] } : {}),
+  };
+}
+
+function unversionMcpAppResourceUri(uri: string): string | null {
+  if (!uri.startsWith("ui://")) return null;
+  try {
+    const parsed = new URL(uri);
+    parsed.pathname = parsed.pathname
+      .replace(/\/+$/g, "")
+      .replace(/\/shell-v\d+$/g, "");
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+
+function normalizeMcpAppResourceUriForMatch(uri: unknown): string | null {
+  if (typeof uri !== "string") return null;
+  const trimmed = uri.trim();
+  if (!trimmed.startsWith("ui://")) return null;
+  return (
+    unversionMcpAppResourceUri(trimmed) ??
+    trimmed.replace(/\/+$/g, "").replace(/\/shell-v\d+(?=([?#]|$))/g, "")
+  );
+}
+
+function matchesMcpAppResourceUri(
+  resourceUri: VersionedMcpAppResourceUri,
+  requestedUri: unknown,
+): boolean {
+  if (typeof requestedUri !== "string") return false;
+  const requested = requestedUri.trim();
+  if (resourceUri.uri === requested) return true;
+  if (resourceUri.legacyUris?.includes(requested)) return true;
+  const requestedBase = normalizeMcpAppResourceUriForMatch(requested);
+  const currentBase = normalizeMcpAppResourceUriForMatch(resourceUri.uri);
+  return Boolean(requestedBase && currentBase && requestedBase === currentBase);
+}
+
+function getMcpAppResourceUri(
+  config: MCPConfig,
+  actionName: string,
+  entry: ActionEntry,
+): VersionedMcpAppResourceUri | null {
+  const resource = entry.mcpApp?.resource;
+  if (!resource) return null;
+  const baseUri =
+    resource.uri?.trim() || legacyDefaultMcpAppUri(config, actionName);
+  return versionMcpAppResourceUri(baseUri);
+}
+
+function expandRequestOriginSources(
+  sources: string[] | undefined,
+  requestMeta?: MCPRequestMeta,
+): string[] | undefined {
+  if (!sources) return undefined;
+  const origin = requestMeta?.origin;
+  return sources.flatMap((source) =>
+    source === MCP_APP_REQUEST_ORIGIN_CSP_SOURCE && origin
+      ? [origin]
+      : [source],
+  );
+}
+
+function openAiWidgetCsp(
+  cspConfig: ActionMcpAppCsp | undefined,
+  requestMeta?: MCPRequestMeta,
+): Record<string, string[]> | undefined {
+  if (!cspConfig) return undefined;
+  const csp: Record<string, string[]> = {};
+  const connectDomains = expandRequestOriginSources(
+    cspConfig.connectDomains,
+    requestMeta,
+  );
+  const resourceDomains = expandRequestOriginSources(
+    cspConfig.resourceDomains,
+    requestMeta,
+  );
+  const frameDomains = expandRequestOriginSources(
+    cspConfig.frameDomains,
+    requestMeta,
+  );
+  if (connectDomains?.length) csp.connect_domains = connectDomains;
+  if (resourceDomains?.length) csp.resource_domains = resourceDomains;
+  if (frameDomains?.length) csp.frame_domains = frameDomains;
+  return Object.keys(csp).length > 0 ? csp : undefined;
+}
+
+function mcpAppUiMeta(
+  resource: ActionMcpAppResourceConfig,
+  resolvedCsp: ActionMcpAppCsp | undefined,
+  requestMeta?: MCPRequestMeta,
+  description?: string,
+): Record<string, unknown> | undefined {
+  const base =
+    resource._meta && typeof resource._meta === "object"
+      ? { ...resource._meta }
+      : {};
+  const existingUi =
+    base.ui && typeof base.ui === "object" && !Array.isArray(base.ui)
+      ? (base.ui as Record<string, unknown>)
+      : {};
+  const ui: Record<string, unknown> = { ...existingUi };
+  delete ui.domain;
+  if (resolvedCsp) {
+    ui.csp = {
+      ...resolvedCsp,
+      connectDomains: expandRequestOriginSources(
+        resolvedCsp.connectDomains,
+        requestMeta,
+      ),
+      resourceDomains: expandRequestOriginSources(
+        resolvedCsp.resourceDomains,
+        requestMeta,
+      ),
+      frameDomains: expandRequestOriginSources(
+        resolvedCsp.frameDomains,
+        requestMeta,
+      ),
+      baseUriDomains: expandRequestOriginSources(
+        resolvedCsp.baseUriDomains,
+        requestMeta,
+      ),
+    };
+  }
+  if (resource.permissions) ui.permissions = resource.permissions;
+  const hostSpecificDomain =
+    hostSpecificDomainString(resource.domain) ??
+    hostSpecificDomainString(existingUi.domain);
+  if (hostSpecificDomain) ui.domain = hostSpecificDomain;
+  const openAiWidgetDomain =
+    originString(resource.domain) ??
+    originString(ui.domain) ??
+    originString(existingUi.domain) ??
+    originString(requestMeta?.origin);
+  if (typeof resource.prefersBorder === "boolean") {
+    ui.prefersBorder = resource.prefersBorder;
+  }
+  if (Object.keys(ui).length > 0) base.ui = ui;
+  if (description && base["openai/widgetDescription"] == null) {
+    base["openai/widgetDescription"] = description;
+  }
+  if (
+    typeof resource.prefersBorder === "boolean" &&
+    base["openai/widgetPrefersBorder"] == null
+  ) {
+    base["openai/widgetPrefersBorder"] = resource.prefersBorder;
+  }
+  const openAiCsp = openAiWidgetCsp(resolvedCsp, requestMeta);
+  if (openAiCsp && base["openai/widgetCSP"] == null) {
+    base["openai/widgetCSP"] = openAiCsp;
+  }
+  if (openAiWidgetDomain && base["openai/widgetDomain"] == null) {
+    base["openai/widgetDomain"] = openAiWidgetDomain;
+  }
+  return Object.keys(base).length > 0 ? base : undefined;
+}
+
+async function resolveMcpAppCsp(
+  resource: ActionMcpAppResourceConfig,
+  ctx: McpAppResourceContext,
+): Promise<ActionMcpAppCsp | undefined> {
+  if (!resource.csp) return undefined;
+  return typeof resource.csp === "function"
+    ? await resource.csp(ctx)
+    : resource.csp;
+}
+
+async function resolveMcpAppResource(
+  config: MCPConfig,
+  actionName: string,
+  entry: ActionEntry,
+  requestMeta?: MCPRequestMeta,
+): Promise<ResolvedMcpAppResource | null> {
+  const resource = entry.mcpApp?.resource;
+  if (!resource) return null;
+  // NB: the inline kill switch is intentionally NOT enforced here. This
+  // resolver also backs `resources/read`, which must keep serving the shell
+  // for a URI the host already holds (e.g. a cached descriptor) so it degrades
+  // gracefully instead of throwing a hard `-32603`. The switch is enforced at
+  // the *advertisement/render* sites (`tools/list` descriptor meta,
+  // `tools/call` result meta, `resources/list`) so disabled embeds never get
+  // advertised in the first place.
+  const resolvedUri = getMcpAppResourceUri(config, actionName, entry);
+  if (!resolvedUri) return null;
+  const description = resource.description ?? entry.tool.description;
+  const resolvedCsp = await resolveMcpAppCsp(resource, {
+    actionName,
+    appId: config.appId,
+    requestOrigin: requestMeta?.origin,
+  });
+  const resourceMeta = mcpAppUiMeta(
+    resource,
+    resolvedCsp,
+    requestMeta,
+    description,
+  );
+  return {
+    uri: resolvedUri.uri,
+    ...(resolvedUri.legacyUris ? { legacyUris: resolvedUri.legacyUris } : {}),
+    name: resource.name?.trim() || actionName,
+    ...(resource.title ? { title: resource.title } : {}),
+    ...(description ? { description } : {}),
+    html: resource.html,
+    mimeType: resource.mimeType ?? MCP_APP_MIME_TYPE,
+    ...(resourceMeta ? { _meta: resourceMeta } : {}),
+  };
+}
+
+async function resolveMcpAppResourceSafely(
+  config: MCPConfig,
+  actionName: string,
+  entry: ActionEntry,
+  requestMeta?: MCPRequestMeta,
+): Promise<ResolvedMcpAppResource | null> {
+  try {
+    return await resolveMcpAppResource(config, actionName, entry, requestMeta);
+  } catch (error) {
+    console.warn(
+      `[mcp] Skipping MCP App resource for action "${actionName}" because its metadata could not be resolved.`,
+      error,
+    );
+    return null;
+  }
+}
+
+async function getMcpAppResources(
+  config: MCPConfig,
+  actions: Record<string, ActionEntry>,
+  requestMeta?: MCPRequestMeta,
+): Promise<ResolvedMcpAppResource[]> {
+  // Advertisement path (resources/list + resources/templates/list): suppressed
+  // by the inline kill switch so disabled embeds are never listed.
+  if (!requestMeta?.inlineMcpApps) return [];
+  const resources = await Promise.all(
+    Object.entries(actions).map(([name, entry]) =>
+      resolveMcpAppResourceSafely(config, name, entry, requestMeta),
+    ),
+  );
+  return resources.filter((resource): resource is ResolvedMcpAppResource =>
+    Boolean(resource),
+  );
+}
+
+function renderMcpAppHtml(
+  resource: ResolvedMcpAppResource,
+  actionName: string,
+  config: MCPConfig,
+  requestMeta?: MCPRequestMeta,
+): string {
+  if (typeof resource.html === "function") {
+    return resource.html({
+      actionName,
+      appId: config.appId,
+      requestOrigin: requestMeta?.origin,
+    });
+  }
+  return resource.html;
+}
+
+function openAiToolDescriptorMeta(
+  resource: ResolvedMcpAppResource,
+): Record<string, unknown> {
+  const label = resource.title ?? resource.name;
+  const widgetCsp = metadataObject(resource._meta?.["openai/widgetCSP"]);
+  return {
+    "openai/outputTemplate": resource.uri,
+    "openai/toolInvocation/invoking": `Opening ${label}`,
+    "openai/toolInvocation/invoked": `${label} ready`,
+    "openai/widgetAccessible": true,
+    ...(Object.keys(widgetCsp).length > 0
+      ? { "openai/widgetCSP": widgetCsp }
+      : {}),
+  };
+}
+
+function openAiToolResultMeta(
+  resource: ResolvedMcpAppResource,
+): Record<string, unknown> {
+  const label = resource.title ?? resource.name;
+  const widgetCsp = metadataObject(resource._meta?.["openai/widgetCSP"]);
+  return {
+    "openai/outputTemplate": resource.uri,
+    "openai/toolInvocation/invoking": `Opening ${label}`,
+    "openai/toolInvocation/invoked": `${label} ready`,
+    "openai/widgetAccessible": true,
+    ...(Object.keys(widgetCsp).length > 0
+      ? { "openai/widgetCSP": widgetCsp }
+      : {}),
+  };
+}
+
+function mcpAppToolUiMeta(
+  resource: ResolvedMcpAppResource,
+  visibility: unknown,
+): Record<string, unknown> {
+  return {
+    resourceUri: resource.uri,
+    visibility: Array.isArray(visibility) ? visibility : ["model", "app"],
+  };
+}
+
+function primitiveValue(value: unknown): value is string | number | boolean {
+  return (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  );
+}
+
+function mcpAppStructuredContent(
+  result: unknown,
+  meta: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  const purged = purgeEmbedStartUrls(result);
+  const out: Record<string, unknown> =
+    purged && typeof purged === "object" && !Array.isArray(purged)
+      ? { ...(purged as Record<string, unknown>) }
+      : primitiveValue(purged)
+        ? { result: purged }
+        : {};
+  for (const key of ["embedStartUrl", "startUrl"]) {
+    const value = out[key];
+    if (typeof value === "string" && isEmbedStartUrl(value)) delete out[key];
+  }
+  if (typeof out.url === "string" && isEmbedStartUrl(out.url)) {
+    delete out.url;
+  }
+  // Internal embed-routing fields belong in `_meta["agent-native/embedStart"]`
+  // (consumed by the embed runtime), not in `structuredContent` (read by the
+  // LLM). `embedTargetPath` reveals the exact route + thread/draft id the user
+  // is looking at; `embedExpiresAt` is an unintended timestamp; ticket-bearing
+  // fields are single-use credentials. Drop all of them unconditionally.
+  const openLink = meta?.["agent-native/openLink"];
+  if (openLink && typeof openLink === "object" && !Array.isArray(openLink)) {
+    const webUrl = (openLink as Record<string, unknown>).webUrl;
+    if (typeof webUrl === "string" && isEmbedStartUrl(webUrl)) {
+      return Object.keys(out).length > 0 ? out : { status: "ok" };
+    }
+    out.openLink = openLink;
+    if (typeof webUrl === "string" && !out.url) out.url = webUrl;
+  }
+  return Object.keys(out).length > 0 ? out : { status: "ok" };
+}
+
+function truncateToolText(value: string, max = 2000): string {
+  if (value.length <= max) return value;
+  return `${value.slice(0, max - 1)}…`;
+}
+
+function conciseMcpAppToolText(
+  name: string,
+  result: unknown,
+  structuredContent: Record<string, unknown>,
+): string {
+  if (typeof result === "string") return truncateToolText(result);
+  const message = structuredContent.message;
+  if (typeof message === "string" && message.trim()) {
+    return truncateToolText(message.trim());
+  }
+  const title = structuredContent.title ?? structuredContent.name;
+  if (typeof title === "string" && title.trim()) {
+    return `${title.trim()} is ready.`;
+  }
+  const id = structuredContent.id;
+  if (typeof id === "string" && id.trim()) {
+    return `${name} completed for ${id.trim()}.`;
+  }
+  return `${name} completed.`;
+}
+
+function isSuccessOnlyResult(value: Record<string, unknown>): boolean {
+  const keys = Object.keys(value);
+  if (keys.length === 0) return true;
+  return keys.every((key) => {
+    const item = value[key];
+    if (key === "ok" || key === "success") return item === true;
+    if (key === "status") {
+      return item === "ok" || item === "success" || item === "completed";
+    }
+    return false;
+  });
+}
+
+function conciseToolResultText(
+  name: string,
+  result: unknown,
+  options?: { preserveObjectResult?: boolean },
+): string {
+  const purged = purgeEmbedStartUrls(result);
+  if (typeof purged === "string") return truncateToolText(purged);
+  if (purged === true || purged == null) return `${name} completed.`;
+  if (purged && typeof purged === "object" && !Array.isArray(purged)) {
+    const record = purged as Record<string, unknown>;
+    // Read-only actions are data reads, not mutations. Keep their object
+    // payload available to MCP clients in the text fallback too; the
+    // structuredContent branch below is the lossless path for clients that
+    // support it. Mutating/action-style results retain the concise status
+    // text so we do not unexpectedly dump write results into conversations.
+    if (options?.preserveObjectResult) {
+      const text = JSON.stringify(purged);
+      return text === undefined ? `${name} completed.` : truncateToolText(text);
+    }
+    const message = record.message ?? record.summary;
+    if (typeof message === "string" && message.trim()) {
+      return truncateToolText(message.trim());
+    }
+    const id = record.id ?? record.planId ?? record.commentId;
+    const title = record.title ?? record.name;
+    if (typeof title === "string" && title.trim()) {
+      const titleText = title.trim();
+      return typeof id === "string" && id.trim()
+        ? `${titleText} (${id.trim()}) is ready.`
+        : `${titleText} is ready.`;
+    }
+    if (typeof id === "string" && id.trim()) {
+      return `${name} completed for ${id.trim()}.`;
+    }
+    const link = record.url ?? record.webUrl ?? record.path;
+    if (typeof link === "string" && link.trim()) {
+      return `${name} completed: ${truncateToolText(link.trim(), 500)}`;
+    }
+    if (isSuccessOnlyResult(record)) return `${name} completed.`;
+  }
+  const text = JSON.stringify(purged);
+  return text === undefined ? `${name} completed.` : truncateToolText(text);
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server creation — converts ActionEntry registry to MCP tools
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a fully-wired MCP `Server` for a single request / session.
+ *
+ * Shared by the stateless Streamable-HTTP mount (`mountMCP`) and the stdio
+ * standalone transport. The HTTP mount passes the per-request origin via
+ * `requestMeta`; the stdio standalone path passes the resolved local app
+ * origin so deep links still become absolute URLs.
+ */
+export async function createMCPServerForRequest(
+  config: MCPConfig,
+  identity: MCPCallerIdentity | undefined,
+  requestMeta?: MCPRequestMeta,
+) {
+  const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
+  const {
+    ListToolsRequestSchema,
+    CallToolRequestSchema,
+    ListResourcesRequestSchema,
+    ReadResourceRequestSchema,
+    ListResourceTemplatesRequestSchema,
+  } = await import("@modelcontextprotocol/sdk/types.js");
+
+  // Resolve the effective caller identity. JWT / header-derived identity
+  // (passed by `mountMCP` via `verifyAuth`) wins. When the caller passed no
+  // identity — the stdio **standalone** path — fall back to the
+  // `AGENT_NATIVE_OWNER_EMAIL` env the `agent-native mcp install` flow writes
+  // into the `agent-native mcp serve` process env, so standalone tool runs are
+  // tenant-scoped to the configured owner instead of running unscoped. Stays
+  // undefined for true dev-open (no token, no secret, no owner) — behavior
+  // there is unchanged.
+  const ownerFromEnv = process.env.AGENT_NATIVE_OWNER_EMAIL?.trim();
+  const effectiveIdentity: MCPCallerIdentity | undefined =
+    identity ??
+    (ownerFromEnv
+      ? { userEmail: ownerFromEnv, orgDomain: undefined }
+      : undefined);
+
+  // Resolve the inline-MCP-App kill switch once per request from the effective
+  // identity + environment, then thread it through `requestMeta` so every
+  // resource/tool handler below honors the same decision. An explicit value on
+  // the incoming meta (tests / embedded callers) wins.
+  requestMeta = {
+    ...(requestMeta ?? {}),
+    inlineMcpApps:
+      requestMeta?.inlineMcpApps ?? isMcpAppsInlineEnabled(effectiveIdentity),
+  };
+
+  // The action set the request handlers operate on = base actions + generic
+  // cross-app builtins (template wins on name collision). An authenticated
+  // real caller (connect-minted token / `mcp install` owner / production —
+  // `requestMeta.fullSurface`, or the stdio standalone path identified by
+  // `AGENT_NATIVE_OWNER_EMAIL`) gets the full `productionActions` surface
+  // even in local dev; the unauthenticated dev-open path keeps the sparse
+  // `config.actions`. See `external-agents` skill, "Dev vs production tool
+  // surface".
+  const useFullSurface = requestMeta?.fullSurface === true || !!ownerFromEnv;
+  const baseActions =
+    useFullSurface && config.productionActions
+      ? config.productionActions
+      : config.actions;
+  const actions = mergeBuiltinTools(config, baseActions, requestMeta);
+  const visibleActions = Object.fromEntries(
+    Object.entries(actions).filter(([, entry]) =>
+      isActionVisibleForOAuthScope(entry, effectiveIdentity?.oauthScopes),
+    ),
+  );
+  const fullCatalogRequested = explicitlyRequestsFullMcpCatalog(requestMeta);
+  // Compact/connector is the DEFAULT for every caller — hosted connectors,
+  // code clients (Claude Code / Cursor / Codex), and the local CLI alike. The
+  // full ~105-tool catalog is served only on the explicit opt-in above, so a
+  // host can never dump every action schema into one giant tool card. The
+  // `mcp:apps` scope still lands on this compact MCP-Apps surface; with no
+  // opt-in, everyone else does too.
+  const compactMcpAppCatalog = !fullCatalogRequested;
+  const advertisedActionsBeforeConnector = compactMcpAppCatalog
+    ? Object.fromEntries(
+        Object.entries(visibleActions).filter(([name, entry]) =>
+          isActionAdvertisedInCompactMcpAppCatalog(name, entry, config),
+        ),
+      )
+    : visibleActions;
+  const autoReadNames = autoAuthenticatedReadNames(visibleActions, config);
+  const connectorNames = new Set([
+    ...(config.connectorCatalog ?? []),
+    ...autoReadNames,
+  ]);
+  const denyNames = externalAgentDenySet(config);
+  const automaticConnectorPolicyActive =
+    config.externalAgents?.authenticatedReads === "auto";
+  // Connector-catalog tier: when a template declares a connector allow-list,
+  // serve exactly that curated surface plus any explicitly annotated
+  // authenticated reads from `externalAgents.authenticatedReads: "auto"`.
+  // This stays compact by default and keeps db-exec / seed-* / extension /
+  // browser-session footguns off the external surface.
+  const connectorCatalogActive =
+    (connectorNames.size > 0 || automaticConnectorPolicyActive) &&
+    !fullCatalogRequested;
+  // When the connector catalog is active, filter directly from visibleActions
+  // rather than advertisedActionsBeforeConnector. This ensures the connector
+  // tier is an independent, template-declared surface that doesn't accidentally
+  // narrow to just the compact-catalog builtins when shouldUseCompactMcpCatalogByDefault
+  // would have activated the compact catalog for the same caller.
+  const advertisedActions = connectorCatalogActive
+    ? Object.fromEntries(
+        Object.entries(visibleActions).filter(([name, entry]) => {
+          if (denyNames.has(name)) return false;
+          if (COMPACT_MCP_APP_CATALOG_BUILTINS.has(name)) return true;
+          if (!connectorNames.has(name)) return false;
+          if (
+            externalAgentWritesAreAskAppOnly(config) &&
+            entry.readOnly !== true
+          ) {
+            return false;
+          }
+          return true;
+        }),
+      )
+    : advertisedActionsBeforeConnector;
+  if (fullCatalogRequested) {
+    warnFullCatalogServed(Object.keys(advertisedActions).length);
+  }
+  const supportsMcpApps =
+    compactMcpAppCatalog ||
+    Object.values(advertisedActions).some((entry) =>
+      Boolean(entry.mcpApp?.resource),
+    );
+  const server = new Server(mcpServerInfo(config, requestMeta), {
+    capabilities: {
+      tools: {},
+      ...(supportsMcpApps
+        ? {
+            resources: {},
+            extensions: {
+              [MCP_APP_EXTENSION_ID]: {
+                mimeTypes: [MCP_APP_MIME_TYPE],
+              },
+            },
+          }
+        : {}),
+    },
+  });
+
+  // Resolve orgId once per request (DB lookup) so subsequent wraps are
+  // synchronous. The caller identity may be undefined for true dev-open —
+  // in that case we run with no userEmail/orgId, which makes downstream
+  // tools that require per-user scope return empty results rather than
+  // cross-tenant data (the safe default).
+  const orgIdPromise = resolveMcpIdentityOrgId(effectiveIdentity);
+
+  /**
+   * Wrap a callback in
+   * `runWithRequestContext({ userEmail, orgId, requestOrigin }, fn)`.
+   * Both the tools/list and tools/call handlers go through this so
+   * downstream `accessFilter`, `resolveCredential`, and per-user MCP
+   * visibility checks see the verified caller's identity. `requestOrigin`
+   * is the live server origin derived from the inbound request (same value
+   * used to absolutize deep links) so actions that build fetchable URLs
+   * (e.g. design `export-coding-handoff`'s signed raw-code URL) resolve the
+   * correct local-workspace origin instead of a prod/localhost fallback.
+   */
+  async function withCallerContext<T>(fn: () => Promise<T>): Promise<T> {
+    const orgId = await orgIdPromise;
+    return runWithRequestContext(
+      {
+        userEmail: effectiveIdentity?.userEmail,
+        orgId,
+        ...(requestMeta?.origin ? { requestOrigin: requestMeta.origin } : {}),
+      },
+      fn,
+    ) as Promise<T>;
+  }
+
+  // tools/list — return all actions + ask-agent meta-tool. Wrapped in the
+  // request context so per-user MCP visibility (mcp-client/visibility.ts)
+  // applies to the listing too.
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return withCallerContext(async () => {
+      const tools = await Promise.all(
+        Object.entries(advertisedActions).map(async ([name, entry]) => {
+          const hasLink = typeof entry.link === "function";
+          const mcpAppResource = await resolveMcpAppResourceSafely(
+            config,
+            name,
+            entry,
+            requestMeta,
+          );
+          const rawToolMeta =
+            (entry.tool as any)._meta &&
+            typeof (entry.tool as any)._meta === "object" &&
+            !Array.isArray((entry.tool as any)._meta)
+              ? { ...((entry.tool as any)._meta as Record<string, unknown>) }
+              : {};
+          const toolMeta = {
+            ...rawToolMeta,
+            // Advertisement path: only tag the tool with its inline-embed
+            // descriptor when the kill switch is on, so disabled embeds never
+            // prompt a host to render/read the `ui://` resource.
+            ...(mcpAppResource && requestMeta?.inlineMcpApps
+              ? {
+                  ...openAiToolDescriptorMeta(mcpAppResource),
+                  [MCP_APP_RESOURCE_URI_META_KEY]: mcpAppResource.uri,
+                  ui: mcpAppToolUiMeta(
+                    mcpAppResource,
+                    entry.mcpApp?.visibility ??
+                      metadataObject(rawToolMeta.ui).visibility,
+                  ),
+                }
+              : {}),
+          };
+          const baseDescription = entry.tool.description ?? name;
+          const annotations: Record<string, unknown> = {
+            readOnlyHint: entry.readOnly === true,
+            destructiveHint: entry.publicAgent?.isConsequential === true,
+            openWorldHint: false,
+          };
+          if (hasLink) annotations["agent-native/producesOpenLink"] = true;
+          return {
+            name,
+            description: hasLink
+              ? `${baseDescription} After calling, surface the returned "Open in … →" link to the user.`
+              : baseDescription,
+            inputSchema: entry.tool.parameters ?? {
+              type: "object" as const,
+              properties: {},
+            },
+            ...(Object.keys(toolMeta).length > 0 ? { _meta: toolMeta } : {}),
+            annotations,
+          };
+        }),
+      );
+
+      if (
+        !compactMcpAppCatalog &&
+        !connectorCatalogActive &&
+        config.askAgent &&
+        hasMcpOAuthScope(effectiveIdentity?.oauthScopes, "mcp:write")
+      ) {
+        tools.push({
+          name: "ask-agent",
+          description:
+            "Send a natural-language message to the app's AI agent and get a response. " +
+            "Use this for complex, multi-step tasks that require the agent's reasoning " +
+            "and full context about the app. On hosted MCP, the server waits briefly " +
+            "for fast completions and returns a taskId plus ask_app_status polling " +
+            "instructions when the agent needs longer.",
+          inputSchema: {
+            type: "object" as const,
+            properties: {
+              message: {
+                type: "string",
+                description: "The message to send to the agent",
+              },
+              async: {
+                type: "boolean",
+                description:
+                  "Start a durable task and return immediately with a taskId.",
+              },
+              maxWaitMs: {
+                type: "number",
+                description:
+                  "Maximum inline wait in milliseconds. Hosted MCP clamps this to 25000ms.",
+              },
+            },
+            required: ["message"],
+          },
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: false,
+          },
+        });
+      }
+
+      return { tools };
+    });
+  });
+
+  // tools/call — dispatch to action registry or ask-agent. Wrapped in the
+  // request context so the action's `run(args)` and `askAgent()` execute
+  // with the verified caller's identity, not the platform default.
+  server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
+    return withCallerContext(async () => {
+      const { name, arguments: args } = request.params;
+
+      if (name === "ask-agent" && config.askAgent) {
+        if (compactMcpAppCatalog || connectorCatalogActive) {
+          return {
+            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            isError: true,
+          };
+        }
+        if (!hasMcpOAuthScope(effectiveIdentity?.oauthScopes, "mcp:write")) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Forbidden: OAuth scope does not allow ask-agent",
+              },
+            ],
+            isError: true,
+          };
+        }
+        const message = args?.message ?? "";
+        try {
+          // Keep the legacy meta-tool compatible for local callers, but use
+          // the same durable A2A submission path as ask_app whenever this is
+          // an HTTP/hosted request. A full agent loop must never be held open
+          // for minutes behind one MCP tools/call request. Always route
+          // through ask_app's own run() — even with no request origin, since
+          // it now bounds that case too via its process-local inline-task
+          // fallback (ask-app-inline-tasks.ts) instead of us awaiting
+          // config.askAgent() here unbounded. This is the shared helper: no
+          // second task map to keep in sync.
+          const hostedAskApp = getBuiltinCrossAppTools(
+            config,
+            requestMeta,
+          ).ask_app;
+          const result = await hostedAskApp.run({
+            message,
+            async: isExplicitAsyncAskAgent(args?.async),
+            maxWaitMs: isExplicitAsyncAskAgent(args?.async)
+              ? 0
+              : boundedAskAgentWaitMs(args?.maxWaitMs),
+          });
+          return {
+            content: [{ type: "text", text: formatAskAgentResult(result) }],
+          };
+        } catch (err: any) {
+          return {
+            content: [{ type: "text", text: `Error: ${err.message}` }],
+            isError: true,
+          };
+        }
+      }
+
+      // Connector-catalog tier: when active, callableActions === advertisedActions
+      // (the filtered set). Non-listed tools are not callable — mirroring how
+      // compactMcpAppCatalog gates calls on advertisedActions.
+      const callableActions =
+        compactMcpAppCatalog || connectorCatalogActive
+          ? advertisedActions
+          : actions;
+      const entry = callableActions[name];
+      if (!entry) {
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+      }
+      if (
+        !isActionVisibleForOAuthScope(entry, effectiveIdentity?.oauthScopes)
+      ) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Forbidden: OAuth scope does not allow tool ${name}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      try {
+        // We're inside `withCallerContext`, so the request-context getters
+        // resolve the verified MCP caller's identity (do NOT inject a dev
+        // fallback). Tag the call as an external-agent MCP dispatch.
+        const result = await entry.run((args as Record<string, string>) ?? {}, {
+          userEmail: getRequestUserEmail(),
+          orgId: getRequestOrgId() ?? null,
+          caller: "mcp",
+          actionName: name,
+        });
+        const mcpResult = isMcpActionResult(result) ? result : null;
+        const rawResult = mcpResult ? mcpResult.raw : result;
+        const resultForClient = mcpResult ? mcpResult.text : result;
+        const mcpResultIsError =
+          !!mcpResult &&
+          !!mcpResult.raw &&
+          typeof mcpResult.raw === "object" &&
+          (mcpResult.raw as Record<string, unknown>).isError === true;
+        // Render path: only treat the result as an inline embed when the kill
+        // switch is on. When off, `mcpAppResource` is null so every embed
+        // branch below degrades to the plain deep-link artifacts the tool would
+        // otherwise return — no `openai/outputTemplate`, no minted embed-start,
+        // no embed structuredContent — so the host shows a link, not an iframe.
+        const mcpAppResourceCandidate = requestMeta?.inlineMcpApps
+          ? await resolveMcpAppResourceSafely(config, name, entry, requestMeta)
+          : null;
+        const rawResultForClient = mcpAppResourceCandidate
+          ? await withServerMintedMcpAppEmbedStart(rawResult, requestMeta)
+          : rawResult;
+        // Only attach the embed widget for a non-error result that has content.
+        const embedHasContent = mcpResultHasContent(rawResultForClient);
+        const mcpAppResource =
+          mcpAppResourceCandidate && !mcpResultIsError && embedHasContent
+            ? mcpAppResourceCandidate
+            : null;
+        // `openai/outputTemplate` is declared at the tool level, so the host
+        // renders a widget for every call regardless of result _meta. The only
+        // per-result signal it honors is `isError` (shows error text, no widget),
+        // so treat an embed tool that produced nothing as an error.
+        const embedProducedNothing =
+          !!mcpAppResourceCandidate && !mcpResultIsError && !embedHasContent;
+        const { block, _meta } = buildLinkArtifacts(
+          entry,
+          (args as Record<string, any>) ?? {},
+          rawResultForClient,
+          requestMeta,
+        );
+        const responseMeta: Record<string, unknown> = {
+          ...(_meta ?? {}),
+          ...(mcpAppResource
+            ? mcpAppEmbedOpenLinkMeta(
+                rawResultForClient,
+                mcpAppResource,
+                requestMeta,
+              )
+            : {}),
+          ...(mcpAppResource ? openAiToolResultMeta(mcpAppResource) : {}),
+        };
+        const toolUiMeta = metadataObject((entry.tool as any)._meta?.ui);
+        const toolVisibility = toolUiMeta.visibility;
+        const isAppOnlyVisibility =
+          Array.isArray(toolVisibility) &&
+          toolVisibility.length > 0 &&
+          toolVisibility.every((v) => v === "app");
+        const readOnlyStructuredResult =
+          entry.readOnly === true &&
+          rawResultForClient &&
+          typeof rawResultForClient === "object"
+            ? Array.isArray(rawResultForClient)
+              ? { items: rawResultForClient }
+              : rawResultForClient
+            : undefined;
+        const structuredContent = mcpAppResource
+          ? mcpAppStructuredContent(rawResultForClient, responseMeta)
+          : isAppOnlyVisibility &&
+              rawResult &&
+              typeof rawResult === "object" &&
+              !Array.isArray(rawResult)
+            ? (rawResult as Record<string, unknown>)
+            : readOnlyStructuredResult
+              ? mcpAppStructuredContent(readOnlyStructuredResult, responseMeta)
+              : undefined;
+        const text = mcpAppResource
+          ? conciseMcpAppToolText(name, resultForClient, structuredContent!)
+          : conciseToolResultText(name, resultForClient, {
+              preserveObjectResult: entry.readOnly === true,
+            });
+        const content: any[] = [{ type: "text", text }];
+        if (block) content.push(block);
+        return {
+          content,
+          ...(mcpResultIsError || embedProducedNothing
+            ? { isError: true }
+            : {}),
+          ...(structuredContent ? { structuredContent } : {}),
+          ...(Object.keys(responseMeta).length > 0
+            ? { _meta: responseMeta }
+            : {}),
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    });
+  });
+
+  if (supportsMcpApps) {
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      return withCallerContext(async () => {
+        const mcpAppResources = await getMcpAppResources(
+          config,
+          advertisedActions,
+          requestMeta,
+        );
+        return {
+          resources: mcpAppResources.map((resource) => ({
+            uri: resource.uri,
+            name: resource.name,
+            ...(resource.title ? { title: resource.title } : {}),
+            ...(resource.description
+              ? { description: resource.description }
+              : {}),
+            mimeType: resource.mimeType,
+            ...(resource._meta ? { _meta: resource._meta } : {}),
+          })),
+        };
+      });
+    });
+
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+      return withCallerContext(async () => {
+        const mcpAppResources = await getMcpAppResources(
+          config,
+          advertisedActions,
+          requestMeta,
+        );
+        return {
+          resourceTemplates: mcpAppResources.map((resource) => ({
+            uriTemplate: resource.uri,
+            name: resource.name,
+            ...(resource.title ? { title: resource.title } : {}),
+            ...(resource.description
+              ? { description: resource.description }
+              : {}),
+            mimeType: resource.mimeType,
+            ...(resource._meta ? { _meta: resource._meta } : {}),
+          })),
+        };
+      });
+    });
+
+    server.setRequestHandler(
+      ReadResourceRequestSchema,
+      async (request: any) => {
+        return withCallerContext(async () => {
+          const uri = request.params?.uri;
+          let found: {
+            actionName: string;
+            resource: ResolvedMcpAppResource;
+          } | null = null;
+          for (const [name, entry] of Object.entries(advertisedActions)) {
+            const resourceUri = getMcpAppResourceUri(config, name, entry);
+            if (!resourceUri || !matchesMcpAppResourceUri(resourceUri, uri)) {
+              continue;
+            }
+            const resource = await resolveMcpAppResourceSafely(
+              config,
+              name,
+              entry,
+              requestMeta,
+            );
+            if (resource) {
+              found = { actionName: name, resource };
+              break;
+            }
+            // resolveMcpAppResourceSafely returned null (e.g. an async resolver
+            // threw) — keep scanning the remaining candidates rather than
+            // aborting and reporting the resource as missing.
+          }
+          if (!found) {
+            throw new Error(`MCP App resource not found: ${uri}`);
+          }
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: found.resource.mimeType,
+                text: renderMcpAppHtml(
+                  found.resource,
+                  found.actionName,
+                  config,
+                  requestMeta,
+                ),
+                ...(found.resource._meta
+                  ? { _meta: found.resource._meta }
+                  : {}),
+              },
+            ],
+          };
+        });
+      },
+    );
+  }
+
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// Auth — reuses the same pattern as A2A (Bearer token or JWT). Shared so the
+// HTTP mount and any stdio-side auth-aware helper resolve identity identically.
+// ---------------------------------------------------------------------------
+
+export function getAccessTokens(): string[] {
+  const single = process.env.ACCESS_TOKEN;
+  const multi = process.env.ACCESS_TOKENS;
+  const tokens: string[] = [];
+  if (single) tokens.push(single);
+  if (multi) {
+    tokens.push(
+      ...multi
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean),
+    );
+  }
+  return tokens;
+}
+
+/**
+ * Resolve the caller identity for a static-token (or dev-open) auth path.
+ *
+ * Static `ACCESS_TOKEN` / `ACCESS_TOKENS` auth carries no per-caller claims,
+ * so without this the MCP endpoint would run every tool with
+ * `userEmail === undefined` and per-user / per-org scoped actions
+ * (`accessFilter`, `resolveAccess`, `resolveCredential`) would return
+ * empty / wrong data. The `agent-native mcp install` flow writes
+ * `AGENT_NATIVE_OWNER_EMAIL` into the client config env and the stdio proxy
+ * forwards it as the `X-Agent-Native-Owner-Email` request header (see
+ * `mcp/stdio.ts#authHeaders`). We trust that owner hint *only* on the
+ * static-token path — JWT auth already carries a cryptographically verified
+ * `sub`, so the header is ignored there and never widens JWT scope.
+ *
+ * Precedence is server-trusted-first: the server process's
+ * `AGENT_NATIVE_OWNER_EMAIL` env (set out-of-band by the operator / deploy)
+ * ALWAYS wins, and a client-supplied `X-Agent-Native-Owner-Email` header is
+ * honored *only as a fallback when that env is unset*. A static `ACCESS_TOKEN`
+ * is a shared bearer secret; letting a request header override a
+ * server-configured owner would let anyone holding a leaked token act as any
+ * user. The header path remains for the single-tenant local-dev install flow
+ * where the app server process has no owner env and the token *is* the
+ * workspace secret; multi-tenant deployments must use A2A JWT (verified `sub`),
+ * not a static token, for per-user scope.
+ *
+ * Returns `undefined` when no owner email is available (true dev-open: no
+ * token, no secret, no owner) so behavior there stays unchanged.
+ */
+function deriveStaticTokenIdentity(
+  ownerEmailHeader: string | undefined,
+): MCPCallerIdentity | undefined {
+  const owner =
+    process.env.AGENT_NATIVE_OWNER_EMAIL?.trim() ||
+    (typeof ownerEmailHeader === "string" && ownerEmailHeader.trim()) ||
+    "";
+  if (!owner) return undefined;
+  return { userEmail: owner, orgDomain: undefined };
+}
+
+export function getBearerToken(
+  authHeader: string | undefined,
+): string | undefined {
+  if (!authHeader) return undefined;
+  const match = /^Bearer\s+(.+)$/i.exec(authHeader.trim());
+  return match?.[1]?.trim() || undefined;
+}
+
+function addSecretCandidate(
+  candidates: string[],
+  secret: string | null | undefined,
+): void {
+  const trimmed = secret?.trim();
+  if (!trimmed || candidates.includes(trimmed)) return;
+  candidates.push(trimmed);
+}
+
+async function verifyA2AJwtForMcp(
+  token: string,
+  resourceUrl?: string | string[],
+): Promise<Record<string, unknown> | null> {
+  const jose = await import("jose");
+  let unverifiedPayload: Record<string, unknown> | null = null;
+  try {
+    unverifiedPayload = jose.decodeJwt(token) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  const candidateSecrets: string[] = [];
+  addSecretCandidate(candidateSecrets, process.env.A2A_SECRET);
+
+  const orgDomain =
+    typeof unverifiedPayload.org_domain === "string"
+      ? unverifiedPayload.org_domain
+      : undefined;
+  if (orgDomain) {
+    try {
+      const { getA2ASecretByDomain } = await import("../org/context.js");
+      addSecretCandidate(
+        candidateSecrets,
+        await getA2ASecretByDomain(orgDomain),
+      );
+    } catch {
+      // DB not ready or org lookup unavailable — fall back to other candidates.
+    }
+  }
+
+  const firstPartyMcp = unverifiedPayload.agent_native_first_party_mcp === true;
+  const audiences = firstPartyMcp ? mcpAudienceList(resourceUrl) : null;
+  if (firstPartyMcp && !audiences?.length) return null;
+
+  for (const secret of candidateSecrets) {
+    const encodedSecret = new TextEncoder().encode(secret);
+    for (const audience of audiences ?? [undefined]) {
+      try {
+        const { payload } = await jose.jwtVerify(
+          token,
+          encodedSecret,
+          audience ? { audience } : undefined,
+        );
+        return payload as Record<string, unknown>;
+      } catch {
+        // Try the next candidate without exposing which secret matched.
+      }
+    }
+  }
+
+  return null;
+}
+
+function mcpAudienceList(resource: string | string[] | undefined): string[] {
+  const raw = Array.isArray(resource) ? resource : resource ? [resource] : [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const value of raw) {
+    const normalized = value.replace(/\/+$/, "");
+    if (normalized && !seen.has(normalized)) {
+      seen.add(normalized);
+      out.push(normalized);
+    }
+  }
+  return out;
+}
+
+async function isConnectTokenAllowed(
+  jti: string | undefined,
+): Promise<boolean> {
+  if (!jti) return false;
+  try {
+    const { isJtiRevoked, touchTokenUsed } = await import("./connect-store.js");
+    if (await isJtiRevoked(jti)) return false;
+    // Best-effort usage telemetry — never blocks / throws.
+    void touchTokenUsed(jti);
+  } catch {
+    // Store import / lookup failed — fail open. Signature verification already
+    // passed; this only gates explicit revokes.
+  }
+  return true;
+}
+
+/**
+ * Verify the inbound auth header. Returns:
+ *   - { authed: true, identity } when verified — `identity` is derived from
+ *     the JWT (`sub` / `org_domain`) for JWT auth, or from the
+ *     `AGENT_NATIVE_OWNER_EMAIL` env / `X-Agent-Native-Owner-Email` header
+ *     for static-token auth (the `agent-native mcp install` flow). `identity`
+ *     is undefined only for true dev-open with no owner hint.
+ *   - { authed: false } on rejection.
+ *
+ * When A2A_SECRET is set we extract the JWT's `sub` (caller email) and
+ * `org_domain` claims so the MCP endpoint can wrap tool runs in
+ * `runWithRequestContext({ userEmail, orgId })`. Without that wrap, the
+ * MCP endpoint loses tenant identity and downstream `accessFilter` /
+ * `resolveCredential` calls fall back to platform-wide defaults.
+ *
+ * `ownerEmailHeader` is the forwarded `X-Agent-Native-Owner-Email` value; it
+ * is consulted ONLY on the static-token / dev-open path (never to influence
+ * verified JWT identity), so the install flow runs tools as the configured
+ * owner instead of an unscoped anonymous caller.
+ */
+export async function verifyAuth(
+  authHeader: string | undefined,
+  ownerEmailHeader?: string,
+  options: { allowDevOpen?: boolean; resourceUrl?: string | string[] } = {},
+): Promise<{
+  authed: boolean;
+  identity?: MCPCallerIdentity;
+  /**
+   * The caller presented a real credential — a verified A2A/connect JWT, a
+   * matching ACCESS_TOKEN, or (on the no-auth-configured path) a forwarded
+   * owner-email header from `agent-native mcp install`. Drives the full vs
+   * sparse MCP tool surface in local dev. The pure unauthenticated dev-open
+   * path (no secret, no token, no owner header) is `false`.
+   */
+  fullSurface?: boolean;
+  /**
+   * The caller explicitly opted up to the full connector catalog by minting
+   * their token with `--full-catalog` (or equivalent). When `true`, the
+   * compact/connector-catalog tier filter (active by default whenever a
+   * `connectorCatalog` is declared) is bypassed for this caller. Derived from a
+   * `catalog_scope: "full"` claim in the verified A2A/connect JWT.
+   */
+  fullCatalog?: boolean;
+}> {
+  // No auth configured → allow only when the route caller has already
+  // established that this is a loopback/local dev request. Still honour an
+  // owner hint there so the local install/connect flow stays tenant-scoped.
+  const accessTokens = getAccessTokens();
+  const hasA2ASecret = !!process.env.A2A_SECRET?.trim();
+  const token = getBearerToken(authHeader);
+  if (token) {
+    const oauthIdentity = await verifyMcpOAuthAccessToken(
+      token,
+      options.resourceUrl,
+    );
+    if (oauthIdentity) {
+      if (
+        oauthIdentity.clientId === MCP_CONNECT_OAUTH_CLIENT_ID &&
+        !(await isConnectTokenAllowed(oauthIdentity.jti))
+      ) {
+        return { authed: false };
+      }
+      return {
+        authed: true,
+        identity: {
+          userEmail: oauthIdentity.userEmail,
+          ...(oauthIdentity.orgId ? { orgId: oauthIdentity.orgId } : {}),
+          orgDomain: oauthIdentity.orgDomain,
+          oauthScopes: oauthIdentity.scopes,
+          oauthClientId: oauthIdentity.clientId,
+        },
+        fullSurface: true,
+        // Per-token opt-up: `catalog_scope: "full"` in the OAuth token
+        // bypasses the connector-catalog tier filter on hosted deployments.
+        fullCatalog: oauthIdentity.catalogScope === "full",
+      };
+    }
+  }
+  if (accessTokens.length === 0 && !hasA2ASecret && !token) {
+    if (options.allowDevOpen === false) {
+      return { authed: false };
+    }
+    return {
+      authed: true,
+      identity: deriveStaticTokenIdentity(ownerEmailHeader),
+      // `mcp install`'s stdio proxy forwards an owner-email header even when
+      // the local app has no secret configured — that is a real, identified
+      // caller and gets the full surface. A bare browser/curl dev probe with
+      // no owner hint stays on the sparse dev surface.
+      fullSurface: !!(ownerEmailHeader && ownerEmailHeader.trim()),
+    };
+  }
+
+  if (!token) return { authed: false };
+
+  // Try an A2A JWT via the shared A2A_SECRET first, then the caller org's
+  // synced A2A secret when the token carries org_domain.
+  const payload = await verifyA2AJwtForMcp(token, options.resourceUrl);
+  if (payload) {
+    const tokenScope =
+      typeof payload.scope === "string" ? payload.scope : undefined;
+    if (tokenScope && tokenScope !== MCP_CONNECT_SCOPE) {
+      return { authed: false };
+    }
+
+    // Connect-minted tokens (scope === "mcp-connect") carry a random `jti`
+    // and are individually revocable. Only these tokens hit the revoke
+    // store — ordinary A2A delegation JWTs skip the DB lookup entirely so
+    // the hot path is unchanged. The signature was already
+    // cryptographically verified, so failing open here only widens the
+    // explicit-revoke gate, never the trust boundary.
+    if (tokenScope === MCP_CONNECT_SCOPE) {
+      if (!(await isConnectTokenAllowed(payload.jti as string | undefined))) {
+        return { authed: false };
+      }
+    }
+
+    return {
+      authed: true,
+      identity: {
+        userEmail: typeof payload.sub === "string" ? payload.sub : undefined,
+        // Org SERVICE tokens (connect-minted, synthetic `svc-*@service.<org>`
+        // subject) carry the org id directly as an `org_id` claim so the
+        // resolved identity is org-scoped even when the org has no domain
+        // mapping. Personal/delegation JWTs don't set the claim — unchanged.
+        ...(typeof payload.org_id === "string" && payload.org_id
+          ? { orgId: payload.org_id as string }
+          : {}),
+        orgDomain:
+          typeof payload.org_domain === "string"
+            ? (payload.org_domain as string)
+            : undefined,
+        ...(payload.agent_native_first_party_mcp === true
+          ? { firstPartyMcp: true }
+          : {}),
+      },
+      // Verified JWT (connect-minted or A2A delegation) — a real caller.
+      fullSurface: true,
+      // Per-token opt-up: `catalog_scope: "full"` embedded at mint time via
+      // `agent-native connect --full-catalog` bypasses the connector-catalog
+      // tier filter on hosted multi-tenant deployments.
+      fullCatalog: payload.catalog_scope === "full",
+    };
+  }
+
+  if (accessTokens.length === 0 && !hasA2ASecret) {
+    if (options.allowDevOpen === false) {
+      return { authed: false };
+    }
+    return {
+      authed: true,
+      identity: deriveStaticTokenIdentity(ownerEmailHeader),
+      fullSurface: !!(ownerEmailHeader && ownerEmailHeader.trim()),
+    };
+  }
+
+  // Try ACCESS_TOKEN / ACCESS_TOKENS exact match. Static tokens carry no
+  // per-caller claims, so derive identity from the forwarded owner-email
+  // hint (install flow) — otherwise tools would run unscoped. Compare in
+  // constant time (matching the rest of this subsystem's secret-comparison
+  // discipline); node:crypto is imported dynamically because this module is
+  // bundled into the serverless function and avoids static Node-only imports.
+  if (accessTokens.length > 0) {
+    const { timingSafeEqual } = await import("node:crypto");
+    const candidate = Buffer.from(token, "utf8");
+    const matched = accessTokens.some((configured) => {
+      const expected = Buffer.from(configured, "utf8");
+      return (
+        expected.length === candidate.length &&
+        timingSafeEqual(expected, candidate)
+      );
+    });
+    if (matched) {
+      return {
+        authed: true,
+        identity: deriveStaticTokenIdentity(ownerEmailHeader),
+        // Matched a configured ACCESS_TOKEN — a real caller.
+        fullSurface: true,
+      };
+    }
+  }
+
+  return { authed: false };
+}
+
+export async function resolveOrgIdFromDomain(
+  orgDomain: string | undefined,
+): Promise<string | undefined> {
+  if (!orgDomain) return undefined;
+  try {
+    const { resolveOrgByDomain } = await import("../org/context.js");
+    const org = await resolveOrgByDomain(orgDomain);
+    return org?.orgId ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function resolveMcpIdentityOrgId(
+  identity: MCPCallerIdentity | undefined,
+): Promise<string | undefined> {
+  if (identity?.orgId) return identity.orgId;
+
+  const orgIdFromDomain = await resolveOrgIdFromDomain(identity?.orgDomain);
+  if (orgIdFromDomain) return orgIdFromDomain;
+
+  const userEmail = identity?.userEmail?.trim();
+  if (!userEmail) return undefined;
+  try {
+    const { resolveOrgIdForEmail } = await import("../org/context.js");
+    return (await resolveOrgIdForEmail(userEmail)) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}