@fitchmultz/pi-mcp-adapter 7.0.0 → 7.1.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.1.0] - 2026-09-27
+
+### Changed
+
+- Keep full MCP gateway/script schemas inactive until selected with `mcp_search({ enable: ["gateway", "script"] })`. Typed discovery still loads matches in one call. Selections persist on the current session branch; configured pins, legacy resource pins, configuration restrictions, and loader-excluded host allowlists retain their behavior.
+- `npm run typecheck` now also checks the test suite under the same strict settings as the source.
+
 ## [7.0.0] - 2026-09-26
 
 ### Breaking changes

package/OAUTH.md

@@ -207,7 +207,7 @@ For browser authorization, this will:
 
 ### Remote/headless authentication
 
-When Pi runs over SSH or in a headless environment, use the proxy tool to retrieve the authorization URL instead of relying on OS browser launch:
+When Pi runs over SSH or in a headless environment, use the proxy tool to retrieve the authorization URL instead of relying on OS browser launch. If `mcp` is inactive, first call `mcp_search({ enable: ["gateway"] })` (no query needed):
 
 ```
 mcp({ action: "auth-start", server: "my-oauth-server" })

package/README.md

@@ -16,7 +16,7 @@ Mario wrote about [why you might not need MCP](https://mariozechner.at/posts/202
 
 His take: skip MCP entirely, write simple CLI tools instead.
 
-The MCP ecosystem has useful databases, browsers, and APIs. This adapter keeps their full tool schemas out of context until needed. `mcp_search` discovers and loads typed tools for the next request; `mcp` handles explicit gateway actions, and `mcp_script` composes MCP calls in JavaScript. Lazy servers stay disconnected until selected discovery or a call needs them.
+The MCP ecosystem has useful databases, browsers, and APIs. This adapter keeps their full tool schemas out of context until needed. Only `mcp_search` and configured pins start active. `mcp_search` discovers and loads typed tools for the next request; `mcp_search({ enable: ["gateway"] })` loads `mcp` for gateway actions, and `mcp_search({ enable: ["script"] })` loads `mcp_script` for JavaScript composition. Lazy servers stay disconnected until selected discovery or a call needs them.
 
 ## Pi release qualification
 
@@ -124,7 +124,9 @@ mcp_search({ query: "take screenshot", server: "chrome-devtools" })
 
 The returned exact tool references become available with their full argument schemas on the next model request. The agent then calls the chosen typed tool normally. Discovery does not run it.
 
-If the host only permits `mcp`, use explicit gateway actions instead:
+To use resources, authentication, UI messages, saved-result readback, or fallback calls, first load the gateway with `mcp_search({ enable: ["gateway"] })`. No query is required and enabling alone performs no integration action or remote connection. Use `enable: ["script"]` for composition, or enable both together. Normal typed search still takes just one discovery call before a typed call.
+
+If the host only permits `mcp` (and excludes `mcp_search`), it stays eager. Use explicit gateway actions instead:
 
 ```js
 mcp({ action: "search", query: "take screenshot", server: "chrome-devtools" })
@@ -409,6 +411,8 @@ If Pi is running on a remote server and cannot open a local browser, start OAuth
 
 On Linux, if credential access fails because Pi inherited a revoked session keyring, the adapter uses a best-effort recovery path through `keyctl session - node <packaged helper>` so explicit re-authentication can write fresh credentials without killing a long-lived tmux server. This path requires `keyctl` and `node` on `PATH`; missing, locked, or otherwise unavailable credential stores still fail closed.
 
+If the gateway is inactive, first call `mcp_search({ enable: ["gateway"] })`.
+
 ```js
 mcp({ action: "auth-start", server: "linear-server" })
 ```
