@agent-native/core 0.145.2 → 0.145.4

package/dist/mcp/build-server.js

@@ -142,6 +142,41 @@ function isActionVisibleForOAuthScope(entry, scopes) {
     const required = entry.readOnly === true ? "mcp:read" : "mcp:write";
     return hasMcpOAuthScope(scopes, required);
 }
+/** Mirrors `TOOL_SEARCH_ACTION_NAME`; not imported, because `agent/tool-search.ts`
+ *  reaches Node-only request context and this module must stay bundleable. */
+const TOOL_SEARCH_TOOL_NAME = "tool-search";
+function withoutToolSearch(actions) {
+    if (!(TOOL_SEARCH_TOOL_NAME in actions))
+        return actions;
+    return Object.fromEntries(Object.entries(actions).filter(([name]) => name !== TOOL_SEARCH_TOOL_NAME));
+}
+/**
+ * Re-point `tool-search` at the surface this caller can actually reach.
+ *
+ * The registry's own entry closes over the app's *whole* action registry, but
+ * `tools/call` accepts only the advertised set — so unscoped it answers with
+ * names that come straight back as "Unknown tool", and its `callable` field
+ * reports plan-mode availability, not that gate. Every template that noticed
+ * worked around it by hand-rolling a narrowed copy; scoping it here is what
+ * makes the trimmed catalog honest without one.
+ */
+function scopeToolSearchToAdvertised(advertised) {
+    const entry = advertised[TOOL_SEARCH_TOOL_NAME];
+    if (!entry)
+        return advertised;
+    return {
+        ...advertised,
+        [TOOL_SEARCH_TOOL_NAME]: {
+            ...entry,
+            // Imported lazily: `agent/tool-search.ts` pulls Node-only request
+            // context, and this module has to stay bundleable for serverless.
+            run: async (args) => {
+                const { searchToolRegistry } = await import("../agent/tool-search.js");
+                return searchToolRegistry(advertised, args ?? {});
+            },
+        },
+    };
+}
 const COMPACT_MCP_APP_CATALOG_BUILTINS = new Set([
     "list_apps",
     "open_app",
@@ -149,9 +184,10 @@ const COMPACT_MCP_APP_CATALOG_BUILTINS = new Set([
     "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",
+    // compacted client discovers any action on demand, which is what makes
+    // "small catalog by default" non-opaque. Discovery is not permission — a
+    // searched name still has to be in the advertised set to be callable.
+    TOOL_SEARCH_TOOL_NAME,
 ]);
 function isActionAdvertisedInCompactMcpAppCatalog(name, entry, config) {
     if (COMPACT_MCP_APP_CATALOG_BUILTINS.has(name))
@@ -1115,16 +1151,36 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
     const baseActions = useFullSurface && config.productionActions
         ? config.productionActions
         : config.actions;
-    const actions = mergeBuiltinTools(config, baseActions, requestMeta);
+    const appCatalog = config.catalogMode === "app";
+    // The app catalog IS a full flat catalog, so the `--full-catalog` opt-ins
+    // have nothing left to escalate — collapsing them here keeps every tier gate
+    // below reading one flag instead of testing `appCatalog` a fifth time.
+    const fullCatalogRequested = !appCatalog && explicitlyRequestsFullMcpCatalog(requestMeta);
+    // `tool-search` earns its place only on a *trimmed* catalog, where it is how
+    // a client reaches an action that was not listed. On a flat catalog — app
+    // mode or the `--full-catalog` opt-in — every tool is already in `tools/list`
+    // beside it, so it can only ever describe its own neighbours while spending
+    // a tool slot and a round trip to do it.
+    const flatCatalog = appCatalog || fullCatalogRequested;
+    // `catalogMode: "app"` asks for parity with the in-app agent, so the cross-app
+    // builtins the MCP layer adds on its own come back off too.
+    const mergedActions = appCatalog
+        ? baseActions
+        : mergeBuiltinTools(config, baseActions, requestMeta);
+    // Strip from `actions`, not just the advertised set: on the full-catalog tier
+    // `actions` IS the callable surface, so filtering only the listing would
+    // leave `tool-search` callable but invisible.
+    const actions = flatCatalog
+        ? withoutToolSearch(mergedActions)
+        : mergedActions;
     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 compactMcpAppCatalog = !appCatalog && !fullCatalogRequested;
     const advertisedActionsBeforeConnector = compactMcpAppCatalog
         ? Object.fromEntries(Object.entries(visibleActions).filter(([name, entry]) => isActionAdvertisedInCompactMcpAppCatalog(name, entry, config)))
         : visibleActions;
@@ -1140,28 +1196,32 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
     // 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) &&
+    const connectorCatalogActive = !appCatalog &&
+        (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))
+    const advertisedActionsBeforeToolSearchScope = appCatalog
+        ? Object.fromEntries(Object.entries(visibleActions).filter(([name]) => !denyNames.has(name)))
+        : 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;
-            if (!connectorNames.has(name))
-                return false;
-            if (externalAgentWritesAreAskAppOnly(config) &&
-                entry.readOnly !== true) {
-                return false;
-            }
-            return true;
-        }))
-        : advertisedActionsBeforeConnector;
+            }))
+            : advertisedActionsBeforeConnector;
+    const advertisedActions = scopeToolSearchToAdvertised(advertisedActionsBeforeToolSearchScope);
     if (fullCatalogRequested) {
         warnFullCatalogServed(Object.keys(advertisedActions).length);
     }
