@earendil-works/pi-coding-agent 0.99.1 → 1.0.0

package/dist/extensions/mcp/index.d.ts

@@ -3,12 +3,15 @@
  *
  * Connects the servers from `mcp.json` and the servers extensions register with
  * `pi.registerMcpServer()` when a session starts, and servers registered later right away. A server
- * in `mcp.json` takes precedence over a registered server of the same name. Tools are registered as
- * `mcp__<server>__<tool>`. By default (`"exposure": "codemode"`) the tools are only callable from
- * codemode scripts, which keeps large MCP tool lists out of the model's tool declarations; the
- * codemode tool is activated for that unless `autoEnableCodemode` is false. `"codemode-deferred"`
- * leaves them out of the codemode description as well. `"deferred"` declares them to the model once
- * the `tool_search` tool loads them, and activates `tool_search` instead of codemode.
+ * in `mcp.json` takes precedence over a registered server of the same name. Connections run in the
+ * background: the first prompt waits only for servers with `direct` tools, and codemode scripts,
+ * `tool_search`, and the resource tools wait for the servers they need when they run. Tools are
+ * registered as `mcp__<server>__<tool>`. By default (`"exposure": "codemode"`) the tools are only
+ * callable from codemode scripts, which keeps MCP tools out of the model's tool declarations and
+ * the codemode description: scripts find the tools with `searchTools()` and the server instructions
+ * with `describeNamespace()`. The codemode tool is activated for that unless `autoEnableCodemode` is
+ * false. `"deferred"` declares the tools to the model once the `tool_search` tool loads them, and
+ * activates `tool_search` instead of codemode.
  * `"exposure": "direct"` declares them to the model right away, and `"hidden"` makes them
  * unreachable. `toolExposure` overrides the exposure of single tools. Servers with resources are
  * reached through Codex's `list_mcp_resources`, `list_mcp_resource_templates`, and
@@ -41,11 +44,32 @@ export interface McpExtensionOptions {
     /** Saves `/mcp` changes to the server's config file. Defaults to editing its `mcp.json`. */
     updateConfig?: (entry: McpServerEntry, patch: McpServerConfigPatch) => void;
     /**
-     * How long the first prompt waits for servers that are still connecting at startup, in
-     * milliseconds. Their tools become available when they connect. Default: 10000.
+     * How long the first prompt waits for servers with `direct` tools that are still connecting at
+     * startup, in milliseconds. Their tools become available when they connect. Other servers are
+     * waited for when a script or search needs them. Default: 10000.
      */
     startupWaitMs?: number;
 }
+/** Name of the system prompt section that lists the servers whose tools are not declared. */
+export declare const MCP_SERVERS_SECTION = "mcp_servers";
+/**
+ * Characters of the whole section. Descriptions shrink to fit; when the server lines alone do not
+ * fit, the last servers are left out and counted in a closing line.
+ */
+export declare const MAX_SERVERS_SECTION_CHARS = 4096;
+/** What the `mcp_servers` section needs of a server. */
+export interface McpServerListing {
+    entry: McpServerEntry;
+    connection?: {
+        instructions?: string;
+    };
+}
+/**
+ * The `mcp_servers` section: every enabled server with codemode or deferred tools, with how its
+ * tools are reached and a one-line summary. The model learns of the servers from it, since neither
+ * codemode nor tool_search lists them. Undefined when there are no such servers.
+ */
+export declare function renderServersSection(servers: readonly McpServerListing[]): string | undefined;
 export declare function createMcpExtension(options?: McpExtensionOptions): ExtensionFactory;
 declare const _default: ExtensionFactory;
 export default _default;

