@agent-native/core 0.145.3 → 0.145.4

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/notifications/routes.d.ts

@@ -13,13 +13,13 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
 } | {
     count?: undefined;
     updated: number;
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
 } | {
     count?: undefined;
     updated?: undefined;

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/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     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/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

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),
+    };
+}

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

@@ -5,6 +5,7 @@ import type { FrameworkToolsConfig } from "../../framework-tools.js";
 import type { ExternalAgentPolicy } from "../../mcp/external-agent-policy.js";
 import type { DatabaseToolsOption } from "../../scripts/db/tool-mode.js";
 import type { PromptExamples } from "../prompts/index.js";
+import type { AgentChatMcpIcon, AgentChatMcpOptions } from "./mcp-options.js";
 /** Shape of a Nitro plugin function: receives the Nitro app instance at
  * startup and may register routes/hooks synchronously or asynchronously. */
 export type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
@@ -51,21 +52,23 @@ export interface AgentChatPluginOptions {
     mentionProviders?: Record<string, MentionProvider> | (() => Record<string, MentionProvider> | Promise<Record<string, MentionProvider>>);
     /** App ID used to exclude self from agent discovery (e.g., "mail", "calendar") */
     appId?: string;
-    /** Optional MCP server branding surfaced during the initialize handshake. */
+    /**
+     * Everything about this app's MCP mount — whether it is mounted, which tools
+     * external callers see, and the branding sent during the `initialize`
+     * handshake. See `AgentChatMcpOptions`.
+     *
+     * Replaces the top-level `disableMcp`, `mcpServerInfo`, `connectorCatalog`,
+     * and `externalAgents`, which stay accepted for one minor. Setting both
+     * forms to disagreeing values throws at plugin init rather than silently
+     * picking one.
+     */
+    mcp?: AgentChatMcpOptions;
+    /** @deprecated Use `mcp.title` / `mcp.description` / `mcp.websiteUrl` / `mcp.icons`. */
     mcpServerInfo?: {
-        /** 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?: Array<{
-            src: string;
-            mimeType?: string;
-            sizes?: string[];
-            theme?: "light" | "dark";
-        }>;
+        icons?: AgentChatMcpIcon[];
     };
     /**
      * Optional callback to resolve the org ID for the current request.
@@ -330,15 +333,10 @@ export interface AgentChatPluginOptions {
      * claim in their connect-minted JWT) or the deployment-wide
      * `AGENT_NATIVE_MCP_FULL_CATALOG=1` env override.
      *
-     * Declare here rather than in MCPConfig directly; the plugin copies it through.
+     * @deprecated Use `mcp.connectorCatalog`.
      */
     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.
-     */
+    /** @deprecated Use `mcp.externalAgents`. */
     externalAgents?: ExternalAgentPolicy;
     /**
      * Allow this app's A2A agent to delegate to a different app through the
@@ -359,14 +357,7 @@ export interface AgentChatPluginOptions {
         maxRunInputTokens?: number;
         maxToolResultChars?: number;
     };
-    /**
-     * Skip mounting the remote MCP protocol route.
-     *
-     * Most apps should leave this off so agent chat, A2A, and MCP share one
-     * runtime. Hosted apps with a dedicated early MCP plugin can set this to
-     * true so their external connector does not depend on the heavier chat
-     * plugin initialization path.
-     */
+    /** @deprecated Use `mcp: { enabled: false }`. */
     disableMcp?: boolean;
     /**
      * Code-execution capability for the production agent.

package/dist/server/agent-chat-plugin.js

@@ -110,6 +110,7 @@ import { createA2AEngineToolSurface, DEFAULT_DELEGATED_MAX_ITERATIONS, DEFAULT_D
 import { createBuilderBrowserTool, createTeamTools, } from "./agent-chat/browser-team-tools.js";
 import { createDataWidgetActionEntries, createFrameworkContextEntry, createRefreshScreenEntry, createUrlTools, } from "./agent-chat/context-tools.js";
 import { _agentChatPromptSectionsForTests, buildFrameworkPrompts, buildSchemaBlock, collectFiles, corpusToolNamesTaughtByPrompt, generateActionsPrompt, generateCorpusToolsPrompt, } from "./agent-chat/framework-prompts.js";
+import { resolveAgentChatMcpOptions } from "./agent-chat/mcp-options.js";
 import { resolveA2AAgentDelegationEnabled, } from "./agent-chat/plugin-options.js";
 import { finalizeClaimedAgentChatProcessRunFailure } from "./agent-chat/process-run-failure.js";
 import { loadResourcesForPrompt, promptResourceManifestSections, resourceScopeForOwner, } from "./agent-chat/prompt-resources.js";
@@ -286,6 +287,11 @@ export function createAgentChatPlugin(options) {
             // here rather than booting with a surface nobody chose.
             const frameworkTools = resolveFrameworkTools(options);
             const disabledFrameworkGroups = frameworkTools.disabledGroups;
+            // Same treatment for the MCP mount: one resolved shape, folding the
+            // deprecated `disableMcp` / `mcpServerInfo` / `connectorCatalog` /
+            // `externalAgents` into `mcp`. A2A reads the same object, so the
+            // connector policy cannot diverge between the two external surfaces.
+            const mcpOptions = resolveAgentChatMcpOptions(options);
             // Build the four assembled system prompt strings. These are static for the
             // lifetime of this plugin instance — examples come from options once at
             // startup, not per-request.
@@ -1055,12 +1061,12 @@ export function createAgentChatPlugin(options) {
                     : "Agent",
                 description: `Agent-native ${options?.appId ?? "app"} agent`,
                 skills: buildPublicAgentA2ASkills(allScripts),
-                authenticatedSkills: buildAuthenticatedAgentA2ASkills(mcpFullActions ?? allScripts, options ?? {}),
+                authenticatedSkills: buildAuthenticatedAgentA2ASkills(mcpFullActions ?? allScripts, mcpOptions),
                 publicSkillsOnly: true,
                 streaming: true,
                 durableBackgroundRuns: options?.durableBackgroundRuns,
                 executeReadOnlyAction: async ({ action, input, invocationId }) => {
-                    const actions = filterDirectA2AActions(mcpFullActions ?? allScripts, options ?? {});
+                    const actions = filterDirectA2AActions(mcpFullActions ?? allScripts, mcpOptions);
                     const entry = actions[action];
                     if (!entry) {
                         return {
@@ -1667,26 +1673,30 @@ export function createAgentChatPlugin(options) {
                         : DEV_FRAMEWORK_PROMPT) + devActionsPrompt;
             // Keep legacy names for the composition below
             const basePrompt = prodPrompt;
-            if (options?.disableMcp !== true) {
+            if (mcpOptions.enabled) {
                 // Mount MCP remote server — same action registry as A2A + agent chat
                 const { mountMCP } = await import("../mcp/server.js");
                 mountMCP(nitroApp, {
                     name: options?.appId
                         ? options.appId.charAt(0).toUpperCase() + options.appId.slice(1)
                         : "Agent",
-                    title: options?.mcpServerInfo?.title,
+                    title: mcpOptions.title,
                     appId: options?.appId,
-                    description: options?.mcpServerInfo?.description ??
+                    description: mcpOptions.description ??
                         `Agent-native ${options?.appId ?? "app"} agent`,
-                    websiteUrl: options?.mcpServerInfo?.websiteUrl,
-                    icons: options?.mcpServerInfo?.icons,
+                    websiteUrl: mcpOptions.websiteUrl,
+                    icons: mcpOptions.icons,
                     actions: allScripts,
                     productionActions: mcpFullActions,
-                    ...(options?.connectorCatalog
-                        ? { connectorCatalog: options.connectorCatalog }
+                    ...(mcpOptions.catalog ? { catalogMode: mcpOptions.catalog } : {}),
+                    ...(mcpOptions.builtinCrossAppTools !== undefined
+                        ? { builtinCrossAppTools: mcpOptions.builtinCrossAppTools }
                         : {}),
-                    ...(options?.externalAgents
-                        ? { externalAgents: options.externalAgents }
+                    ...(mcpOptions.connectorCatalog
+                        ? { connectorCatalog: mcpOptions.connectorCatalog }
+                        : {}),
+                    ...(mcpOptions.externalAgents
+                        ? { externalAgents: mcpOptions.externalAgents }
                         : {}),
                     askAgent: async (message) => {
                         const ownerEmail = getRequestUserEmail();

package/dist/server/index.d.ts

@@ -32,6 +32,7 @@ export { createObservationalMemoryPlugin, defaultObservationalMemoryPlugin, } fr
 export { createGoogleAuthPlugin, type GoogleAuthPluginOptions, } from "./google-auth-plugin.js";
 export type { GoogleAuthMode } from "./google-auth-mode.js";
 export { createAgentChatPlugin, defaultAgentChatPlugin, refreshGlobalMcpManager, type AgentChatPluginOptions, } from "./agent-chat-plugin.js";
+export type { AgentChatMcpIcon, AgentChatMcpOptions, } from "./agent-chat/mcp-options.js";
 export { configureAgentNativeEmbeddedEnvironment, createAgentNativeEmbeddedAuthOptions, createAgentNativeEmbeddedPlugin, mountAgentNativeEmbedded, normalizeAgentNativeEmbeddedSession, type AgentNativeEmbeddedAuthOptions, type AgentNativeEmbeddedGetSession, type AgentNativeEmbeddedHostSession, type AgentNativeEmbeddedPluginOptions, } from "./embedded.js";
 export { createThread, getThread, listThreads, updateThreadData, deleteThread, setThreadArchived, setThreadPinned, setThreadScope, type ChatThread, type ChatThreadScope, type ChatThreadSummary, type ListThreadsOptions, } from "../chat-threads/store.js";
 export { createResourcesPlugin, defaultResourcesPlugin, } from "./resources-plugin.js";
@@ -52,6 +53,8 @@ export { getH3App, awaitBootstrap, markDefaultPluginProvided, type H3AppShim, }
 export { fireInternalDispatch, resolveSelfDispatchBaseUrl, type FireInternalDispatchOptions, } from "./self-dispatch.js";
 export { extractBearerToken as extractInternalBearerToken, verifyInternalToken, } from "../integrations/internal-token.js";
 export { autoDiscoverActions, autoDiscoverScripts, loadActionsFromStaticRegistry, mergeCoreSharingActions, registerPackageActions, } from "./action-discovery.js";
+export { attachToolSearch, createToolSearchEntry, searchToolRegistry, TOOL_SEARCH_ACTION_NAME, } from "../agent/tool-search.js";
+export { filterFrameworkToolGroups, frameworkGroupEnabled, resolveFrameworkTools, FRAMEWORK_TOOL_GROUPS, type FrameworkToolGroup, type FrameworkToolsConfig, type FrameworkToolsOption, type ResolvedFrameworkTools, } from "../framework-tools.js";
 export { registerPromptContextProvider, type PromptContextProvider, type PromptContextProviderContext, type PromptContextProviderContribution, } from "./agent-chat/prompt-resources.js";
 export { mountActionRoutes, type MountActionRoutesOptions, type ActionRouteAuthAdapter, type ActionRouteResolvedCaller, } from "./action-routes.js";
 export { AGENT_RUN_OWNER_CONTEXT_KEY, seedAgentRunOwnerContext, type AgentRunOwnerContext, } from "./agent-run-context.js";

package/dist/server/index.js

@@ -53,6 +53,13 @@ export { getH3App, awaitBootstrap, markDefaultPluginProvided, } from "./framewor
 export { fireInternalDispatch, resolveSelfDispatchBaseUrl, } from "./self-dispatch.js";
 export { extractBearerToken as extractInternalBearerToken, verifyInternalToken, } from "../integrations/internal-token.js";
 export { autoDiscoverActions, autoDiscoverScripts, loadActionsFromStaticRegistry, mergeCoreSharingActions, registerPackageActions, } from "./action-discovery.js";
+// A standalone `mountMCP` plugin has to compose the same action surface the
+// agent-chat plugin does. Without these, the only way to build one was to
+// hand-roll a copy — which is how a template ends up with a `tool-search` that
+// drifts from the framework's, and an MCP mount that silently ignores
+// `frameworkTools`.
+export { attachToolSearch, createToolSearchEntry, searchToolRegistry, TOOL_SEARCH_ACTION_NAME, } from "../agent/tool-search.js";
+export { filterFrameworkToolGroups, frameworkGroupEnabled, resolveFrameworkTools, FRAMEWORK_TOOL_GROUPS, } from "../framework-tools.js";
 export { registerPromptContextProvider, } from "./agent-chat/prompt-resources.js";
 export { mountActionRoutes, } from "./action-routes.js";
 export { AGENT_RUN_OWNER_CONTEXT_KEY, seedAgentRunOwnerContext, } from "./agent-run-context.js";