@@ -1389,8 +1449,10 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                     annotations,
                 };
             }));
-            if (!compactMcpAppCatalog &&
-                !connectorCatalogActive &&
+            // `ask-agent` is the legacy full-catalog meta-tool; `ask_app` is the
+            // builtin every other tier carries. Gate on the one flag that means
+            // "this caller opted all the way in".
+            if (fullCatalogRequested &&
                 config.askAgent &&
                 hasMcpOAuthScope(effectiveIdentity?.oauthScopes, "mcp:write")) {
                 tools.push({
@@ -1436,7 +1498,7 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
         return withCallerContext(async () => {
             const { name, arguments: args } = request.params;
             if (name === "ask-agent" && config.askAgent) {
-                if (compactMcpAppCatalog || connectorCatalogActive) {
+                if (!fullCatalogRequested) {
                     return {
                         content: [{ type: "text", text: `Unknown tool: ${name}` }],
                         isError: true,
@@ -1483,12 +1545,14 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                     };
                 }
             }
-            // 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;
+            // Every tier except the explicit full-catalog opt-in treats the
+            // advertised set as the authoritative callable surface: a name that
+            // was not listed is rejected, not merely hidden. Deriving this from
+            // the one opt-in flag rather than re-testing each tier is what keeps a
+            // newly added tier from silently defaulting to "everything callable".
+            const callableActions = fullCatalogRequested
+                ? actions
+                : advertisedActions;
             const entry = callableActions[name];
             if (!entry) {
                 return {

package/dist/mcp/oauth-client-metadata.js

@@ -170,12 +170,16 @@ function validateClientMetadataDocument(clientId, value) {
     if (tokenEndpointAuthMethod !== "none") {
         throw new Error("Only public Client ID Metadata clients are supported");
     }
+    // A grant type we do not support is not a reason to reject the document —
+    // clients advertise grants they use elsewhere (Claude.ai's CIMD document
+    // lists "urn:ietf:params:oauth:grant-type:jwt-bearer" next to the two we
+    // support). The token endpoint independently honors only
+    // "authorization_code"/"refresh_token" no matter what this list says.
     const grantTypes = parseStringArray(document.grant_types);
     if ((document.grant_types !== undefined &&
         (!Array.isArray(document.grant_types) ||
             grantTypes.length !== document.grant_types.length)) ||
-        grantTypes.length > 10 ||
-        !grantTypes.every((grant) => grant === "authorization_code" || grant === "refresh_token")) {
+        grantTypes.length > 10) {
         throw new Error("Client metadata document grant_types are unsupported");
     }
     const responseTypes = parseStringArray(document.response_types);

package/dist/observability/routes.d.ts

@@ -41,16 +41,16 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
+    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-    error?: undefined;
     ok?: undefined;
 } | {
     summary?: undefined;
@@ -59,9 +59,9 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     error: any;
     ok?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
-    error?: undefined;
     ok: boolean;
 }>>;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,8 +311,8 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        deleted?: undefined;
         id?: undefined;
+        deleted?: undefined;
         provider?: undefined;
         found?: undefined;
         providers: {
@@ -329,9 +329,9 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         label?: undefined;
         message?: undefined;
     } | {
+        id?: undefined;
         deleted?: undefined;
         count?: undefined;
-        id?: undefined;
         providers?: undefined;
         found: boolean;
         provider: import("../custom-registry.js").CustomProviderConfig;

package/dist/server/action-discovery.d.ts

@@ -26,7 +26,7 @@
  * ```
  */
 import type { ActionEntry } from "../agent/production-agent.js";
-import type { FrameworkToolGroup } from "../framework-tools.js";
+import { CORE_ACTION_GROUPS } from "../framework-tools.js";
 /**
  * Register a map of actions contributed by a published package.
  *
@@ -81,22 +81,7 @@ export declare function loadActionsFromStaticRegistry(modules: Record<string, un
  *   passing to `createAgentChatPlugin({ actions })`.
  */
 export declare function autoDiscoverActions(from: string): Promise<Record<string, ActionEntry>>;
-/**
- * Which `frameworkTools` switch owns each framework action kit.
- *
- * The group is stamped onto the entry as `frameworkGroup`, which is what lets
- * one filter subtract a whole kit from every agent tool surface at once — the
- * plugin spreads these registries at thirteen composition sites, and a
- * per-site condition would be the same omission waiting to happen thirteen
- * times. The tag also keeps these ~45 schemas out of the DEFAULT first-request
- * tool list; they stay reachable through `tool-search`.
- *
- * Anything absent from this map is always-on and must be listed in
- * `ALWAYS_ON_CORE_ACTIONS` instead. `action-discovery.spec.ts` fails when a new
- * core action appears in neither, so "always-on" stays a decision someone made
- * rather than the default that happens when a map goes un-updated.
- */
-export declare const CORE_ACTION_GROUPS: Record<string, FrameworkToolGroup>;
+export { CORE_ACTION_GROUPS };
 /**
  * Core actions with no `frameworkTools` switch, and why:
  *
@@ -104,7 +89,7 @@ export declare const CORE_ACTION_GROUPS: Record<string, FrameworkToolGroup>;
  * - The email catalog is mounted everywhere on purpose so Dispatch can ask any
  *   app what it sends without that app opting in (see its comment below). It is
  *   a read surface, not the `email` group's send capability.
- * - MCP tools and org service tokens are already governed by `disableMcp`.
+ * - MCP tools and org service tokens are already governed by `mcp.enabled`.
  */
 export declare const ALWAYS_ON_CORE_ACTIONS: ReadonlySet<string>;
 export declare function mergeCoreSharingActions(registry: Record<string, ActionEntry>): Promise<void>;

package/dist/server/action-discovery.js

@@ -1,4 +1,5 @@
 import nodePath from "node:path";
+import { CORE_ACTION_GROUPS } from "../framework-tools.js";
 import { captureCliOutput } from "./cli-capture.js";
 // Lazy fs — loaded via dynamic import() on first use.
 // Avoids require() which bundlers convert to createRequire() that crashes on CF Workers.
@@ -497,70 +498,10 @@ export async function autoDiscoverActions(from) {
     }
     return registry;
 }
-/**
- * Which `frameworkTools` switch owns each framework action kit.
- *
- * The group is stamped onto the entry as `frameworkGroup`, which is what lets
- * one filter subtract a whole kit from every agent tool surface at once — the
- * plugin spreads these registries at thirteen composition sites, and a
- * per-site condition would be the same omission waiting to happen thirteen
- * times. The tag also keeps these ~45 schemas out of the DEFAULT first-request
- * tool list; they stay reachable through `tool-search`.
- *
- * Anything absent from this map is always-on and must be listed in
- * `ALWAYS_ON_CORE_ACTIONS` instead. `action-discovery.spec.ts` fails when a new
- * core action appears in neither, so "always-on" stays a decision someone made
- * rather than the default that happens when a map goes un-updated.
- */
-export const CORE_ACTION_GROUPS = {
-    "share-resource": "sharing",
-    "unshare-resource": "sharing",
-    "list-resource-shares": "sharing",
-    "set-resource-visibility": "sharing",
-    "create-agent-resource-link": "sharing",
-    "get-feature-flags": "featureFlags",
-    "list-feature-flags": "featureFlags",
-    "set-feature-flag": "featureFlags",
-    "list-recurring-jobs": "automation",
-    "manage-recurring-job": "automation",
-    "run-automation-now": "automation",
-    "list-automation-runs": "automation",
-    "list-automations": "automation",
-    "manage-automation": "automation",
-    "context-manifest-get": "contextXray",
-    "context-preview-get": "contextXray",
-    "context-pin": "contextXray",
-    "context-evict": "contextXray",
-    "context-restore": "contextXray",
-    "context-report": "contextXray",
-    "get-localization-preference": "localization",
-    "set-localization-preference": "localization",
-    // Profile, credentials, and appearance share one switch: an app that hides
-    // its profile surface from the agent hides password management with it.
-    "get-user-profile": "userProfile",
-    "update-user-profile": "userProfile",
-    "get-auth-methods": "userProfile",
-    "set-password": "userProfile",
-    "change-password": "userProfile",
-    "change-appearance": "userProfile",
-    "list-audit-events": "audit",
-    "get-audit-event": "audit",
-    "export-audit-events": "audit",
-    "create-resource-version": "history",
-    "list-resource-versions": "history",
-    "get-resource-version": "history",
-    "restore-resource-version": "history",
-    "list-resource-history": "history",
-    "list-review-comments": "review",
-    "create-review-comment": "review",
-    "reply-review-comment": "review",
-    "resolve-review-thread": "review",
-    "delete-review-comment": "review",
-    "consume-review-feedback": "review",
-    "get-review-feedback": "review",
-    "set-review-status": "review",
-    "send-review-thread-to-agent": "review",
-};
+// `CORE_ACTION_GROUPS` lives in `framework-tools.ts` so the group filter can
+// resolve a kit by name without importing this module. Re-exported here
+// because this is where callers have always found it.
+export { CORE_ACTION_GROUPS };
 /**
  * Core actions with no `frameworkTools` switch, and why:
  *
@@ -568,7 +509,7 @@ export const CORE_ACTION_GROUPS = {
  * - The email catalog is mounted everywhere on purpose so Dispatch can ask any
  *   app what it sends without that app opting in (see its comment below). It is
  *   a read surface, not the `email` group's send capability.
- * - MCP tools and org service tokens are already governed by `disableMcp`.
+ * - MCP tools and org service tokens are already governed by `mcp.enabled`.
  */
 export const ALWAYS_ON_CORE_ACTIONS = new Set([
     "upload-image",
@@ -818,6 +759,9 @@ export async function mergeCoreSharingActions(registry) {
                     // actions' `toolCallable: false` (audit-H5) is dropped and the
                     // tools-iframe bridge 403 in action-routes.ts never fires.
                     ...preserveActionFlags(def),
+                    // Pre-resolved copy of what `resolveFrameworkGroup` would compute
+                    // from the name anyway. Kept so an entry read in isolation still
+                    // reports its kit; the filters no longer depend on it.
                     ...(CORE_ACTION_GROUPS[name]
                         ? { frameworkGroup: CORE_ACTION_GROUPS[name] }
                         : {}),

package/dist/server/agent-chat/action-filters-a2a.d.ts

@@ -3,6 +3,7 @@ import type { EngineTool } from "../../agent/engine/types.js";
 import { type ActionEntry, type AgentLoopOutcome } from "../../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../../agent/run-loop-with-resume.js";
 import type { AgentChatEvent } from "../../agent/types.js";
+import type { ExternalAgentPolicy } from "../../mcp/external-agent-policy.js";
 import type { AgentChatPluginOptions } from "./plugin-options.js";
 export declare function filterReadOnlyActions(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
 /** Drop actions that opted out of agent exposure via `agentTool: false`. They
@@ -25,13 +26,24 @@ export declare function filterPublicAgentActions(actions: Record<string, ActionE
  * action out of this rule.
  */
 export declare function hasRawQueryInput(entry: ActionEntry): boolean;
+/**
+ * The two policy fields A2A shares with the MCP mount. Structural rather than
+ * `Pick<AgentChatPluginOptions, …>` so callers pass the *resolved* MCP options:
+ * reading the raw plugin options here would leave A2A on the deprecated
+ * top-level keys, so `mcp: { connectorCatalog }` would narrow the MCP surface
+ * while A2A kept serving the old one.
+ */
+export interface A2AExternalAgentSurface {
+    connectorCatalog?: string[];
+    externalAgents?: ExternalAgentPolicy;
+}
 /**
  * Direct A2A action calls share the authenticated external-agent policy with
  * MCP, but remain stricter: only explicitly exposed, authenticated read-only
  * actions can skip the receiver's model loop, and never one that takes a raw
  * query the caller wrote.
  */
-export declare function filterDirectA2AActions(actions: Record<string, ActionEntry>, options: Pick<AgentChatPluginOptions, "connectorCatalog" | "externalAgents">): Record<string, ActionEntry>;
+export declare function filterDirectA2AActions(actions: Record<string, ActionEntry>, options: A2AExternalAgentSurface): Record<string, ActionEntry>;
 export declare function buildPublicAgentA2ASkills(actions: Record<string, ActionEntry>): Array<{
     id: string;
     name: string;
@@ -47,7 +59,7 @@ export declare function buildPublicAgentA2ASkills(actions: Record<string, Action
  * `requiresAuth === true` — advertising the public set alone tells siblings
  * an app has nothing callable when it does.
  */
-export declare function buildAuthenticatedAgentA2ASkills(actions: Record<string, ActionEntry>, options: Pick<AgentChatPluginOptions, "connectorCatalog" | "externalAgents">): Array<{
+export declare function buildAuthenticatedAgentA2ASkills(actions: Record<string, ActionEntry>, options: A2AExternalAgentSurface): Array<{
     id: string;
     name: string;
     description: string;

package/dist/server/agent-chat/action-filters-a2a.js

@@ -405,6 +405,6 @@ export function resolveInitialToolNames(templateActions, configured) {
     if (configured)
         return configured;
     return Object.entries(templateActions)
-        .filter(([, entry]) => !isFrameworkGroupedAction(entry))
+        .filter(([name, entry]) => !isFrameworkGroupedAction(name, entry))
         .map(([name]) => name);
 }

package/dist/server/agent-chat/mcp-options.d.ts

@@ -0,0 +1,106 @@
+import type { ExternalAgentPolicy } from "../../mcp/external-agent-policy.js";
+/** App icon descriptor surfaced during the MCP `initialize` handshake. */
+export interface AgentChatMcpIcon {
+    src: string;
+    mimeType?: string;
+    sizes?: string[];
+    theme?: "light" | "dark";
+}
+/**
+ * Everything the agent-chat plugin can configure about its MCP mount, in one
+ * object.
+ *
+ * Before this existed, the MCP settings were five unrelated top-level keys
+ * (`disableMcp`, `mcpServerInfo`, `connectorCatalog`, `externalAgents`) and
+ * several `MCPConfig` fields with no route through the plugin at all —
+ * `builtinCrossAppTools` was reachable only by calling `mountMCP` directly,
+ * which is why `frameworkTools` could never remove the cross-app builtins from
+ * an app that used the normal plugin entry point.
+ */
+export interface AgentChatMcpOptions {
+    /**
+     * Mount the remote MCP protocol route. Defaults to `true`.
+     *
+     * Set `false` for hosted apps with a dedicated early MCP plugin, so their
+     * external connector does not depend on the heavier chat plugin
+     * initialization path.
+     */
+    enabled?: boolean;
+    /**
+     * `"app"` serves external callers exactly this app's own tool registry,
+     * flat — the same actions the in-app agent holds, with no cross-app
+     * builtins, no `ask-agent`, no `tool-search`, and no compact/connector
+     * trimming. `connectorCatalog` and the `--full-catalog` opt-ins are inert
+     * once this is set; `externalAgents.denyActions` and OAuth scopes still
+     * apply.
+     *
+     * Weigh the token cost before setting it: an app registering ~100 actions
+     * puts every one of their schemas in the caller's context on `tools/list`,
+     * which is the exact footgun the compact default exists to avoid.
+     */
+    catalog?: "app";
+    /**
+     * Curated allow-list of action names served to external connector clients.
+     * Trims both the advertised and the callable surface — a name outside the
+     * list is rejected, not merely hidden.
+     */
+    connectorCatalog?: string[];
+    /**
+     * Default authenticated external-agent policy. In `auto` read mode, every
+     * action explicitly marked as GET + readOnly + publicAgent.requiresAuth is
+     * added to the connector surface automatically. Writes remain ask_app-only
+     * unless `writes: "allowlisted"` is explicitly selected.
+     */
+    externalAgents?: ExternalAgentPolicy;
+    /**
+     * Merge the generic cross-app builtins (`list_apps`, `open_app`, `ask_app`,
+     * `ask_app_status`, `create_embed_session`, `create_workspace_app`,
+     * `list_templates`). Defaults to `true`.
+     *
+     * These are added by the MCP layer itself, downstream of `frameworkTools`,
+     * so they are NOT removed by `frameworkTools: "minimal"` or
+     * `workspaceApps: false` — this is the switch that turns them off.
+     */
+    builtinCrossAppTools?: boolean;
+    /** Human-facing title. Defaults to the capitalized app id/name. */
+    title?: string;
+    /** Host-facing description. Defaults to "Agent-native <app> agent". */
+    description?: string;
+    /** Canonical app URL. Relative URLs are resolved against the request origin. */
+    websiteUrl?: string;
+    /** App icons. Relative `src` values are resolved against the request origin. */
+    icons?: AgentChatMcpIcon[];
+}
+/** The legacy top-level keys `mcp` replaces. */
+export interface AgentChatMcpLegacyInput {
+    /** @deprecated Use `mcp.enabled: false`. */
+    disableMcp?: boolean;
+    /** @deprecated Use `mcp.title` / `mcp.description` / `mcp.websiteUrl` / `mcp.icons`. */
+    mcpServerInfo?: {
+        title?: string;
+        description?: string;
+        websiteUrl?: string;
+        icons?: AgentChatMcpIcon[];
+    };
+    /** @deprecated Use `mcp.connectorCatalog`. */
+    connectorCatalog?: string[];
+    /** @deprecated Use `mcp.externalAgents`. */
+    externalAgents?: ExternalAgentPolicy;
+    mcp?: AgentChatMcpOptions;
+}
+export interface ResolvedAgentChatMcp {
+    enabled: boolean;
+    catalog: "app" | undefined;
+    connectorCatalog: string[] | undefined;
+    externalAgents: ExternalAgentPolicy | undefined;
+    builtinCrossAppTools: boolean | undefined;
+    title: string | undefined;
+    description: string | undefined;
+    websiteUrl: string | undefined;
+    icons: AgentChatMcpIcon[] | undefined;
+}
+/**
+ * Collapse the nested `mcp` option and the legacy top-level keys into the one
+ * shape the plugin threads into `mountMCP`.
+ */
+export declare function resolveAgentChatMcpOptions(input: AgentChatMcpLegacyInput | undefined): ResolvedAgentChatMcp;

package/dist/server/agent-chat/mcp-options.js

@@ -0,0 +1,50 @@
+function conflict(key, legacyKey, legacyValue, nestedValue) {
+    throw new Error(`[agent-native] Conflicting agent-chat options: \`${legacyKey}: ${JSON.stringify(legacyValue)}\` ` +
+        `and \`mcp.${key}: ${JSON.stringify(nestedValue)}\` disagree. ` +
+        `Remove the deprecated \`${legacyKey}\` and keep \`mcp.${key}\`.`);
+}
+const warnedLegacyKeys = new Set();
+/**
+ * Nested value wins, but only when the two forms agree.
+ *
+ * Disagreement throws at plugin init rather than picking a side: an app that
+ * boots with an MCP surface nobody chose is how a "why can't the connector see
+ * this tool" report ends up unexplainable. Same contract as
+ * `resolveFrameworkTools`.
+ */
+function pick(key, legacyKey, legacyValue, nestedValue) {
+    if (legacyValue === undefined)
+        return nestedValue;
+    if (nestedValue !== undefined &&
+        JSON.stringify(legacyValue) !== JSON.stringify(nestedValue)) {
+        conflict(key, legacyKey, legacyValue, nestedValue);
+    }
+    if (!warnedLegacyKeys.has(legacyKey)) {
+        warnedLegacyKeys.add(legacyKey);
+        console.warn(`[agent-native] \`${legacyKey}\` is deprecated — use \`mcp: { ${key}: … }\`.`);
+    }
+    return nestedValue ?? legacyValue;
+}
+/**
+ * Collapse the nested `mcp` option and the legacy top-level keys into the one
+ * shape the plugin threads into `mountMCP`.
+ */
+export function resolveAgentChatMcpOptions(input) {
+    const mcp = input?.mcp ?? {};
+    const legacyInfo = input?.mcpServerInfo;
+    // `disableMcp` is the inverse of `enabled`, so normalize before comparing —
+    // otherwise `disableMcp: true` + `enabled: false` would read as a conflict.
+    const legacyEnabled = input?.disableMcp === undefined ? undefined : !input.disableMcp;
+    const enabled = pick("enabled", "disableMcp", legacyEnabled, mcp.enabled);
+    return {
+        enabled: enabled ?? true,
+        catalog: mcp.catalog,
+        connectorCatalog: pick("connectorCatalog", "connectorCatalog", input?.connectorCatalog, mcp.connectorCatalog),
+        externalAgents: pick("externalAgents", "externalAgents", input?.externalAgents, mcp.externalAgents),
+        builtinCrossAppTools: mcp.builtinCrossAppTools,
+        title: pick("title", "mcpServerInfo.title", legacyInfo?.title, mcp.title),
+        description: pick("description", "mcpServerInfo.description", legacyInfo?.description, mcp.description),
+        websiteUrl: pick("websiteUrl", "mcpServerInfo.websiteUrl", legacyInfo?.websiteUrl, mcp.websiteUrl),
+        icons: pick("icons", "mcpServerInfo.icons", legacyInfo?.icons, mcp.icons),
+    };
+}