@@ -481,7 +485,7 @@ Persistent OAuth is unsupported out of the box on Android/Termux because `@napi-
 | `mcpServers.<name>.oauth.authorizationParams` | Extra authorization URL parameters for provider-specific OAuth extensions. Flow-owned parameters such as `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `response_type`, and `resource` cannot be overridden. |
 | `directTools` | Global default for all servers (default: false). Per-server overrides this. |
 | `freezeDirectTools` | Keep direct-tool registration stable after the initial sync so automatic reconnects and list-change notifications do not rebuild the system prompt. Use `mcp({ action: "connect", server: "server" })` or `/mcp reconnect <server>` to refresh deliberately. Default: false. |
-| `scriptMode` | Register the MCP-only `mcp_script` plain-JavaScript tool (default: true). Set to `false` to hide it. |
+| `scriptMode` | Make the MCP-only `mcp_script` plain-JavaScript tool loadable (default: true). Set to `false` to hide it. |
 | `disableProxyTool` | Hide `mcp` once configured pinned tools are available. Legacy resource pins keep it available for resource access. |
 | `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
 | `sampling` | Allow MCP servers to sample through Pi models, honoring `modelPreferences.hints` before current/default fallback (default: true when UI approval is available). |
@@ -531,7 +535,7 @@ Tune the limits with the object form:
 
 Set `"outputGuard": false` — or the env kill switch `MCP_OUTPUT_GUARD=0` — to disable the guard and restore raw output behavior. Recovery notices remain visible even when a configured cap is too small to fit them. Saved files are created with mode `0600` under the system temp directory (or the SDK host's `outputDirectory`) and are not cleaned up automatically; note that spilled MCP output may contain sensitive data.
 
-Read a retained result without repeating the MCP operation:
+Read a retained result without repeating the MCP operation. Load the gateway first if inactive with `mcp_search({ enable: ["gateway"] })`:
 
 ```js
 mcp({ action: "read-result", ref: "/returned/result/path", path: "/structuredContent/rows", fields: ["id", "title"], offset: 0, limit: 12000 })