package/dist/extensions/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,KAAK,EAGX,gBAAgB,EAChB,gBAAgB,EAEhB,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EAEN,KAAK,eAAe,EAGpB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EAEnB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,uBAAuB,EAAmB,MAAM,YAAY,CAAC;AAI3E,OAAO,KAAK,EAAqC,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAI3F,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,WAAW,mBAAmB;IACnC,uFAAuF;IACvF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,eAAe,CAAC;IACxD,qFAAqF;IACrF,eAAe,CAAC,EAAE,mBAAmB,CAAC;IACtC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,4FAA4F;IAC5F,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC5E;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAqFD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,gBAAgB,CAizBtF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAGX,gBAAgB,EAChB,gBAAgB,EAEhB,MAAM,gCAAgC,CAAC;AAMxC,OAAO,EAEN,KAAK,eAAe,EAGpB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EAEnB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,uBAAuB,EAAmB,MAAM,YAAY,CAAC;AAS3E,OAAO,KAAK,EAAqC,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAI3F,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,WAAW,mBAAmB;IACnC,uFAAuF;IACvF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,eAAe,CAAC;IACxD,qFAAqF;IACrF,eAAe,CAAC,EAAE,mBAAmB,CAAC;IACtC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,4FAA4F;IAC5F,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC5E;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AA4DD,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAGjD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAe9C,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC;AAQD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,GAAG,SAAS,CA0B7F;AA2DD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,gBAAgB,CAs4BtF"}

package/dist/extensions/mcp/index.js

@@ -3,12 +3,15 @@
  *
  * Connects the servers from `mcp.json` and the servers extensions register with
  * `pi.registerMcpServer()` when a session starts, and servers registered later right away. A server
- * in `mcp.json` takes precedence over a registered server of the same name. Tools are registered as
- * `mcp__<server>__<tool>`. By default (`"exposure": "codemode"`) the tools are only callable from
- * codemode scripts, which keeps large MCP tool lists out of the model's tool declarations; the
- * codemode tool is activated for that unless `autoEnableCodemode` is false. `"codemode-deferred"`
- * leaves them out of the codemode description as well. `"deferred"` declares them to the model once
- * the `tool_search` tool loads them, and activates `tool_search` instead of codemode.
+ * in `mcp.json` takes precedence over a registered server of the same name. Connections run in the
+ * background: the first prompt waits only for servers with `direct` tools, and codemode scripts,
+ * `tool_search`, and the resource tools wait for the servers they need when they run. Tools are
+ * registered as `mcp__<server>__<tool>`. By default (`"exposure": "codemode"`) the tools are only
+ * callable from codemode scripts, which keeps MCP tools out of the model's tool declarations and
+ * the codemode description: scripts find the tools with `searchTools()` and the server instructions
+ * with `describeNamespace()`. The codemode tool is activated for that unless `autoEnableCodemode` is
+ * false. `"deferred"` declares the tools to the model once the `tool_search` tool loads them, and
+ * activates `tool_search` instead of codemode.
  * `"exposure": "direct"` declares them to the model right away, and `"hidden"` makes them
  * unreachable. `toolExposure` overrides the exposure of single tools. Servers with resources are
  * reached through Codex's `list_mcp_resources`, `list_mcp_resource_templates`, and
@@ -23,19 +26,25 @@
  * current session for registered servers.
  */
 import { join, resolve } from "node:path";
+import { hyperlink } from "@earendil-works/pi-tui";
 import { getAgentDir } from "../../config.js";
+import { mcpNamespace } from "../../core/mcp-servers.js";
 import { openBrowser } from "../../utils/open-browser.js";
 import { CODEMODE_TOOL_NAME, isCodemodeTool } from "../codemode/tool.js";
 import { isToolSearchTool, TOOL_SEARCH_TOOL_NAME } from "../tool-search/tool.js";
 import { getMcpToolExposure, loadMcpConfig, updateMcpServerConfig, } from "./config.js";
-import { createMcpResourceToolDefinitions } from "./resources.js";
+import { createMcpResourceToolDefinitions, LIST_MCP_RESOURCE_TEMPLATES_TOOL, LIST_MCP_RESOURCES_TOOL, READ_MCP_RESOURCE_TOOL, } from "./resources.js";
 import { loadMcpRuntime } from "./runtime.lazy.js";
 import { createMcpToolDefinition, createMcpToolName } from "./tools.js";
 import { showMcpManager } from "./ui.js";
 const DEFAULT_STARTUP_WAIT_MS = 10_000;
