@fitchmultz/pi-mcp-adapter 7.0.0 → 7.1.1

package/dist/direct-tools.js

@@ -15,7 +15,7 @@ export function directToolSelection(config, serverName, envOverride) {
 export function buildProxyDescription(config) {
     const servers = Object.entries(config.mcpServers).filter(([, definition]) => !isServerDisabled(definition)).map(([name]) => name).sort();
     return [
-        "MCP gateway. Use mcp_search to discover and load typed tools; mcp_script for multi-call composition. Native Pi tools are called directly.",
+        'MCP gateway. Use mcp_search to discover typed tools; enable mcp_script with mcp_search({ enable: ["script"] }) for multi-call composition. Native Pi tools are called directly.',
         `Configured servers: ${servers.join(", ") || "none"}. Catalog discovery is lazy.`,
         "Actions: status; list/search/describe; call (tool,args,server?); connect (server); instructions (server); resources (server); read-resource (server,uri); read-result (ref,path?,fields?,offset?,limit?); auth-start/auth-complete (server,args?); ui-messages.",
         "Use call when a discovered direct tool is unavailable in this host. read-result reads a retained response without repeating the remote operation.",

package/dist/index.js

@@ -15,11 +15,11 @@ import { createMcpRuntimeOwner, createOwnedUi, isAbortError } from "./runtime-ow
 import { publishMcpStatusShutdown } from "./mcp-status.js";
 import { DEFAULT_MCP_SCRIPT_TIMEOUT_MS, runMcpScript } from "./mcp-code.js";
 import { MAX_PAGE_SIZE, paginate, rankToolMatches } from "./search-ranking.js";
-import { createToolLoader, supportsNativeAsync } from "./tool-loader.js";
+import { createToolLoader } from "./tool-loader.js";
 import { gatewayParameters, prepareGatewayArguments } from "./gateway-arguments.js";
 import { executeResourceList, executeResourceRead } from "./resource-tools.js";
 import { guardMcpOutput, guardedMcpDetails, readMcpResult, resolveMcpOutputGuardOptions } from "./mcp-output-guard.js";
-import { abortable } from "./abort.js";
+import { abortable, throwIfAborted } from "./abort.js";
 import { onSessionCheckpoint, prepareMcpCheckpoint } from "./checkpoint.js";
 export { MCP_STATUS_EVENT, MCP_STATUS_SNAPSHOT_VERSION, } from "./types.js";
 const INIT_WAIT_TIMEOUT_MS = 30_000;
@@ -90,29 +90,14 @@ function installMcpAdapter(pi, options) {
         ? cloneMcpConfig(sessionConfig)
         : { mcpServers: {} };
     const earlyCache = null;
+    let currentConfig = earlyConfig;
     const envRaw = process.env.MCP_DIRECT_TOOLS;
     const envDirectToolOverride = envRaw?.split(",").map(s => s.trim()).filter(Boolean);
     const toolLoader = createToolLoader(pi, () => state, () => initPromise, beforeExecute);
-    const deactivatedTools = new Set();
     let runtimeCwd;
-    let nativeAsyncSupported = false;
     let proxyToolRegistered = false;
     let proxyToolDescription = null;
     let directToolsFrozen = false;
-    function deactivateTools(toolNames) {
-        if (toolNames.length === 0)
-            return;
-        const remove = new Set(toolNames);
-        const activeTools = pi.getActiveTools();
-        for (const toolName of toolNames) {
-            if (activeTools.includes(toolName))
-                deactivatedTools.add(toolName);
-        }
-        const nextActiveTools = activeTools.filter((name) => !remove.has(name));
-        if (nextActiveTools.length !== activeTools.length) {
-            pi.setActiveTools(nextActiveTools);
-        }
-    }
     function applyDirectToolConfigChanges(changes) {
         if (!state)
             return;
@@ -124,12 +109,9 @@ function installMcpAdapter(pi, options) {
         }
     }
     function syncToolSurface(ctx) {
-        const config = state?.config ?? earlyConfig;
+        const config = state?.config ?? currentConfig;
         const cache = loadMetadataCache(state?.metadataCacheEnabled ?? false);
-        toolLoader.sync(config, cache, envRaw === "__none__" ? null : envDirectToolOverride, nativeAsyncSupported, specs => {
-            syncProxyTool(config, cache, specs);
-            syncScriptTool(config);
-        });
+        toolLoader.sync(config, cache, envRaw === "__none__" ? null : envDirectToolOverride, specs => syncGateways(config, cache, specs));
     }
     const registeredPromptCommands = new Set();
     function registerPromptCommands(specs) {
@@ -219,7 +201,6 @@ function installMcpAdapter(pi, options) {
     }
     async function startSession(ctx) {
         runtimeCwd = ctx.cwd;
-        nativeAsyncSupported = supportsNativeAsync(ctx);
         directToolsFrozen = false;
         const generation = ++lifecycleGeneration;
         const previousState = state;
@@ -260,15 +241,13 @@ function installMcpAdapter(pi, options) {
         if (options.transformConfig) {
             runtimeConfig = cloneMcpConfig(options.transformConfig(cloneMcpConfig(runtimeConfig), ctx));
         }
+        currentConfig = runtimeConfig;
         const metadataCacheEnabled = ctx.isProjectTrusted()
             || !isPathInsideProject(getMetadataCachePath(), ctx.cwd);
         toolLoader.restore(ctx);
         registerPromptCommands(resolveCachedPrompts(runtimeConfig, metadataCacheEnabled));
         const runtimeCache = loadMetadataCache(metadataCacheEnabled);
-        toolLoader.sync(runtimeConfig, runtimeCache, envRaw === "__none__" ? null : envDirectToolOverride, nativeAsyncSupported, specs => {
-            syncProxyTool(runtimeConfig, runtimeCache, specs);
-            syncScriptTool(runtimeConfig);
-        });
+        toolLoader.sync(runtimeConfig, runtimeCache, envRaw === "__none__" ? null : envDirectToolOverride, specs => syncGateways(runtimeConfig, runtimeCache, specs));
         const initialization = startInitialization(ctx, owner, oauthRuntime, runtimeConfig, generation);
         if (envRaw !== undefined && envRaw !== "__none__") {
             const missingEnvDirectTools = getMissingConfiguredDirectToolServers(runtimeConfig, runtimeCache, envDirectToolOverride);
@@ -283,7 +262,6 @@ function installMcpAdapter(pi, options) {
         syncToolSurface(ctx);
     });
     pi.on("model_select", (_event, ctx) => {
-        nativeAsyncSupported = supportsNativeAsync(ctx);
         if (state)
             syncToolSurface(ctx);
     });
@@ -538,7 +516,17 @@ function installMcpAdapter(pi, options) {
         owner?.throwIfInactive();
         return state ?? { content: [{ type: "text", text: "MCP not initialized" }], details: { error: "not_initialized" } };
     }
+    const unavailableFeatures = (enable = [], tools) => enable.filter(feature => !tools.some(tool => tool.name === (feature === "gateway" ? "mcp" : "mcp_script")));
     async function searchAndLoad(params, signal, ctx) {
+        throwIfAborted(signal);
+        if (params.query === undefined && !params.enable?.length)
+            throw new Error("Provide query or enable.");
+        // Loading front doors does not require initialization or connect to a server.
+        if (params.query === undefined) {
+            const tools = toolLoader.activate([], params.enable);
+            const unavailable = unavailableFeatures(params.enable, tools);
+            return { content: [{ type: "text", text: `Loaded for the next request: ${JSON.stringify(tools)}${unavailable.length ? `. Unavailable under configuration or host policy: ${unavailable.join(", ")}` : ""}` }], details: { loaded: tools, unavailable }, tools };
+        }
         const ready = await getToolState(signal);
         if ("content" in ready)
             return { ...ready, tools: [] };
@@ -551,23 +539,27 @@ function installMcpAdapter(pi, options) {
         const matches = params.query.trim() ? rankToolMatches(ready, params.query, params.server)
             : params.server ? (ready.toolMetadata.get(params.server) ?? []).filter(tool => !tool.resourceUri).map(tool => ({ server: params.server, tool })).sort((a, b) => a.tool.name.localeCompare(b.tool.name)) : [];
         const page = paginate(matches, params.offset ?? 0, params.limit ?? 5);
-        const tools = toolLoader.activate(page.items);
-        const result = executeSearch(ready, params.query, params.server, tools.length < page.items.length, params.limit ?? 5, params.offset, "mcp_search");
+        const tools = toolLoader.activate(page.items, params.enable);
+        const unavailable = unavailableFeatures(params.enable, tools);
+        const typedCount = tools.filter(tool => tool.name !== "mcp" && tool.name !== "mcp_script").length;
+        const result = executeSearch(ready, params.query, params.server, typedCount < page.items.length, params.limit ?? 5, params.offset, "mcp_search");
         const guarded = await guardMcpOutput([
             ...result.content,
-            { type: "text", text: tools.length ? `Loaded for the next request: ${JSON.stringify(tools)}` : "No direct tools loaded. Use mcp action call or tools.call in mcp_script with the returned exact names." },
+            { type: "text", text: tools.length ? `Loaded for the next request: ${JSON.stringify(tools)}` : 'No direct tools loaded. Enable gateway or script with mcp_search({ enable: ["gateway"] }) or mcp_search({ enable: ["script"] }), then use mcp action call or tools.call with the returned exact names.' },
+            ...(unavailable.length ? [{ type: "text", text: `Unavailable under configuration or host policy: ${unavailable.join(", ")}` }] : []),
         ], resolveMcpOutputGuardOptions(ready.config.settings, ready.outputDirectory));
-        return { content: guarded.content, details: { ...result.details, ...guardedMcpDetails(guarded), loaded: tools }, tools };
+        return { content: guarded.content, details: { ...result.details, ...guardedMcpDetails(guarded), loaded: tools, ...(unavailable.length ? { unavailable } : {}) }, tools };
     }
     const searchDefinition = {
         name: "mcp_search", label: "MCP Search",
-        description: "Discover MCP tools by name, description, and parameter guidance, and load matching tools with their complete schemas for the next request. Start with a specific task query. Specify server to discover an uncached server; an empty query with server browses it. Results report incomplete catalog coverage. Resources use mcp action resources/read-resource.",
+        description: "Discover and load typed MCP tools for the next request. Use query; server discovers an uncached server (empty query browses it). Results report incomplete coverage. Or enable gateway for mcp status/list/search/describe/call/connect/instructions, resources/read-resource, read-result, auth-start/auth-complete and ui-messages; enable script for JavaScript composition, resources and saved-result readback. Enable alone performs no integration action. Loaded schemas stay available in this session/branch.",
         parameters: Type.Object({
-            query: Type.String(),
+            query: Type.Optional(Type.String()),
+            enable: Type.Optional(Type.Array(Type.Union([Type.Literal("gateway"), Type.Literal("script")]), { minItems: 1, uniqueItems: true })),
             server: Type.Optional(Type.String()),
             limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_PAGE_SIZE, description: "Tools to load (default 5)." })),
             offset: Type.Optional(Type.Integer({ minimum: 0 })),
-        }),
+        }, { anyOf: [{ required: ["query"] }, { required: ["enable"] }] }),
         renderResult: renderMcpToolResult,
         async execute(toolCallId, params, signal, _onUpdate, ctx) {
             if (beforeExecute) {
@@ -579,15 +571,12 @@ function installMcpAdapter(pi, options) {
             return searchAndLoad(params, signal, ctx);
         },
     };
-    if (toolLoader.native)
-        pi.registerToolSearch(searchDefinition);
-    else
-        pi.registerTool(searchDefinition);
+    pi.registerTool(searchDefinition);
     let scriptToolRegistered = false;
     function registerScriptTool() {
         if (scriptToolRegistered)
             return;
-        pi.registerTool({
+        toolLoader.registerFeature("script", {
             ...(beforeExecute ? { executionMode: "sequential" } : {}),
             name: "mcp_script",
             label: "MCP Script",
@@ -609,21 +598,8 @@ function installMcpAdapter(pi, options) {
         });
         scriptToolRegistered = true;
     }
-    function syncScriptTool(config) {
-        if (config.settings?.scriptMode === false) {
-            if (scriptToolRegistered)
-                deactivateTools(["mcp_script"]);
-            return;
-        }
-        registerScriptTool();
-        if (deactivatedTools.delete("mcp_script")) {
-            const activeTools = pi.getActiveTools();
-            if (!activeTools.includes("mcp_script"))
-                pi.setActiveTools([...activeTools, "mcp_script"]);
-        }
-    }
     function registerProxyTool(description) {
-        pi.registerTool({
+        toolLoader.registerFeature("gateway", {
             ...(beforeExecute ? { executionMode: "sequential" } : {}),
             name: "mcp", label: "MCP", description,
             promptSnippet: "MCP server operations, resources, saved result readback, and fallback tool calls",
@@ -684,7 +660,10 @@ function installMcpAdapter(pi, options) {
         proxyToolRegistered = true;
         proxyToolDescription = description;
     }
-    function syncProxyTool(config, cache, directSpecs) {
+    function syncGateways(config, cache, directSpecs) {
+        const policy = {};
+        if (config.settings?.scriptMode !== false)
+            policy.script = {};
         const missingConfiguredDirectToolServers = getMissingConfiguredDirectToolServers(config, cache, envRaw === undefined || envRaw === "__none__" ? undefined : envDirectToolOverride);
         const hasPinnedResources = envRaw !== "__none__" && Object.entries(config.mcpServers).some(([server, definition]) => {
             if (definition.disabled === true)
@@ -706,21 +685,15 @@ function installMcpAdapter(pi, options) {
             if (!proxyToolRegistered || proxyToolDescription !== description) {
                 registerProxyTool(description);
             }
-            if (deactivatedTools.delete("mcp")) {
-                const activeTools = pi.getActiveTools();
-                if (!activeTools.includes("mcp")) {
-                    pi.setActiveTools([...activeTools, "mcp"]);
-                }
-            }
-            return;
+            policy.gateway = { eager: hasPinnedResources };
         }
-        if (proxyToolRegistered)
-            deactivateTools(["mcp"]);
+        if (policy.script)
+            registerScriptTool();
+        return policy;
     }
     // A transform needs the session context before any configured tool surface is registered.
     if (!options.transformConfig) {
-        syncProxyTool(earlyConfig, earlyCache, []);
-        syncScriptTool(earlyConfig);
+        syncGateways(earlyConfig, earlyCache, []);
     }
 }
 export function createMcpAdapter(options = {}) {

package/dist/mcp-output-guard.js

@@ -223,7 +223,7 @@ export function formatMcpPayloadFile(file) {
     return `[MCP ${file.kind === "audio" ? "audio" : "binary resource"}${file.uri ? ` (${file.uri})` : ""}: ${file.mimeType ?? "unknown MIME type"}; not rendered. ${file.path ? `Saved file: ${file.path}` : `Could not save: ${file.error}`}]`;
 }
 export function formatMcpResultReference(ref) {
-    return `[MCP result saved: ${JSON.stringify(ref)}. Inspect without repeating the call using mcp action "read-result" or tools.readResult with this ref. Optionally select a JSON Pointer with path.]`;
+    return `[MCP result saved: ${JSON.stringify(ref)}. Inspect without repeating the call using mcp action "read-result" or tools.readResult with this ref. If inactive, first mcp_search({ enable: ["gateway"] }) or mcp_search({ enable: ["script"] }). Optionally select a JSON Pointer with path.]`;
 }
 function summarizeMcpResult(result, rawBytes, artifact) {
     const { path: fullResultPath, error: resultWriteError } = artifact;

package/dist/proxy-modes.js

@@ -21,7 +21,7 @@ function disabledResult(mode, serverName) {
         details: { mode, error: "server_disabled", server: serverName, message },
     };
 }
-function getAuthRequiredMessage(state, serverName, defaultMessage = `Server "${serverName}" requires OAuth authentication. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`) {
+function getAuthRequiredMessage(state, serverName, defaultMessage = `Server "${serverName}" requires OAuth authentication. If mcp is inactive, first mcp_search({ enable: ["gateway"] }). Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`) {
     const oauth = state.config.mcpServers[serverName]?.oauth;
     if (oauth && oauth.crossAppAccess)
         defaultMessage = `Server "${serverName}" requires enterprise authorization. Check oauth.crossAppAccess IdP configuration and ID-token source, then retry.`;
@@ -33,7 +33,7 @@ function getAuthFailedMessage(state, serverName, message) {
     if (customGuidance || (oauth && oauth.crossAppAccess)) {
         return `OAuth authentication failed for "${serverName}": ${message}. ${getAuthRequiredMessage(state, serverName)}`;
     }
-    return `OAuth authentication failed for "${serverName}": ${message}. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`;
+    return `OAuth authentication failed for "${serverName}": ${message}. If mcp is inactive, first mcp_search({ enable: ["gateway"] }). Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`;
 }
 function getRedirectPort(authorizationUrl) {
     try {
@@ -91,7 +91,7 @@ async function attemptAutoAuth(state, serverName, signal) {
     if (!state.ui && !isNonInteractiveOAuth(definition.oauth)) {
         return {
             status: "failed",
-            message: getAuthRequiredMessage(state, serverName, `Server "${serverName}" requires OAuth authentication. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`),
+            message: getAuthRequiredMessage(state, serverName, `Server "${serverName}" requires OAuth authentication. If mcp is inactive, first mcp_search({ enable: ["gateway"] }). Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`),
         };
     }
     try {
@@ -268,7 +268,7 @@ export async function executeAuthStart(state, serverName, signal) {
     const definition = state.config.mcpServers[serverName];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers (load it first with mcp_search({ enable: ["gateway"] }) if inactive).` }],
             details: { mode: "auth-start", error: "not_found", server: serverName },
         };
     }
@@ -314,7 +314,7 @@ export async function executeAuthComplete(state, serverName, input, signal) {
     const definition = state.config.mcpServers[serverName];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers (load it first with mcp_search({ enable: ["gateway"] }) if inactive).` }],
             details: { mode: "auth-complete", error: "not_found", server: serverName },
         };
     }
@@ -372,7 +372,7 @@ export function executeDescribe(state, toolName, serverFilter) {
             return disabledResult("describe", disabled[0]);
         const suggestions = rankSuggestions(state, toolName, 5, serverFilter);
         const hint = suggestions.length > 0
-            ? `Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ action: "describe", tool: "${suggestions[0]}" }).`
+            ? `Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ action: "describe", tool: "${suggestions[0]}" }). Load if inactive: mcp_search({ enable: ["gateway"] }).`
             : `Use mcp_search({ query: "..." }) to search.`;
         return {
             content: [{ type: "text", text: `Tool "${toolName}" not found. ${hint}` }],
@@ -461,7 +461,7 @@ export function executeList(state, server, limit = 12, offset = 0) {
     const definition = state.config.mcpServers[server];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${server}" not found. Use mcp({ action: "status" }) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${server}" not found. Use mcp({ action: "status" }) to see available servers (load it first with mcp_search({ enable: ["gateway"] }) if inactive).` }],
             details: { mode: "list", server, tools: [], count: 0, error: "not_found" },
         };
     }
@@ -534,7 +534,7 @@ export function executeInstructions(state, server) {
     const definition = state.config.mcpServers[server];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${server}" not found. Use mcp({ action: "status" }) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${server}" not found. Use mcp({ action: "status" }) to see available servers (load it first with mcp_search({ enable: ["gateway"] }) if inactive).` }],
             details: { mode: "instructions", server, error: "not_found" },
         };
     }
@@ -565,7 +565,7 @@ export async function executeConnect(state, serverName, signal, limit, offset) {
     const definition = state.config.mcpServers[serverName];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers (load it first with mcp_search({ enable: ["gateway"] }) if inactive).` }],
             details: { mode: "connect", error: "not_found", server: serverName },
         };
     }
@@ -962,6 +962,7 @@ export async function executeCall(state, toolName, args, serverOverride, getPiTo
         let hint = suggestions.length
             ? ` Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ action: "describe", tool: ${JSON.stringify(suggestions[0])} }).`
             : serverName ? ` Search with mcp({ action: "search", query: ${JSON.stringify(toolName)}, server: ${JSON.stringify(serverName)} }).` : ' Use mcp({ action: "search", query: "..." }) to search.';
+        hint += ' If mcp is inactive, load it with mcp_search({ enable: ["gateway"] }).';
         if (serverName && state.toolMetadata.has(serverName) && state.manager.getConnection(serverName)?.status !== "connected")
             hint += ` Refresh a stale catalog with mcp({ action: "connect", server: ${JSON.stringify(serverName)} }).`;
         return {
@@ -973,7 +974,7 @@ export async function executeCall(state, toolName, args, serverOverride, getPiTo
         return missing();
     const definition = state.config.mcpServers[serverName];
     if (!definition)
-        return { content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }], details: { mode: "call", error: "server_not_found", server: serverName, requestedTool: toolName } };
+        return { content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers (load it first with mcp_search({ enable: ["gateway"] }) if inactive).` }], details: { mode: "call", error: "server_not_found", server: serverName, requestedTool: toolName } };
     if (isServerDisabled(definition))
         return disabledResult("call", serverName);
     const cached = state.toolMetadata.get(serverName);

package/dist/server-manager.js

@@ -691,7 +691,8 @@ export class McpServerManager {
         let client;
         client = new ManagedClient({ name: `pi-mcp-${serverName}`, version: ADAPTER_VERSION }, {
             versionNegotiation: { mode: definition.protocolVersion ?? (definition.url ? "auto" : "legacy") },
-            listMaxPages: 0,
+            // ponytail: reject catalogs over 1024 pages; raise this native cap if a real catalog needs more.
+            listMaxPages: 1024,
             ...(Object.keys(capabilities).length > 0 ? { capabilities } : {}),
             listChanged: {
                 tools: {

package/dist/tool-loader.d.ts

@@ -1,32 +1,22 @@
-import type { AgentToolResult, ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type TSchema } from "typebox";
 import { type MetadataCache } from "./metadata-cache.ts";
 import type { McpExtensionState } from "./state.ts";
 import { type DirectToolSpec, type McpAdapterOptions, type McpConfig, type ToolMetadata } from "./types.ts";
-type Reference = {
-    name: string;
-    namespace?: string;
-};
-type SearchDefinition<TParams extends TSchema, TDetails> = Omit<ToolDefinition<TParams, TDetails>, "execute"> & {
-    execute: (...args: Parameters<ToolDefinition<TParams, TDetails>["execute"]>) => Promise<AgentToolResult<TDetails> & {
-        tools: Reference[];
-    }>;
-};
-export type SearchAPI = ExtensionAPI & {
-    registerToolSearch?: <TParams extends TSchema, TDetails>(definition: SearchDefinition<TParams, TDetails>) => void;
-    getActiveToolReferences?: () => Reference[];
-    setActiveToolReferences?: (tools: Reference[]) => void;
-};
-export declare function supportsNativeAsync(ctx: ExtensionContext): boolean;
-export declare function createToolLoader(pi: SearchAPI, getState: () => McpExtensionState | null, getInitPromise: () => Promise<McpExtensionState> | null, beforeExecute?: McpAdapterOptions["beforeExecute"]): {
-    native: boolean;
+export type Feature = "gateway" | "script";
+export type FeaturePolicy = Partial<Record<Feature, {
+    eager?: boolean;
+}>>;
+export declare function createToolLoader(pi: ExtensionAPI, getState: () => McpExtensionState | null, getInitPromise: () => Promise<McpExtensionState> | null, beforeExecute?: McpAdapterOptions["beforeExecute"]): {
+    registerFeature: <TParams extends TSchema, TDetails>(feature: Feature, definition: ToolDefinition<TParams, TDetails>) => void;
     restore: (ctx: ExtensionContext) => void;
-    sync: (config: McpConfig, cache: MetadataCache | null, env?: string[] | null, asyncSupported?: boolean, registerGateways?: (pins: DirectToolSpec[]) => void) => DirectToolSpec[];
+    sync: (config: McpConfig, cache: MetadataCache | null, env?: string[] | null, registerGateways?: (pins: DirectToolSpec[]) => FeaturePolicy) => DirectToolSpec[];
     activate: (matches: Array<{
         server: string;
         tool: ToolMetadata;
-    }>) => Reference[];
+    }>, enable?: Feature[]) => {
+        name: string;
+    }[];
     persist: () => void;
     selectedServers: () => string[];
 };
-export {};

package/dist/tool-loader.js

@@ -4,42 +4,50 @@ import { isServerCacheValid, reconstructToolMetadata } from "./metadata-cache.js
 import { createMcpDirectToolCallRenderer, renderMcpToolResult } from "./tool-result-renderer.js";
 import { isServerDisabled } from "./types.js";
 import { normalizeDirectToolInputSchema } from "./utils.js";
-import { isToolCallApprovalRequired } from "./tool-approval.js";
+const featureNames = { gateway: "mcp", script: "mcp_script" };
 const ENTRY = "mcp-tool-selection";
 const key = (value) => JSON.stringify([value.server, value.tool]);
-const refKey = (value) => JSON.stringify([value.namespace ?? null, value.name]);
 const reserved = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls", "mcp", "mcp_search", "mcp_script"]);
-export function supportsNativeAsync(ctx) {
-    const compat = ctx.model?.compat;
-    return "getPendingToolCalls" in ctx && typeof ctx.getPendingToolCalls === "function"
-        && !!compat && "supportsAsyncTools" in compat && compat.supportsAsyncTools === true;
-}
 export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
-    const native = typeof pi.registerToolSearch === "function"
-        && typeof pi.getActiveToolReferences === "function"
-        && typeof pi.setActiveToolReferences === "function";
     pi.registerEntryRenderer(ENTRY, () => undefined);
     const registered = new Map();
     let available = new Set();
     let selected = new Map();
     let inactive = new Map();
+    let features = {};
+    let selectedFeatures = new Set();
+    let inactiveFeatures = new Set();
+    const registeredFeatures = new Set();
     let restoring = true;
-    const active = () => native ? pi.getActiveToolReferences() : pi.getActiveTools().map(name => ({ name }));
-    const setActive = (refs) => {
-        const unique = [...new Map(refs.map(ref => [refKey(ref), ref])).values()];
+    const active = () => pi.getActiveTools();
+    const setActive = (names) => {
+        const unique = [...new Set(names)];
         if (JSON.stringify(active()) === JSON.stringify(unique))
             return;
-        if (native)
-            pi.setActiveToolReferences(unique);
-        else
-            pi.setActiveTools(unique.map(ref => ref.name));
+        pi.setActiveTools(unique);
     };
+    function registerFeature(feature, definition) {
+        pi.registerTool(definition);
+        registeredFeatures.add(feature);
+    }
     function capture() {
-        const current = new Set(active().map(refKey));
-        for (const [id, { selection, ref, pinned }] of registered) {
+        const current = new Set(active());
+        for (const feature of Object.keys(features)) {
+            if (current.has(featureNames[feature])) {
+                if (!features[feature]?.eager)
+                    selectedFeatures.add(feature);
+                inactiveFeatures.delete(feature);
+            }
+            else {
+                selectedFeatures.delete(feature);
+                if (features[feature]?.eager)
+                    inactiveFeatures.add(feature);
+            }
+        }
+        for (const [id, { selection, name, pinned }] of registered) {
             if (!available.has(id))
                 continue;
-            if (current.has(refKey(ref))) {
+            if (current.has(name)) {
                 if (!pinned)
                     selected.set(id, selection);
                 inactive.delete(id);
@@ -53,15 +61,19 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
     }
     function persist() {
         capture();
-        pi.appendEntry(ENTRY, { selected: [...selected.values()], inactive: [...inactive.values()] });
+        pi.appendEntry(ENTRY, { selected: [...selected.values()], inactive: [...inactive.values()], features: [...selectedFeatures], inactiveFeatures: [...inactiveFeatures] });
     }
     function restore(ctx) {
         selected = new Map();
         inactive = new Map();
+        selectedFeatures = new Set();
+        inactiveFeatures = new Set();
         for (const entry of ctx.sessionManager.getBranch()) {
             if (entry.type !== "custom" || entry.customType !== ENTRY || !entry.data || typeof entry.data !== "object")
                 continue;
             const data = entry.data;
+            selectedFeatures = new Set(Array.isArray(data.features) ? data.features.filter(value => value === "gateway" || value === "script") : []);
+            inactiveFeatures = new Set(Array.isArray(data.inactiveFeatures) ? data.inactiveFeatures.filter(value => value === "gateway" || value === "script") : []);
             for (const [field, target] of [[data.selected, selected], [data.inactive, inactive]]) {
                 target.clear();
                 for (const selection of Array.isArray(field) ? field : []) {
@@ -72,11 +84,11 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
         }
         restoring = true;
     }
-    function sync(config, cache, env, asyncSupported = false, registerGateways) {
+    function sync(config, cache, env, registerGateways) {
         if (!restoring)
             capture();
-        const previousRefs = new Set([...registered.values()].map(item => refKey(item.ref)));
-        const existing = new Set(pi.getAllTools().map(tool => refKey(tool)));
+        const previousNames = new Set([...registered.values()].map(item => item.name));
+        const existing = new Set(pi.getAllTools().map(tool => tool.name));
         const specs = [];
         for (const [server, definition] of Object.entries(env === null ? {} : config.mcpServers)) {
             if (isServerDisabled(definition))
@@ -89,27 +101,26 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
                 if (tool.resourceUri)
                     continue;
                 const pinned = selection === true || (Array.isArray(selection) && selection.includes(tool.originalName));
-                const ref = native && !pinned ? { namespace: `mcp_${server}`, name: tool.originalName } : { name: prefixedName };
-                specs.push({ spec: { ...tool, prefixedName, serverName: server }, selection: { server, tool: tool.originalName }, ref, pinned });
+                specs.push({ spec: { ...tool, prefixedName, serverName: server }, selection: { server, tool: tool.originalName }, name: prefixedName, pinned });
             }
         }
         const counts = new Map();
-        for (const { ref } of specs)
-            counts.set(refKey(ref), (counts.get(refKey(ref)) ?? 0) + 1);
+        for (const { name } of specs)
+            counts.set(name, (counts.get(name) ?? 0) + 1);
         available = new Set();
         const enabled = [];
-        for (const { spec, selection, ref, pinned } of specs) {
+        for (const { spec, selection, name, pinned } of specs) {
             const id = key(selection);
-            const refId = refKey(ref);
-            if ((!ref.namespace && reserved.has(ref.name)) || counts.get(refId) > 1 || (existing.has(refId) && !previousRefs.has(refId)))
+            if (reserved.has(name) || counts.get(name) > 1 || (existing.has(name) && !previousNames.has(name)))
                 continue;
             available.add(id);
-            const asyncTool = asyncSupported && !beforeExecute && !spec.uiResourceUri && !isToolCallApprovalRequired(config, spec.serverName, spec);
-            const fingerprint = JSON.stringify({ spec, ref, asyncTool });
+            const fingerprint = JSON.stringify({ spec, name });
             if (registered.get(id)?.fingerprint !== fingerprint) {
                 pi.registerTool({
-                    ...ref,
-                    ...(asyncTool ? { async: true } : {}),
+                    name,
+                    namespace: { name: `mcp_${spec.serverName}` },
+                    // Inactive direct tools are not callable through codemode or nested execution.
+                    defaultActive: false,
                     ...(beforeExecute ? { executionMode: "sequential" } : {}),
                     label: spec.title ?? `MCP: ${spec.originalName}`,
                     description: spec.description || "(no description)",
@@ -119,34 +130,60 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
                     renderResult: renderMcpToolResult,
                 });
             }
-            registered.set(id, { selection, ref, fingerprint, pinned });
+            registered.set(id, { selection, name, fingerprint, pinned });
             if (selected.has(id) || (pinned && !inactive.has(id)))
-                enabled.push(ref);
+                enabled.push(name);
+        }
+        const permitted = new Set(pi.getAllTools().map(tool => tool.name));
+        const pins = specs.filter(item => item.pinned && available.has(key(item.selection)) && permitted.has(item.name)).map(item => item.spec);
+        const policy = registerGateways?.(pins);
+        if (policy) {
+            const permittedFeatures = new Set(pi.getAllTools().map(tool => tool.name));
+            const loaderMissing = !permittedFeatures.has("mcp_search");
+            features = {};
+            for (const feature of Object.keys(featureNames)) {
+                if (policy[feature] && permittedFeatures.has(featureNames[feature])) {
+                    features[feature] = { eager: policy[feature].eager || loaderMissing };
+                    if (selectedFeatures.has(feature) || (features[feature]?.eager && !inactiveFeatures.has(feature)))
+                        enabled.push(featureNames[feature]);
+                }
+                else {
+                    selectedFeatures.delete(feature);
+                    inactiveFeatures.delete(feature);
+                }
+            }
         }
-        const permitted = new Set(pi.getAllTools().map(refKey));
-        const pins = specs.filter(item => item.pinned && available.has(key(item.selection)) && permitted.has(refKey(item.ref))).map(item => item.spec);
-        registerGateways?.(pins);
         // Official 0.87 reactivates allowlisted definitions on registration. Apply our loadout last.
-        const ownedRefs = new Set([...previousRefs, ...[...registered.values()].map(item => refKey(item.ref))]);
-        setActive([...active().filter(ref => !ownedRefs.has(refKey(ref))), ...enabled]);
+        const ownedNames = new Set([...previousNames, ...[...registered.values()].map(item => item.name)]);
+        for (const feature of registeredFeatures)
+            ownedNames.add(featureNames[feature]);
+        setActive([...active().filter(name => !ownedNames.has(name)), ...enabled]);
         restoring = false;
         return pins;
     }
-    function activate(matches) {
+    function activate(matches, enable = []) {
         const requested = matches.flatMap(({ server, tool }) => {
             const id = key({ server, tool: tool.originalName });
             const registration = available.has(id) ? registered.get(id) : undefined;
             return registration ? [registration] : [];
         });
         // No await between reading and extending the current loadout: parallel searches union their selections.
-        setActive([...active(), ...requested.map(item => item.ref)]);
-        const current = new Set(active().map(refKey));
-        const tools = requested.filter(item => current.has(refKey(item.ref))).map(({ selection, ref }) => {
+        const permitted = new Set(pi.getAllTools().map(tool => tool.name));
+        const requestedFeatures = [...new Set(enable)].filter(feature => features[feature] && permitted.has(featureNames[feature]));
+        setActive([...active(), ...requested.map(item => item.name), ...requestedFeatures.map(feature => featureNames[feature])]);
+        const current = new Set(active());
+        const tools = requested.filter(item => current.has(item.name)).map(({ selection, name }) => {
             selected.set(key(selection), selection);
-            return ref;
+            return { name };
         });
+        for (const feature of requestedFeatures) {
+            if (!current.has(featureNames[feature]))
+                continue;
+            selectedFeatures.add(feature);
+            tools.push({ name: featureNames[feature] });
+        }
         persist();
         return tools;
     }
-    return { native, restore, sync, activate, persist, selectedServers: () => [...new Set([...selected.values()].map(item => item.server))] };
+    return { registerFeature, restore, sync, activate, persist, selectedServers: () => [...new Set([...selected.values()].map(item => item.server))] };
 }

package/dist/ui-server.js

@@ -481,7 +481,7 @@ export async function startUiServer(options) {
         }
         catch (error) {
             if (error instanceof SessionRecoveryAuthRequiredError) {
-                const fallback = `Server "${options.serverName}" requires OAuth authentication. Run mcp({ action: "auth-start", server: "${options.serverName}" }) to get a browser URL, or /mcp-auth ${options.serverName} in an interactive local session.`;
+                const fallback = `Server "${options.serverName}" requires OAuth authentication. If mcp is inactive, first mcp_search({ enable: ["gateway"] }). Run mcp({ action: "auth-start", server: "${options.serverName}" }) to get a browser URL, or /mcp-auth ${options.serverName} in an interactive local session.`;
                 const message = error.authMessage ?? (options.config
                     ? formatAuthRequiredMessage(options.config, options.serverName, fallback)
                     : fallback);