@agent-native/core 0.128.3 → 0.129.0

package/corpus/core/src/mcp/build-server.ts

@@ -18,6 +18,14 @@
  * — it can be bundled into the serverless function alongside `mountMCP`.
  */
 
+import type {
+  CallToolResult,
+  InputRequiredResult,
+  RequestStateCodec,
+  ServerContext,
+  Tool,
+} from "@modelcontextprotocol/server";
+
 import {
   MCP_APP_EXTENSION_ID,
   MCP_APP_MIME_TYPE,
@@ -45,6 +53,10 @@ import {
   withCollapsedAgentSidebarParam,
 } from "../shared/agent-sidebar-url.js";
 import { MCP_APP_CHAT_BRIDGE_QUERY_PARAM } from "../shared/embed-auth.js";
+import {
+  consumeMcpApprovalGrant,
+  createMcpApprovalGrant,
+} from "./approval-store.js";
 import { getBuiltinCrossAppTools } from "./builtin-tools.js";
 import {
   MCP_CONNECT_OAUTH_CLIENT_ID,
@@ -163,6 +175,81 @@ export interface MCPCallerIdentity {
   firstPartyMcp?: boolean;
 }
 
+const MCP_ACTION_APPROVAL_TTL_SECONDS = 10 * 60;
+const MCP_ACTION_APPROVAL_INPUT_KEY = "actionApproval";
+
+interface McpActionApprovalState {
+  version: 1;
+  nonce: string;
+  actionName: string;
+  argumentsHash: string;
+  expiresAt: number;
+}
+
+function canonicalJson(value: unknown): string {
+  if (
+    value === null ||
+    typeof value === "boolean" ||
+    typeof value === "string"
+  ) {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("MCP action arguments must contain finite numbers");
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+      .join(",")}}`;
+  }
+  throw new TypeError("MCP action arguments must be JSON values");
+}
+
+async function sha256Base64Url(value: string): Promise<string> {
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(value),
+  );
+  const bytes = new Uint8Array(digest);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function mcpApprovalPrincipal(
+  identity: MCPCallerIdentity | undefined,
+  orgId: string | undefined,
+  requestMeta: MCPRequestMeta | undefined,
+): string {
+  return canonicalJson({
+    caller: "mcp",
+    userEmail: identity?.userEmail?.trim().toLowerCase() ?? "",
+    orgId: orgId ?? identity?.orgId ?? "",
+    orgDomain: identity?.orgDomain?.trim().toLowerCase() ?? "",
+    oauthClientId: identity?.oauthClientId ?? "",
+    firstPartyMcp: identity?.firstPartyMcp === true,
+    origin: requestMeta?.origin ?? "",
+  });
+}
+
+function actionApprovalError(message: string): CallToolResult {
+  return {
+    content: [{ type: "text" as const, text: message }],
+    isError: true,
+  };
+}
+
 /** 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
@@ -935,6 +1022,10 @@ function mcpServerInfo(config: MCPConfig, requestMeta?: MCPRequestMeta) {
   };
 }
 
+function compareMcpCatalogValues(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
 function safeUiSegment(value: string | undefined, fallback: string): string {
   const normalized = (value || fallback)
     .trim()
@@ -1419,14 +1510,13 @@ export async function createMCPServerForRequest(
   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");
+    ResourceNotFoundError,
+    Server,
+    acceptedContent,
+    createRequestStateCodec,
+    inputRequired,
+  } = await import("@modelcontextprotocol/server");
 
   // Resolve the effective caller identity. JWT / header-derived identity
   // (passed by `mountMCP` via `verifyAuth`) wins. When the caller passed no
@@ -1527,6 +1617,39 @@ export async function createMCPServerForRequest(
   if (fullCatalogRequested) {
     warnFullCatalogServed(Object.keys(advertisedActions).length);
   }
+  // Resolve orgId once per request (DB lookup) so approval state and every
+  // downstream action see the same authenticated principal.
+  const orgIdPromise = resolveMcpIdentityOrgId(effectiveIdentity);
+  const hasApprovalActions = Object.values(actions).some(
+    (entry) => entry.needsApproval !== undefined,
+  );
+  const approvalOrgId = hasApprovalActions ? await orgIdPromise : undefined;
+  const approvalPrincipal = hasApprovalActions
+    ? mcpApprovalPrincipal(effectiveIdentity, approvalOrgId, requestMeta)
+    : undefined;
+  const approvalCallerKey = approvalPrincipal
+    ? await sha256Base64Url(approvalPrincipal)
+    : undefined;
+  let approvalCodec: RequestStateCodec<McpActionApprovalState> | undefined;
+  let approvalConfigurationError = false;
+  if (hasApprovalActions && approvalPrincipal) {
+    try {
+      const { getAuthSecret } =
+        await import("../server/better-auth-instance.js");
+      approvalCodec = createRequestStateCodec<McpActionApprovalState>({
+        key: getAuthSecret(),
+        ttlSeconds: MCP_ACTION_APPROVAL_TTL_SECONDS,
+        bind: (ctx) => `${ctx.mcpReq.method}\0${approvalPrincipal}`,
+      });
+    } catch {
+      // Production secret resolution deliberately throws when neither the
+      // explicit Better Auth secret nor the workspace-derived A2A secret is
+      // stable. Keep the MCP server available for reads, but refuse every
+      // approval-gated action rather than minting replayable/ephemeral hosted
+      // authorization state.
+      approvalConfigurationError = true;
+    }
+  }
   const supportsMcpApps =
     compactMcpAppCatalog ||
     Object.values(advertisedActions).some((entry) =>
@@ -1546,15 +1669,28 @@ export async function createMCPServerForRequest(
           }
         : {}),
     },
+    // Every catalog and resource is identity-scoped and can change at runtime
+    // through app configuration/HMR. Explicitly mark modern cacheable results
+    // private and immediately stale; the 2026 codec adds the required
+    // ttlMs/cacheScope fields while 2025 responses remain byte-compatible.
+    cacheHints: {
+      "server/discover": { ttlMs: 0, cacheScope: "private" },
+      "tools/list": { ttlMs: 0, cacheScope: "private" },
+      "resources/list": { ttlMs: 0, cacheScope: "private" },
+      "resources/templates/list": { ttlMs: 0, cacheScope: "private" },
+      "resources/read": { ttlMs: 0, cacheScope: "private" },
+    },
+    ...(approvalCodec
+      ? {
+          inputRequired: {
+            maxRounds: 2,
+            roundTimeoutMs: 10 * 60_000,
+          },
+          requestState: { verify: approvalCodec.verify },
+        }
+      : {}),
   });
 
-  // 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)`.
@@ -1578,63 +1714,178 @@ export async function createMCPServerForRequest(
     ) as Promise<T>;
   }
 
+  async function requireMcpActionApproval(
+    entry: ActionEntry,
+    name: string,
+    args: Record<string, unknown>,
+    ctx: ServerContext,
+  ): Promise<CallToolResult | InputRequiredResult | undefined> {
+    const verifiedState =
+      ctx.mcpReq.requestState<McpActionApprovalState>() ?? undefined;
+    const argumentsHash = await sha256Base64Url(canonicalJson(args));
+
+    if (verifiedState !== undefined) {
+      if (
+        verifiedState.version !== 1 ||
+        typeof verifiedState.nonce !== "string" ||
+        verifiedState.actionName !== name ||
+        verifiedState.argumentsHash !== argumentsHash ||
+        !Number.isFinite(verifiedState.expiresAt) ||
+        verifiedState.expiresAt < Date.now() ||
+        !approvalCallerKey
+      ) {
+        return actionApprovalError(
+          `Approval for ${name} is invalid or does not match this exact call.`,
+        );
+      }
+
+      const consumed = await consumeMcpApprovalGrant({
+        nonce: verifiedState.nonce,
+        callerKey: approvalCallerKey,
+        actionName: name,
+        argumentsHash,
+        expiresAt: verifiedState.expiresAt,
+      });
+      if (!consumed) {
+        return actionApprovalError(
+          `Approval for ${name} is invalid, expired, or already used.`,
+        );
+      }
+
+      const approval = acceptedContent(
+        ctx.mcpReq.inputResponses,
+        MCP_ACTION_APPROVAL_INPUT_KEY,
+      ) as Record<string, unknown> | undefined;
+      if (approval?.decision !== "approve") {
+        return actionApprovalError(`${name} was not approved.`);
+      }
+      return undefined;
+    }
+
+    if (entry.needsApproval === undefined) return undefined;
+    let mustApprove = false;
+    try {
+      mustApprove =
+        typeof entry.needsApproval === "function"
+          ? Boolean(
+              await entry.needsApproval(args, {
+                userEmail: getRequestUserEmail(),
+                orgId: getRequestOrgId() ?? null,
+                caller: "mcp",
+                actionName: name,
+              }),
+            )
+          : entry.needsApproval === true;
+    } catch {
+      mustApprove = true;
+    }
+    if (!mustApprove) return undefined;
+
+    if (approvalConfigurationError || !approvalCodec || !approvalCallerKey) {
+      return actionApprovalError(
+        `${name} requires approval, but secure MCP approval is not configured on this server.`,
+      );
+    }
+
+    const now = Date.now();
+    const approvalState: McpActionApprovalState = {
+      version: 1,
+      nonce: globalThis.crypto.randomUUID(),
+      actionName: name,
+      argumentsHash,
+      expiresAt: now + MCP_ACTION_APPROVAL_TTL_SECONDS * 1000,
+    };
+    await createMcpApprovalGrant({
+      ...approvalState,
+      callerKey: approvalCallerKey,
+    });
+    const requestState = await approvalCodec.mint(approvalState, ctx);
+    return inputRequired({
+      inputRequests: {
+        [MCP_ACTION_APPROVAL_INPUT_KEY]: inputRequired.elicit({
+          message:
+            `Action "${name}" requires your approval before it can run. ` +
+            "Review the exact tool arguments in your MCP client, then explicitly choose Approve or Deny.",
+          requestedSchema: {
+            type: "object",
+            properties: {
+              decision: {
+                type: "string",
+                title: `Run ${name}?`,
+                description:
+                  "Approve runs this exact call once. Deny leaves it unexecuted.",
+                enum: ["approve", "deny"],
+              },
+            },
+            required: ["decision"],
+          },
+        }),
+      },
+      requestState,
+    });
+  }
+
   // 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 () => {
+  server.setRequestHandler("tools/list", 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,
-          };
-        }),
+      const tools: Tool[] = await Promise.all(
+        Object.entries(advertisedActions)
+          .sort(([a], [b]) => compareMcpCatalogValues(a, b))
+          .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 ||
+                entry.needsApproval !== undefined,
+              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,
+            } as Tool;
+          }),
       );
 
       if (
@@ -1679,6 +1930,7 @@ export async function createMCPServerForRequest(
         });
       }
 