@@ -541,7 +545,7 @@ mcp({ action: "read-result", ref: "/returned/result/path", path: "/structuredCon
 
 ### MCP Scripting
 
-For multi-call MCP work, write ordinary JavaScript: discover, inspect, call, loop, filter, chain, or fan out, then return one result. Run that code with the default-on `mcp_script` tool. Use `mcp_search` for typed discovery, a loaded typed tool for a single call, and `mcp` for explicit gateway actions. Set `settings.scriptMode` to `false` to hide the scripting tool.
+For multi-call MCP work, write ordinary JavaScript: discover, inspect, call, loop, filter, chain, or fan out, then return one result. Load the script tool with `mcp_search({ enable: ["script"] })`, then run that code with `mcp_script`. Use `mcp_search` for typed discovery, a loaded typed tool for a single call, and `mcp` for explicit gateway actions. Set `settings.scriptMode` to `false` to hide the scripting tool.
 
 The bundled `mcp-scripting` skill is a separate Pi package resource. To hide that skill while keeping the adapter extension installed, replace the package entry in Pi settings with the object form and disable package skills:
 
@@ -606,7 +610,7 @@ See the bundled `mcp-scripting` skill for the workflow and exact return shapes.
 
 ### MCP Resources
 
-Resources are catalog entries addressed by URI, separate from tools:
+Resources are catalog entries addressed by URI, separate from tools. Load the gateway first if inactive with `mcp_search({ enable: ["gateway"] })`:
 
 ```js
 mcp({ action: "resources", server: "docs", limit: 12, offset: 0 })
@@ -637,7 +641,7 @@ URL mode is advertised only in TUI mode. The adapter displays the requesting ser
 
 `mcp_search({ query, server?, limit?, offset? })` searches real tools and loads the matching typed functions for the next request. It defaults to five matches, with a maximum of 100 and zero-based pagination. Use a specific query, or an empty query with `server` to browse that server. It does not execute a hit or rewrite dynamic instructions into the system prompt.
 
-Cached eligible schemas register inactive; only pins and tools selected for the current branch are active. The adapter persists canonical `{ server, tool }` selections in native Pi session entries and restores them across resume, reload, branch navigation, and working-directory changes. Host tool allowlists remain binding.
+Cached eligible schemas and the full gateway/script definitions register inactive; only pins and tools selected for the current branch are active. Legacy resource pins keep the gateway eager. Allowed gateway/script tools also stay eager when the host excludes the loader, so restricted hosts remain usable. The adapter persists canonical `{ server, tool }` selections and enabled gateway/script features in native Pi session entries and restores them across resume, reload, branch navigation, and working-directory changes. Host tool allowlists remain binding. Manual deselection survives reload. Loaded schemas remain available rather than unloading each turn; activation changes declarations and can invalidate the prompt-cache prefix.
 
 On hosts with native tool-search support, lazy tools use exact references in namespace `mcp_<server>` with the original tool name as the leaf. Existing direct pins retain their flat prefixed names. On official Pi 0.87.1, which has no native tool search, the ordinary `mcp_search` loader activates flat tools with the same discover-then-call workflow. Always use the exact reference returned by discovery rather than constructing names.
 
@@ -748,7 +752,7 @@ MCP servers can ship interactive UIs via [MCP Apps](https://github.com/modelcont
 
 **Native rendering:** On macOS, if [Glimpse](https://github.com/hazat/glimpse) is installed (`pi install npm:glimpseui`), UIs open in a native WKWebView window instead of a browser tab. Set `MCP_UI_VIEWER=browser` to force the browser, `MCP_UI_VIEWER=glimpse` to require native rendering, or `MCP_UI_VIEWER=none` (also accepts `off` / `disabled`) to suppress the window entirely — the tool still runs and its inline result is returned to the agent, but no browser or native window opens. This is useful for headless setups, CI, or users who want the tool output delivered inline as text only. When suppressed, a one-line info notification shows the UI URL so it can still be opened manually if needed.
 
-**Bidirectional communication:** The UI talks back. When it sends a prompt or intent, the message is stored and `triggerTurn()` wakes the agent. The agent retrieves messages via `mcp({ action: "ui-messages" })` and responds, enabling conversational UIs where the app and agent collaborate in real-time.
+**Bidirectional communication:** The UI talks back. When it sends a prompt or intent, the message is stored and `triggerTurn()` wakes the agent. The agent loads the gateway if inactive with `mcp_search({ enable: ["gateway"] })`, then retrieves messages via `mcp({ action: "ui-messages" })` and responds, enabling conversational UIs where the app and agent collaborate in real-time.
 
 **Session reuse:** When the agent calls the same tool again while its UI is already open, the adapter pushes the new result to the existing window instead of replacing it. This enables live updates — the agent can refine a chart, add data, or respond to user input without losing the current view. Different tools still replace the session as before.
 
@@ -820,6 +824,7 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/fitch-mcp-adapt
 | Action | Example |
 |--------|---------|
 | Discover and load typed tools | `mcp_search({ query: "screenshot", server: "chrome-devtools", limit: 5 })` |
+| Load gateway / script | `mcp_search({ enable: ["gateway", "script"] })` |
 | Status | `mcp({ action: "status" })` |
 | List server tools | `mcp({ action: "list", server: "name", limit: 12, offset: 0 })` |
 | Search without activation | `mcp({ action: "search", query: "screenshot navigate", limit: 12 })` |
@@ -834,7 +839,7 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/fitch-mcp-adapt
 | Auth start | `mcp({ action: "auth-start", server: "name" })` |
 | Auth complete | `mcp({ action: "auth-complete", server: "name" })` after the browser callback, or supply `args: { redirectUrl: "..." }` |
 
-`action` is required. Search requires `query`; describe/call require `tool`; list/connect/instructions/resources/auth require `server`; resource reads require `server` and `uri`; saved-result reads require `ref`. Pass object `args`. Optional `server` disambiguates tool calls and descriptions.
+Load `mcp` first if inactive using the row above. `action` is required. Search requires `query`; describe/call require `tool`; list/connect/instructions/resources/auth require `server`; resource reads require `server` and `uri`; saved-result reads require `ref`. Pass object `args`. Optional `server` disambiguates tool calls and descriptions.
 
 `connect` refreshes an already connected server, including tools, resources, prompts, and instructions. Server-scoped discovery connects that server if its catalog is unknown. Global search uses known catalogs and returns `coverage: { complete, knownServers, unknownServers }`; partial coverage is never presented as an exhaustive result. Gateway search provides schemas without activating functions, so it works for gateway-only hosts.
 
@@ -875,7 +880,7 @@ Advertised tool `outputSchema` values support JSON Schema draft-07 and 2020-12.
 
 ## How It Works
 
-- Stable `mcp_search`, `mcp`, and optional `mcp_script` entry points; full typed schemas load when selected
+- Eager `mcp_search`; full `mcp`, optional `mcp_script`, and typed schemas load when selected
 - Lazy servers connect on selected discovery or calls; configured pins and eager/keep-alive servers can bootstrap intentionally
 - Tool metadata is cached to disk so search/list/describe work without live connections
 - Idle servers disconnect after 10 minutes (configurable), reconnect automatically on next use

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

@@ -19,7 +19,7 @@ import { createToolLoader, supportsNativeAsync } 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,15 @@ 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 +110,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, nativeAsyncSupported, specs => syncGateways(config, cache, specs));
     }
     const registeredPromptCommands = new Set();
     function registerPromptCommands(specs) {
@@ -260,15 +243,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, nativeAsyncSupported, specs => syncGateways(runtimeConfig, runtimeCache, specs));
         const initialization = startInitialization(ctx, owner, oauthRuntime, runtimeConfig, generation);
         if (envRaw !== undefined && envRaw !== "__none__") {
             const missingEnvDirectTools = getMissingConfiguredDirectToolServers(runtimeConfig, runtimeCache, envDirectToolOverride);
@@ -538,7 +519,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") && !tool.namespace));
     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 +542,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.namespace || (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) {
@@ -587,7 +582,7 @@ function installMcpAdapter(pi, options) {
     function registerScriptTool() {
         if (scriptToolRegistered)
             return;
-        pi.registerTool({
+        toolLoader.registerFeature("script", {
             ...(beforeExecute ? { executionMode: "sequential" } : {}),
             name: "mcp_script",
             label: "MCP Script",
@@ -609,21 +604,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 +666,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 +691,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/tool-loader.d.ts

@@ -7,6 +7,10 @@ type Reference = {
     name: string;
     namespace?: string;
 };
+export type Feature = "gateway" | "script";
+export type FeaturePolicy = Partial<Record<Feature, {
+    eager?: boolean;
+}>>;
 type SearchDefinition<TParams extends TSchema, TDetails> = Omit<ToolDefinition<TParams, TDetails>, "execute"> & {
     execute: (...args: Parameters<ToolDefinition<TParams, TDetails>["execute"]>) => Promise<AgentToolResult<TDetails> & {
         tools: Reference[];
@@ -20,12 +24,13 @@ export type SearchAPI = ExtensionAPI & {
 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;
+    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, asyncSupported?: boolean, registerGateways?: (pins: DirectToolSpec[]) => FeaturePolicy) => DirectToolSpec[];
     activate: (matches: Array<{
         server: string;
         tool: ToolMetadata;
-    }>) => Reference[];
+    }>, enable?: Feature[]) => Reference[];
     persist: () => void;
     selectedServers: () => string[];
 };

package/dist/tool-loader.js

@@ -5,6 +5,7 @@ import { createMcpDirectToolCallRenderer, renderMcpToolResult } from "./tool-res
 import { isServerDisabled } from "./types.js";
 import { normalizeDirectToolInputSchema } from "./utils.js";
 import { isToolCallApprovalRequired } from "./tool-approval.js";
+const featureRefs = { gateway: { name: "mcp" }, script: { name: "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]);
@@ -23,6 +24,10 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
     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) => {
@@ -34,8 +39,24 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
         else
             pi.setActiveTools(unique.map(ref => ref.name));
     };
+    function registerFeature(feature, definition) {
+        pi.registerTool(definition);
+        registeredFeatures.add(feature);
+    }
     function capture() {
         const current = new Set(active().map(refKey));
+        for (const feature of Object.keys(features)) {
+            if (current.has(refKey(featureRefs[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, ref, pinned }] of registered) {
             if (!available.has(id))
                 continue;
@@ -53,15 +74,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 : []) {
@@ -125,28 +150,54 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
         }
         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);
+        const policy = registerGateways?.(pins);
+        if (policy) {
+            const permittedFeatures = new Set(pi.getAllTools().map(refKey));
+            const loaderMissing = !permittedFeatures.has(refKey({ name: "mcp_search" }));
+            features = {};
+            for (const feature of Object.keys(featureRefs)) {
+                if (policy[feature] && permittedFeatures.has(refKey(featureRefs[feature]))) {
+                    features[feature] = { eager: policy[feature].eager || loaderMissing };
+                    if (selectedFeatures.has(feature) || (features[feature]?.eager && !inactiveFeatures.has(feature)))
+                        enabled.push(featureRefs[feature]);
+                }
+                else {
+                    selectedFeatures.delete(feature);
+                    inactiveFeatures.delete(feature);
+                }
+            }
+        }
         // Official 0.87 reactivates allowlisted definitions on registration. Apply our loadout last.
         const ownedRefs = new Set([...previousRefs, ...[...registered.values()].map(item => refKey(item.ref))]);
+        for (const feature of registeredFeatures)
+            ownedRefs.add(refKey(featureRefs[feature]));
         setActive([...active().filter(ref => !ownedRefs.has(refKey(ref))), ...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 permitted = new Set(pi.getAllTools().map(refKey));
+        const requestedFeatures = [...new Set(enable)].filter(feature => features[feature] && permitted.has(refKey(featureRefs[feature])));
+        setActive([...active(), ...requested.map(item => item.ref), ...requestedFeatures.map(feature => featureRefs[feature])]);
         const current = new Set(active().map(refKey));
         const tools = requested.filter(item => current.has(refKey(item.ref))).map(({ selection, ref }) => {
             selected.set(key(selection), selection);
             return ref;
         });
+        for (const feature of requestedFeatures) {
+            if (!current.has(refKey(featureRefs[feature])))
+                continue;
+            selectedFeatures.add(feature);
+            tools.push(featureRefs[feature]);
+        }
         persist();
         return tools;
     }
-    return { native, restore, sync, activate, persist, selectedServers: () => [...new Set([...selected.values()].map(item => item.server))] };
+    return { native, 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-mcp-adapter",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Fitch's independently maintained MCP adapter for Pi coding agent",
   "type": "module",
   "types": "./dist/index.d.ts",

package/skills/mcp-scripting/SKILL.md

@@ -7,6 +7,8 @@ description: Write mcp_script JavaScript for discovering, inspecting, and callin
 
 Use `mcp_script` for MCP calls with loops, filtering, chaining, fan-out, or other logic between calls. Pass ordinary JavaScript as its `code` argument. For a single call, use an already loaded typed tool. Use `mcp_search({ query, server?, limit?, offset? })` to discover and load typed tools for the next request, or explicit `mcp` actions for gateway-only workflows. Discovery never executes a search hit.
 
+If `mcp_script` is inactive, first call `mcp_search({ enable: ["script"] })`. For gateway actions, load `mcp` with `mcp_search({ enable: ["gateway"] })`. Enable both in one call when needed. Enabling does not connect to a server or run an integration action; selections stay active for the session/branch. Hosts permitting only one gateway without the loader keep that tool eager.
+
 ## Discover, inspect, then call
 
 ```js