+const RESOURCE_TOOL_NAMES = new Set([
+    LIST_MCP_RESOURCES_TOOL,
+    LIST_MCP_RESOURCE_TEMPLATES_TOOL,
+    READ_MCP_RESOURCE_TOOL,
+]);
 const EXPOSURE_DESCRIPTIONS = {
-    codemode: "called from codemode scripts, listed in the codemode description",
-    "codemode-deferred": "called from codemode scripts, not listed; scripts find them with searchTools()",
+    codemode: "called from codemode scripts, which find them with searchTools()",
     deferred: "not declared until tool_search loads them, then called directly; no codemode needed",
     direct: "declared to the model like built-in tools",
 };
@@ -51,6 +60,86 @@ function isEnabled(server) {
 function exposureOf(entry) {
     return entry.config.exposure ?? "codemode";
 }
+/** Exposures the server's tools can have, known from its config before it connects. */
+function configuredExposures(entry) {
+    return new Set([exposureOf(entry), ...Object.values(entry.config.toolExposure ?? {})]);
+}
+/** Whether some of the server's tools are declared to the model, so the first prompt waits for them. */
+function hasDirectTools(entry) {
+    return configuredExposures(entry).has("direct");
+}
+/** Whether some of the server's tools are reached through codemode or tool_search. */
+function hasIndirectTools(entry) {
+    const exposures = configuredExposures(entry);
+    return exposures.has("codemode") || exposures.has("deferred");
+}
+/** Name of the system prompt section that lists the servers whose tools are not declared. */
+export const MCP_SERVERS_SECTION = "mcp_servers";
+/** Characters of a server description in the section, as Codex allows for deferred namespaces. */
+const MAX_SERVER_DESCRIPTION_CHARS = 250;
+/**
+ * Characters of the whole section. Descriptions shrink to fit; when the server lines alone do not
+ * fit, the last servers are left out and counted in a closing line.
+ */
+export const MAX_SERVERS_SECTION_CHARS = 4096;
+/** The section's first line. It explains only the ways of reaching tools that the listed servers use. */
+function serversSectionIntro(reaches) {
+    let intro = "MCP servers whose tools are not declared to you.";
+    if (reaches.has("codemode"))
+        intro += " Call the tools of `codemode` servers from codemode scripts.";
+    if (reaches.has("tool_search"))
+        intro += " Load the tools of `tool_search` servers with `tool_search`.";
+    return intro;
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return max <= 1 ? "" : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+/** First line of the configured description, or of the server instructions once connected. */
+function serverSummary(server) {
+    const text = server.entry.config.description?.trim() || server.connection?.instructions || "";
+    return (text.split("\n", 1)[0] ?? "").trim();
+}
+/**
+ * The `mcp_servers` section: every enabled server with codemode or deferred tools, with how its
+ * tools are reached and a one-line summary. The model learns of the servers from it, since neither
+ * codemode nor tool_search lists them. Undefined when there are no such servers.
+ */
+export function renderServersSection(servers) {
+    const listed = servers
+        .filter((server) => isEnabled(server) && hasIndirectTools(server.entry))
+        .sort((a, b) => a.entry.name.localeCompare(b.entry.name));
+    if (listed.length === 0)
+        return undefined;
+    const reaches = listed.map((server) => configuredExposures(server.entry).has("codemode") ? "codemode" : "tool_search");
+    const intro = serversSectionIntro(new Set(reaches));
+    const heads = listed.map((server, index) => `- ${mcpNamespace(server.entry.name)} (${reaches[index]})`);
+    const omitted = (count) => count > 0 ? [`- … ${count} more server${count === 1 ? "" : "s"}; find their tools with searchTools()`] : [];
+    // Characters of the intro, the first `kept` server lines without descriptions, and the omission line.
+    const size = (kept) => [intro, ...heads.slice(0, kept), ...omitted(listed.length - kept)].join("\n").length;
+    let kept = listed.length;
+    while (kept > 0 && size(kept) > MAX_SERVERS_SECTION_CHARS)
+        kept--;
+    // Each description also takes a ": " separator.
+    const perServer = kept === 0
+        ? 0
+        : Math.min(MAX_SERVER_DESCRIPTION_CHARS, Math.floor((MAX_SERVERS_SECTION_CHARS - size(kept)) / kept) - 2);
+    const lines = listed.slice(0, kept).map((server, index) => {
+        const summary = perServer > 0 ? truncate(serverSummary(server), perServer) : "";
+        return summary ? `${heads[index]}: ${summary}` : heads[index];
+    });
+    return [intro, ...lines, ...omitted(listed.length - kept)].join("\n");
+}
+/**
+ * Whether a codemode script needs the server: it names the server's namespace, or searches,
+ * enumerates, or describes tools or namespaces, which may name the server in other forms.
+ */
+function scriptNeedsServer(code, server) {
+    if (/\b(searchTools|describeNamespace|describeTool|ALL_TOOLS)\b/.test(code))
+        return true;
+    return code.includes(mcpNamespace(server));
+}
 /** Short state for lists and the startup report. `withError` appends the first line of a failure. */
 function describeState(server, withError = true) {
     if (!isEnabled(server))
@@ -121,6 +210,8 @@ export function createMcpExtension(options = {}) {
         /** Working directory of the session, for stdio servers. */
         let sessionCwd = process.cwd();
         let credentials = options.credentials;
+        /** The session's model registry, which resolves `auth.provider` tokens. */
+        let modelRegistry;
         let serverLog;
         const openUrl = options.openUrl ?? openBrowser;
         const updateConfig = options.updateConfig ?? ((entry, patch) => updateMcpServerConfig(entry.source, entry.name, patch));
@@ -142,9 +233,9 @@ export function createMcpExtension(options = {}) {
             const registered = [];
             const overriddenNames = [];
             for (const { name, config, extensionPath } of pi.getMcpServers()) {
-                const configured = configuredEntries.find((entry) => entry.name === name);
+                const configured = configuredEntries.find((entry) => mcpNamespace(entry.name) === mcpNamespace(name));
                 if (configured) {
-                    overriddenNames.push(`"${name}" registered by ${extensionPath} is overridden by ${configured.source}`);
+                    overriddenNames.push(`"${name}" registered by ${extensionPath} is overridden by "${configured.name}" in ${configured.source}`);
                     continue;
                 }
                 registered.push({
@@ -171,17 +262,23 @@ export function createMcpExtension(options = {}) {
         const registerTools = (connection) => {
             const server = connection.entry.name;
             const entry = findServer(server)?.entry ?? connection.entry;
-            const namespaceName = `mcp__${server}`;
+            const description = entry.config.description?.trim();
             const namespace = {
-                name: namespaceName,
-                description: connection.instructions ?? `Tools in the ${namespaceName} namespace.`,
+                name: mcpNamespace(server),
+                ...(description ? { description } : {}),
+                ...(connection.instructions ? { instructions: connection.instructions } : {}),
             };
             const previous = serverTools.get(server) ?? new Set();
             const current = new Set();
+            // Like Codex, all tools whose names sanitize to the same name get the hash suffix, so which
+            // one would keep the plain name does not depend on the order of the list.
+            const plain = [...new Set(connection.tools.map((tool) => tool.name))].map((tool) => createMcpToolName(server, tool));
             const assignName = (tool, owner) => {
                 const name = createMcpToolName(server, tool, (candidate) => {
                     const existing = toolOwners.get(candidate);
-                    return (existing !== undefined && existing !== owner) || current.has(candidate);
+                    return ((existing !== undefined && existing !== owner) ||
+                        current.has(candidate) ||
+                        plain.indexOf(candidate) !== plain.lastIndexOf(candidate));
                 });
                 toolOwners.set(name, owner);
                 current.add(name);
@@ -232,7 +329,7 @@ export function createMcpExtension(options = {}) {
          */
         const syncResourceTools = () => {
             const exposures = new Set(serversWithResources().map((server) => exposureOf(server.entry)));
-            const exposure = ["direct", "codemode", "codemode-deferred", "deferred"].find((candidate) => exposures.has(candidate));
+            const exposure = ["direct", "codemode", "deferred"].find((candidate) => exposures.has(candidate));
             const next = exposure ?? "hidden";
             if (next === resourceToolsExposure || (resourceToolsExposure === undefined && next === "hidden"))
                 return;
@@ -249,21 +346,19 @@ export function createMcpExtension(options = {}) {
         /**
          * Tools that are not declared to the model are reached through the codemode tool (scripts call
          * them) or the tool_search tool (it declares them). Either reaches every such tool. Activate the
-         * one the tools' exposure asks for: codemode for `codemode` and `codemode-deferred` unless
-         * `autoEnableCodemode` is false, tool_search for `deferred`.
+         * one the tools' exposure asks for: codemode for `codemode` unless `autoEnableCodemode` is false,
+         * tool_search for `deferred`.
          */
         const ensureDiscoveryActive = (ctx) => {
+            // From the config, so the tool is active before the servers connect. Resource tools share
+            // their server's exposure.
             const exposures = new Set();
-            for (const { connection, entry } of servers) {
-                if (connection?.state !== "connected")
-                    continue;
-                // Resource tools share the server's exposure.
-                if (connection.hasResources)
-                    exposures.add(exposureOf(entry));
-                for (const tool of connection.tools)
-                    exposures.add(getMcpToolExposure(entry.config, tool.name));
+            for (const server of servers) {
+                if (isEnabled(server))
+                    for (const exposure of configuredExposures(server.entry))
+                        exposures.add(exposure);
             }
-            const needsCodemode = exposures.has("codemode") || exposures.has("codemode-deferred");
+            const needsCodemode = exposures.has("codemode");
             const needsToolSearch = exposures.has("deferred");
             if (!needsCodemode && !needsToolSearch)
                 return;
@@ -299,7 +394,7 @@ export function createMcpExtension(options = {}) {
         const tokensAtSignIn = new Map();
         const storedTokens = (connection) => {
             const url = connection.oauthUrl;
-            return url && credentials ? JSON.stringify(credentials.tokens(url) ?? null) : "null";
+            return url && credentials ? JSON.stringify(credentials.tokens(connection.name, url) ?? null) : "null";
         };
         const onConnectionChange = (connection) => {
             if (connection.state !== "needs-auth")
@@ -326,6 +421,7 @@ export function createMcpExtension(options = {}) {
                 cwd: sessionCwd,
                 createTransport: options.createTransport ?? runtime.createDefaultTransport,
                 credentials: getCredentials(runtime),
+                providerToken: async (provider) => modelRegistry?.getApiKeyForProvider(provider),
                 log: getServerLog(runtime),
                 onTools: registerTools,
                 onChange: onConnectionChange,
@@ -334,6 +430,40 @@ export function createMcpExtension(options = {}) {
             emitChange();
             return connection;
         };
+        /**
+         * Connect the server in the background. `server.ready` settles when it connected or failed;
+         * failures show in its state. It starts after `after`; `isCurrent` stops it when the session ended
+         * meanwhile. The returned promise rejects when the MCP runtime cannot be loaded.
+         */
+        const startConnection = (server, isCurrent, after) => {
+            const ready = (async () => {
+                await after;
+                if (!isCurrent())
+                    return;
+                const connection = await createConnection(server);
+                if (!isCurrent())
+                    return;
+                await connection.getClient().catch(() => undefined);
+            })();
+            server.ready = ready.catch(() => undefined);
+            return ready;
+        };
+        /** Wait for servers still connecting, until they settle or `signal` aborts. */
+        const waitForServers = async (waiting, signal) => {
+            const ready = waiting.flatMap((server) => (server.ready ? [server.ready] : []));
+            if (ready.length === 0 || signal?.aborted)
+                return;
+            let onAbort;
+            await Promise.race([
+                Promise.all(ready),
+                new Promise((resolve) => {
+                    onAbort = () => resolve();
+                    signal?.addEventListener("abort", onAbort, { once: true });
+                }),
+            ]);
+            if (onAbort)
+                signal?.removeEventListener("abort", onAbort);
+        };
         /**
          * One message for everything that needs the user after startup, or only for `only`, servers
          * that connected later.
@@ -374,7 +504,7 @@ export function createMcpExtension(options = {}) {
             try {
                 await runtime.signInMcpServer({
                     serverUrl: url,
-                    store: getCredentials(runtime).forServer(url),
+                    store: getCredentials(runtime).forServer(server.entry.name, url),
                     settings: connection.oauthSettings(),
                     challenge: connection.challenge,
                     prompt,
@@ -400,7 +530,7 @@ export function createMcpExtension(options = {}) {
             const url = connection?.oauthUrl;
             if (!connection || !url)
                 return false;
-            const removed = getCredentials(await loadMcpRuntime()).remove(url);
+            const removed = getCredentials(await loadMcpRuntime()).remove(server.entry.name, url);
             await connection.signOut();
             return removed;
         };
@@ -429,8 +559,7 @@ export function createMcpExtension(options = {}) {
                 await connection?.close();
                 return undefined;
             }
-            const connection = await createConnection(server);
-            await connection.getClient().catch(() => undefined);
+            await startConnection(server, () => true);
             return undefined;
         };
         const setExposure = (server, exposure) => {
@@ -692,7 +821,11 @@ export function createMcpExtension(options = {}) {
             }
             const failure = await signIn(server, {
                 showAuthorizationUrl: (url) => {
-                    ctx.ui.notify(`Sign in to MCP server "${name}" in your browser:\n${url.href}`, "info");
+                    // Long URLs wrap, which some terminals cannot open; a short link line stays on one line.
+                    const lines = ctx.mode === "tui"
+                        ? `${hyperlink(url.href, url.href)}\n${hyperlink(process.platform === "darwin" ? "Cmd+click to open" : "Ctrl+click to open", url.href)}`
+                        : url.href;
+                    ctx.ui.notify(`Sign in to MCP server "${name}" in your browser:\n${lines}`, "info");
                     openUrl(url.href);
                 },
                 promptForRedirectUrl: (signal) => ctx.ui.input(`Waiting for sign-in to "${name}". If the browser cannot reach this machine, paste the URL it was redirected to.`, "http://127.0.0.1:.../callback?code=...", { signal }),
@@ -711,6 +844,7 @@ export function createMcpExtension(options = {}) {
             warnedUnreachable = false;
             waitedForStartup = false;
             sessionCwd = ctx.cwd;
+            modelRegistry = ctx.modelRegistry;
             const current = ++generation;
             sessionActive = true;
             configuredEntries = loaded.servers;
@@ -718,6 +852,9 @@ export function createMcpExtension(options = {}) {
             overridden = registered.overridden;
             servers = [...loaded.servers.map((entry) => ({ entry })), ...registered.servers];
             emitChange();
+            // Codemode or tool_search is activated from the config: the first prompt does not wait for
+            // servers whose tools are not declared to the model, and scripts or searches wait for them.
+            ensureDiscoveryActive(ctx);
             const enabled = servers.filter(isEnabled);
             if (enabled.length === 0) {
                 reportProblems(ctx);
@@ -725,19 +862,12 @@ export function createMcpExtension(options = {}) {
             }
             // The MCP client loads only now, so sessions without servers never pay for it. Waiting one
             // event loop turn lets the first render happen before loading and connecting.
-            pending = new Promise((resolve) => setImmediate(resolve))
-                .then(() => loadMcpRuntime())
-                .then(async () => {
-                if (current !== generation)
-                    return;
-                const started = await Promise.all(enabled.map((server) => createConnection(server)));
-                if (current !== generation)
-                    return;
-                await Promise.allSettled(started.map((connection) => connection.getClient()));
-                if (current !== generation)
-                    return;
-                ensureDiscoveryActive(ctx);
-                reportProblems(ctx);
+            const runtime = new Promise((resolve) => setImmediate(resolve)).then(() => loadMcpRuntime());
+            const isCurrent = () => current === generation;
+            pending = Promise.all(enabled.map((server) => startConnection(server, isCurrent, runtime)))
+                .then(() => {
+                if (isCurrent())
+                    reportProblems(ctx);
             })
                 .catch((error) => {
                 // The session may have been disposed meanwhile, which makes ctx stale.
@@ -747,16 +877,19 @@ export function createMcpExtension(options = {}) {
                 catch { }
             });
         });
-        // The first prompt waits for startup connections so their tools are available to it, but not
-        // indefinitely: a slow or hanging server must not hold up the prompt.
-        pi.on("before_agent_start", async (_event, ctx) => {
-            const startup = pending;
-            if (!startup || waitedForStartup)
+        // The first prompt waits for servers whose tools are declared to the model, so they are declared
+        // in its first request, but not indefinitely: a slow or hanging server must not hold up the
+        // prompt. Other servers are waited for when a script or search needs them (below).
+        const waitForDirectServers = async (ctx) => {
+            if (waitedForStartup)
                 return;
             waitedForStartup = true;
+            const ready = servers.flatMap((server) => isEnabled(server) && hasDirectTools(server.entry) && server.ready ? [server.ready] : []);
+            if (ready.length === 0)
+                return;
             let timer;
             const finished = await Promise.race([
-                startup.then(() => true),
+                Promise.all(ready).then(() => true),
                 new Promise((resolve) => {
                     timer = setTimeout(() => resolve(false), startupWaitMs);
                 }),
@@ -765,6 +898,38 @@ export function createMcpExtension(options = {}) {
             if (!finished) {
                 ctx.ui.notify("MCP servers are still connecting; their tools become available once connected.", "info");
             }
+        };
+        // Every prompt lists the servers in the `mcp_servers` section as they are when it starts. Pi
+        // appends the section to the conversation when it changed, for example after a server connected.
+        pi.on("before_agent_start", async (event, ctx) => {
+            await waitForDirectServers(ctx);
+            const { sections } = event.systemPromptOptions;
+            const section = renderServersSection(servers);
+            if (section)
+                sections[MCP_SERVERS_SECTION] = section;
+            else
+                delete sections[MCP_SERVERS_SECTION];
+        });
+        // A codemode script waits for the servers it names, or for every server when it searches or
+        // enumerates tools, so their tools are registered before the script runs. tool_search and the
+        // resource tools reach every server, so they wait for all of them.
+        pi.on("tool_call", async (event, ctx) => {
+            const tool = pi.getAllTools().find((candidate) => candidate.name === event.toolName);
+            if (!tool)
+                return;
+            const pendingServers = servers.filter((server) => isEnabled(server) && server.connection?.state !== "connected" && server.ready);
+            if (pendingServers.length === 0)
+                return;
+            let waiting = [];
+            if (isCodemodeTool(tool)) {
+                const { code } = event.input;
+                const source = typeof code === "string" ? code : "";
+                waiting = pendingServers.filter((server) => scriptNeedsServer(source, server.entry.name));
+            }
+            else if (isToolSearchTool(tool) || RESOURCE_TOOL_NAMES.has(tool.name)) {
+                waiting = pendingServers;
+            }
+            await waitForServers(waiting, ctx.signal);
         });
         // Pick up sign-ins done outside the session, such as `pi mcp login` run by the agent.
         pi.on("turn_start", async (_event, ctx) => {
@@ -788,17 +953,17 @@ export function createMcpExtension(options = {}) {
             const added = registered.servers.filter((server) => !findServer(server.entry.name));
             servers.push(...added);
             emitChange();
+            ensureDiscoveryActive(ctx);
             await Promise.all(removed.map((server) => server.connection?.close()));
             const connecting = added.filter(isEnabled);
             if (current !== generation || connecting.length === 0)
                 return;
             try {
-                const started = await Promise.all(connecting.map((server) => createConnection(server)));
+                await Promise.all(connecting.map((server) => startConnection(server, () => current === generation)));
                 if (current !== generation) {
-                    await Promise.all(started.map((connection) => connection.close()));
+                    await Promise.all(connecting.map((server) => server.connection?.close()));
                     return;
                 }
-                await Promise.allSettled(started.map((connection) => connection.getClient()));
             }
             catch (error) {
                 ctx.ui.notify(`MCP failed to load: ${errorMessage(error)}`, "error");
@@ -806,7 +971,6 @@ export function createMcpExtension(options = {}) {
             }
             if (current !== generation)
                 return;
-            ensureDiscoveryActive(ctx);
             reportProblems(ctx, connecting);
         });
         pi.on("session_shutdown", async () => {