+      tools.sort((a, b) => compareMcpCatalogValues(a.name, b.name));
       return { tools };
     });
   });
@@ -1686,52 +1938,208 @@ export async function createMCPServerForRequest(
   // 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;
+  server.setRequestHandler(
+    "tools/call",
+    async (request: any, ctx: ServerContext) => {
+      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,
+            };
+          }
+        }
 
-      if (name === "ask-agent" && config.askAgent) {
-        if (compactMcpAppCatalog || connectorCatalogActive) {
+        // 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 (!hasMcpOAuthScope(effectiveIdentity?.oauthScopes, "mcp:write")) {
+        if (
+          !isActionVisibleForOAuthScope(entry, effectiveIdentity?.oauthScopes)
+        ) {
           return {
             content: [
               {
                 type: "text",
-                text: "Forbidden: OAuth scope does not allow ask-agent",
+                text: `Forbidden: OAuth scope does not allow tool ${name}`,
               },
             ],
             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,
+          const approvalResult = await requireMcpActionApproval(
+            entry,
+            name,
+            (args as Record<string, unknown>) ?? {},
+            ctx,
+          );
+          if (approvalResult !== undefined) return approvalResult;
+
+          // 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,
-          ).ask_app;
-          const result = await hostedAskApp.run({
-            message,
-            async: isExplicitAsyncAskAgent(args?.async),
-            maxWaitMs: isExplicitAsyncAskAgent(args?.async)
-              ? 0
-              : boundedAskAgentWaitMs(args?.maxWaitMs),
-          });
+          );
+          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: [{ type: "text", text: formatAskAgentResult(result) }],
+            content,
+            ...(mcpResultIsError || embedProducedNothing
+              ? { isError: true }
+              : {}),
+            ...(structuredContent ? { structuredContent } : {}),
+            ...(Object.keys(responseMeta).length > 0
+              ? { _meta: responseMeta }
+              : {}),
           };
         } catch (err: any) {
           return {
@@ -1739,146 +2147,12 @@ export async function createMCPServerForRequest(
             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 () => {
+    server.setRequestHandler("resources/list", async () => {
       return withCallerContext(async () => {
         const mcpAppResources = await getMcpAppResources(
           config,
@@ -1886,21 +2160,23 @@ export async function createMCPServerForRequest(
           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 } : {}),
-          })),
+          resources: mcpAppResources
+            .sort((a, b) => compareMcpCatalogValues(a.uri, b.uri))
+            .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 () => {
+    server.setRequestHandler("resources/templates/list", async () => {
       return withCallerContext(async () => {
         const mcpAppResources = await getMcpAppResources(
           config,
@@ -1908,71 +2184,71 @@ export async function createMCPServerForRequest(
           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 } : {}),
-          })),
+          resourceTemplates: mcpAppResources
+            .sort((a, b) => compareMcpCatalogValues(a.uri, b.uri))
+            .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.
+    server.setRequestHandler("resources/read", 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;
           }
-          if (!found) {
-            throw new Error(`MCP App resource not found: ${uri}`);
+          const resource = await resolveMcpAppResourceSafely(
+            config,
+            name,
+            entry,
+            requestMeta,
+          );
+          if (resource) {
+            found = { actionName: name, resource };
+            break;
           }
-          return {
-            contents: [
-              {
-                uri,
-                mimeType: found.resource.mimeType,
-                text: renderMcpAppHtml(
-                  found.resource,
-                  found.actionName,
-                  config,
-                  requestMeta,
-                ),
-                ...(found.resource._meta
-                  ? { _meta: found.resource._meta }
-                  : {}),
-              },
-            ],
-          };
-        });
-      },
-    );
+          // 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 ResourceNotFoundError(
+            String(uri ?? ""),
+            `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;