@astralyn/pi 0.99.0 → 1.0.1

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
@@ -24,18 +27,23 @@
  */
 import { join, resolve } from "node:path";
 import { getAgentDir } from "../../config.js";
+import { mcpNamespace } from "../../core/mcp-servers.js";
 import { openBrowser } from "../../utils/open-browser.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 { createMcpToolDefinition, createMcpToolName, createMcpToolRenderers } from "./tools.js";
 import { showMcpManager } from "./ui.js";
 const DEFAULT_STARTUP_WAIT_MS = 10_000;
 const CODEMODE_TOOL_NAME = "codemode";
 const TOOL_SEARCH_TOOL_NAME = "tool_search";
+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 +59,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))
@@ -105,6 +193,8 @@ export function createMcpExtension(options = {}) {
         /** Servers from `mcp.json`, which take precedence over registered servers of the same name. */
         let configuredEntries = [];
         let configErrors = [];
+        /** The trusted project's `mcp.json`, where `/mcp` saves project overrides of global servers. */
+        let projectConfig;
         /** Registered servers that `mcp.json` overrides, shown in `/mcp`. */
         let overridden = [];
         /** Between session_start and session_shutdown. Registrations before that are read on session_start. */
@@ -121,9 +211,14 @@ 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));
+        const updateConfig = options.updateConfig ??
+            ((entry, patch) => updateMcpServerConfig(entry.override ?? entry.source, entry.name, patch, {
+                override: entry.override !== undefined,
+            }));
         const listeners = new Set();
         const emitChange = () => {
             for (const listener of listeners)
@@ -142,9 +237,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({
@@ -168,20 +263,31 @@ export function createMcpExtension(options = {}) {
         const serverTools = new Map();
         /** Last definition registered under each tool name, to re-register withdrawn tools as hidden. */
         const definitions = new Map();
+        // A resumed session renders calls to MCP tools before their server connected, if it ever does.
+        pi.registerToolRenderer((toolName, next) => {
+            const match = /^mcp__(.+?)__(.+)$/.exec(toolName);
+            return next() ?? (match ? createMcpToolRenderers(`${match[1]}/${match[2]}`) : undefined);
+        });
         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 +338,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;
@@ -246,33 +352,40 @@ export function createMcpExtension(options = {}) {
                 pi.setActiveTools(pi.getActiveTools().filter((name) => !names.has(name)));
             }
         };
+        /**
+         * Which of the tools are the bundled codemode and tool_search tools. Other extensions' tools of
+         * the same names cannot reach MCP tools. The owning extensions identify their tools through the
+         * event bus, so this extension does not import their internals.
+         */
+        const discoverOrchestrators = (tools) => {
+            const candidates = new Map(tools.map((tool) => [tool.name, tool.parameters]));
+            pi.events.emit("pi:discover-tool-orchestrators", candidates);
+            return {
+                codemode: candidates.get(CODEMODE_TOOL_NAME) === true,
+                toolSearch: candidates.get(TOOL_SEARCH_TOOL_NAME) === true,
+            };
+        };
         /**
          * 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;
             // Other extensions' tools of the same names cannot reach MCP tools, so never activate them.
-            const tools = pi.getAllTools();
-            const candidates = new Map(tools.map((tool) => [tool.name, tool.parameters]));
-            pi.events.emit("pi:discover-tool-orchestrators", candidates);
-            const hasCodemode = candidates.get(CODEMODE_TOOL_NAME) === true;
-            const hasToolSearch = candidates.get(TOOL_SEARCH_TOOL_NAME) === true;
+            const { codemode: hasCodemode, toolSearch: hasToolSearch } = discoverOrchestrators(pi.getAllTools());
             const active = pi.getActiveTools();
             const activate = [];
             if (needsCodemode && hasCodemode && autoEnableCodemode && !active.includes(CODEMODE_TOOL_NAME)) {
@@ -301,7 +414,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")
@@ -328,6 +441,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,
@@ -336,6 +450,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.
@@ -353,18 +501,20 @@ export function createMcpExtension(options = {}) {
         };
         /**
          * Save a config change; returns an error message when the file could not be updated. Changes to
-         * registered servers only apply to the current session.
+         * registered servers only apply to the current session. `inProject` adds a project override.
          */
-        const saveConfig = (server, patch) => {
-            if (server.entry.scope !== "extension") {
+        const saveConfig = (server, patch, inProject = false) => {
+            const override = inProject ? projectConfig : server.entry.override;
+            const entry = override ? { ...server.entry, override } : server.entry;
+            if (entry.scope !== "extension") {
                 try {
-                    updateConfig(server.entry, patch);
+                    updateConfig(entry, patch);
                 }
                 catch (error) {
-                    return `Could not update ${server.entry.source}: ${errorMessage(error)}`;
+                    return `Could not update ${entry.override ?? entry.source}: ${errorMessage(error)}`;
                 }
             }
-            server.entry = { ...server.entry, config: { ...server.entry.config, ...patch } };
+            server.entry = { ...entry, config: { ...entry.config, ...patch } };
             return undefined;
         };
         const signIn = async (server, prompt) => {
@@ -376,7 +526,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,
@@ -402,7 +552,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;
         };
@@ -419,8 +569,8 @@ export function createMcpExtension(options = {}) {
             }
         };
         /** Returns an error message when the config could not be saved; connection errors show in the state. */
-        const setEnabled = async (server, enabled) => {
-            const failed = saveConfig(server, { enabled });
+        const setEnabled = async (server, enabled, inProject = false) => {
+            const failed = saveConfig(server, { enabled }, inProject);
             if (failed)
                 return failed;
             if (!enabled) {
@@ -431,8 +581,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) => {
@@ -467,7 +616,7 @@ export function createMcpExtension(options = {}) {
                 .map((server) => ({
                 value: server.entry.name,
                 label: server.entry.name,
-                description: `${describeState(server)} · ${exposureOf(server.entry)} · ${server.entry.scope ?? server.entry.source}`,
+                description: `${describeState(server)} · ${exposureOf(server.entry)} · ${server.entry.override ? "global, project override" : (server.entry.scope ?? server.entry.source)}`,
             })),
             empty: `No MCP servers configured. Add them to ${resolve(getAgentDir(), "mcp.json")} or .pi/mcp.json.`,
             confirmLabel: "manage",
@@ -487,12 +636,20 @@ export function createMcpExtension(options = {}) {
             const { entry, connection } = server;
             const saved = entry.scope === "extension"
                 ? "for this session"
-                : entry.scope
-                    ? `saved to the ${entry.scope} mcp.json`
-                    : "saved to mcp.json";
+                : entry.override
+                    ? "saved to the project mcp.json"
+                    : entry.scope
+                        ? `saved to the ${entry.scope} mcp.json`
+                        : "saved to mcp.json";
+            // Global servers without an override can be turned on or off for the trusted project alone.
+            const inProject = entry.scope === "global" && !entry.override && projectConfig !== undefined;
+            const inProjectSaved = "saved to the project mcp.json";
             const items = [];
             if (!isEnabled(server)) {
                 items.push({ value: "enable", label: "Enable", description: saved });
+                if (inProject) {
+                    items.push({ value: "enable-project", label: "Enable in this project", description: inProjectSaved });
+                }
             }
             else {
                 const state = connection?.state;
@@ -509,10 +666,14 @@ export function createMcpExtension(options = {}) {
                 }
                 items.push({ value: "exposure", label: "Exposure", description: exposureOf(entry) });
                 items.push({ value: "disable", label: "Disable", description: saved });
+                if (inProject) {
+                    items.push({ value: "disable-project", label: "Disable in this project", description: inProjectSaved });
+                }
             }
             const details = [
                 describeTransport(entry),
                 `${entry.scope ?? "config"}: ${entry.source}`,
+                ...(entry.override ? [`project override: ${entry.override}`] : []),
                 `State: ${describeState(server, false)}`,
             ];
             const error = [server.message, connection?.state === "connected" ? undefined : connection?.error]
@@ -554,7 +715,7 @@ export function createMcpExtension(options = {}) {
                 title: `Exposure of ${server.entry.name}`,
                 details: server.entry.scope === "extension"
                     ? `Applies to this session; the server is registered by ${server.entry.source}.`
-                    : `Saved to ${server.entry.source}.`,
+                    : `Saved to ${server.entry.override ?? server.entry.source}.`,
                 items: Object.keys(EXPOSURE_DESCRIPTIONS).map((exposure) => ({
                     value: exposure,
                     label: `${exposure === current ? "✓ " : "  "}${exposure}`,
@@ -568,27 +729,30 @@ export function createMcpExtension(options = {}) {
                 return undefined;
             return setExposure(server, choice);
         };
+        /** Sign in with the manager view's sign-in screen, which shows the URL with a copy key. */
+        const signInWithUi = (ui, server) => {
+            const title = `Sign in to ${server.entry.name}`;
+            let authorizationUrl = "";
+            ui.status(title, "Contacting the authorization server…");
+            return signIn(server, {
+                showAuthorizationUrl: (url) => {
+                    authorizationUrl = url.href;
+                    openUrl(url.href);
+                },
+                promptForRedirectUrl: async (signal) => {
+                    const value = await ui.redirectUrl(title, authorizationUrl, signal);
+                    ui.status(title, "Connecting…");
+                    return value;
+                },
+            });
+        };
         const runAction = async (ui, ctx, server, action) => {
             const { name } = server.entry;
             let message;
             switch (action) {
-                case "signin": {
-                    const title = `Sign in to ${name}`;
-                    let authorizationUrl = "";
-                    ui.status(title, "Contacting the authorization server…");
-                    message = await signIn(server, {
-                        showAuthorizationUrl: (url) => {
-                            authorizationUrl = url.href;
-                            openUrl(url.href);
-                        },
-                        promptForRedirectUrl: async (signal) => {
-                            const value = await ui.redirectUrl(title, authorizationUrl, signal);
-                            ui.status(title, "Connecting…");
-                            return value;
-                        },
-                    });
+                case "signin":
+                    message = await signInWithUi(ui, server);
                     break;
-                }
                 case "reconnect":
                     // A failure shows as the connection's state and error.
                     ui.status(`MCP server ${name}`, "Reconnecting…");
@@ -605,9 +769,13 @@ export function createMcpExtension(options = {}) {
                     break;
                 case "enable":
                 case "disable":
-                    ui.status(`MCP server ${name}`, action === "enable" ? "Connecting…" : "Disconnecting…");
-                    message = await setEnabled(server, action === "enable");
+                case "enable-project":
+                case "disable-project": {
+                    const enable = action.startsWith("enable");
+                    ui.status(`MCP server ${name}`, enable ? "Connecting…" : "Disconnecting…");
+                    message = await setEnabled(server, enable, action.endsWith("-project"));
                     break;
+                }
             }
             server.message = message;
             ensureDiscoveryActive(ctx);
@@ -692,13 +860,21 @@ export function createMcpExtension(options = {}) {
                 ctx.ui.notify(`Signing in to MCP server "${name}" requires interactive mode.`, "error");
                 return;
             }
-            const failure = await signIn(server, {
-                showAuthorizationUrl: (url) => {
-                    ctx.ui.notify(`Sign in to MCP server "${name}" in your browser:\n${url.href}`, "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 }),
-            });
+            let failure;
+            if (ctx.mode === "tui") {
+                await showMcpManager(ctx, async (ui) => {
+                    failure = await signInWithUi(ui, server);
+                });
+            }
+            else {
+                failure = await signIn(server, {
+                    showAuthorizationUrl: (url) => {
+                        ctx.ui.notify(`Sign in to MCP server "${name}" in your browser:\n${url.href}`, "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 }),
+                });
+            }
             if (failure) {
                 ctx.ui.notify(failure, failure === "Sign-in cancelled." ? "info" : "error");
                 return;
@@ -709,10 +885,12 @@ export function createMcpExtension(options = {}) {
         pi.on("session_start", (_event, ctx) => {
             const loaded = (options.loadConfig ?? defaultLoadConfig)(ctx);
             configErrors = loaded.errors;
+            projectConfig = loaded.projectConfig;
             autoEnableCodemode = loaded.autoEnableCodemode ?? true;
             warnedUnreachable = false;
             waitedForStartup = false;
             sessionCwd = ctx.cwd;
+            modelRegistry = ctx.modelRegistry;
             const current = ++generation;
             sessionActive = true;
             configuredEntries = loaded.servers;
@@ -720,6 +898,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);
@@ -727,19 +908,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.
@@ -749,16 +923,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);
                 }),
@@ -767,6 +944,39 @@ 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 = [];
+            const orchestrator = discoverOrchestrators([tool]);
+            if (orchestrator.codemode) {
+                const { code } = event.input;
+                const source = typeof code === "string" ? code : "";
+                waiting = pendingServers.filter((server) => scriptNeedsServer(source, server.entry.name));
+            }
+            else if (orchestrator.toolSearch || 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) => {
@@ -790,17 +1000,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");
@@ -808,7 +1018,6 @@ export function createMcpExtension(options = {}) {
             }
             if (current !== generation)
                 return;
-            ensureDiscoveryActive(ctx);
             reportProblems(ctx, connecting);
         });
         pi.on("session_shutdown", async () => {