pi-mcp-client 0.1.0 → 0.3.0

package/dist/index.js

@@ -30,7 +30,7 @@ function diagnostic(code, context) {
     cancelled: "Start the operation again when ready.",
     connection_failed: `Check the URL or executable, working directory, network, and TLS setup; then run /mcp reconnect ${target}.`,
     protocol_error: "Check the server's MCP compatibility and protocol setting. Only stdio and Streamable HTTP are supported.",
-    tool_changed: "Check server filters and run mcp_search again to load the current tool definition. Reload Pi if the connection configuration changed.",
+    tool_changed: "Check server filters and use mcp_tools with activate and the exact identifier to activate the current tool definition. Reload Pi if the connection configuration changed.",
     tool_error: "Review the server's tool result and inputs. Verify the outcome before retrying.",
     oauth_failed: `Check OAuth support and browser access to the local callback, then run /mcp auth ${target}.`,
     callback_unavailable: "Free local port 19847, then retry authentication.",
@@ -285,12 +285,14 @@ __export(config_exports, {
   matches: () => matches,
   object: () => object,
   parseConfig: () => parseConfig,
-  resolveServer: () => resolveServer
+  resolveServer: () => resolveServer,
+  setServerDisabled: () => setServerDisabled
 });
-import { readFile } from "node:fs/promises";
+import { chmod, readFile, realpath, stat, writeFile, rename, rm } from "node:fs/promises";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { resolve, join } from "node:path";
 import { homedir } from "node:os";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 function object(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -386,6 +388,46 @@ async function loadConfig(agentDir, cwd, trusted) {
   }
   return config;
 }
+async function setServerDisabled(agentDir, cwd, trusted, server, disabled, validate) {
+  const paths = [join(agentDir, "mcp.json"), ...trusted ? [join(cwd, ".mcp.json")] : []];
+  const locks = [...new Set(await Promise.all(
+    paths.map((path) => realpath(path).catch(() => resolve(path)))
+  ))].sort();
+  const locked = async (index) => {
+    if (index < locks.length)
+      return withFileMutationQueue(locks[index], () => locked(index + 1));
+    const documents = await Promise.all(paths.map(readJson));
+    const config = /* @__PURE__ */ Object.create(null);
+    let source = -1;
+    for (const [index2, document2] of documents.entries()) {
+      if (document2 === void 0) continue;
+      const parsed = parseConfig(document2, paths[index2]);
+      Object.assign(config, parsed);
+      if (Object.hasOwn(parsed, server)) source = index2;
+    }
+    if (source < 0) throw new Error("Server is no longer configured. Run /mcp reload.");
+    const changed = Boolean(config[server].disabled) !== disabled;
+    if (changed) config[server].disabled = disabled;
+    validate(config);
+    const document = documents[source];
+    if (changed) {
+      document.mcpServers[server].disabled = disabled;
+      const target = await realpath(paths[source]);
+      const mode = (await stat(target)).mode & 511;
+      const temporary = `${target}.${randomUUID()}.tmp`;
+      try {
+        await writeFile(temporary, JSON.stringify(document, null, 2) + "\n", { mode: 384, flag: "wx" });
+        await chmod(temporary, mode);
+        validate(config);
+        await rename(temporary, target);
+      } finally {
+        await rm(temporary, { force: true });
+      }
+    }
+    return { config, scope: source === 0 ? "global" : "project" };
+  };
+  return locked(0);
+}
 function interpolate(value, env = process.env) {
   return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
     const found = env[name];
@@ -547,9 +589,9 @@ var recurse = (node, query, maxDistance, results, matrix, m, n, prefix) => {
   const offset = m * n;
   key: for (const key of node.keys()) {
     if (key === LEAF) {
-      const distance = matrix[offset - 1];
-      if (distance <= maxDistance) {
-        results.set(prefix, [node.get(key), distance]);
+      const distance2 = matrix[offset - 1];
+      if (distance2 <= maxDistance) {
+        results.set(prefix, [node.get(key), distance2]);
       }
     } else {
       let i = m;
@@ -1903,22 +1945,22 @@ var MiniSearch = class _MiniSearch {
     }
     if (prefixMatches) {
       for (const [term, data2] of prefixMatches) {
-        const distance = term.length - query.term.length;
-        if (!distance) {
+        const distance2 = term.length - query.term.length;
+        if (!distance2) {
           continue;
         }
         fuzzyMatches === null || fuzzyMatches === void 0 ? void 0 : fuzzyMatches.delete(term);
-        const weight = prefixWeight * term.length / (term.length + 0.3 * distance);
+        const weight = prefixWeight * term.length / (term.length + 0.3 * distance2);
         this.termResults(query.term, term, weight, query.termBoost, data2, boosts, boostDocument, bm25params, results);
       }
     }
     if (fuzzyMatches) {
       for (const term of fuzzyMatches.keys()) {
-        const [data2, distance] = fuzzyMatches.get(term);
-        if (!distance) {
+        const [data2, distance2] = fuzzyMatches.get(term);
+        if (!distance2) {
           continue;
         }
-        const weight = fuzzyWeight * term.length / (term.length + distance);
+        const weight = fuzzyWeight * term.length / (term.length + distance2);
         this.termResults(query.term, term, weight, query.termBoost, data2, boosts, boostDocument, bm25params, results);
       }
     }
@@ -2310,6 +2352,41 @@ function prepareTool(server, identity, tool) {
     schemaHash: fingerprint(inputSchema)
   };
 }
+function summarize(tool, includeIdentifier = true) {
+  const schema = tool.inputSchema;
+  const required = Array.isArray(schema.required) ? schema.required.filter((name) => typeof name === "string") : [];
+  const prefix = includeIdentifier ? `${tool.server}.${tool.name} \u2014 ` : "";
+  return `${prefix}${line(tool.description).slice(0, 180)} (required: ${required.map(line).join(", ") || "none"})`;
+}
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 0; i < a.length; i++) {
+    let diagonal = row[0];
+    row[0] = i + 1;
+    for (let j = 0; j < b.length; j++) {
+      const previous = row[j + 1];
+      row[j + 1] = Math.min(row[j] + 1, previous + 1, diagonal + Number(a[i] !== b[j]));
+      diagonal = previous;
+    }
+  }
+  return row[b.length];
+}
+function resolveTools(tools, identifiers) {
+  return [...new Set(identifiers)].map((identifier) => {
+    const matches2 = tools.filter(
+      (tool2) => identifier === tool2.nativeName || identifier === `${tool2.server}.${tool2.name}`
+    );
+    const tool = matches2.length === 1 ? matches2[0] : void 0;
+    const suggestions = tool ? [] : tools.map((candidate) => ({
+      name: `${candidate.server}.${candidate.name}`,
+      score: Math.min(
+        distance(identifier, `${candidate.server}.${candidate.name}`),
+        distance(identifier, candidate.nativeName)
+      )
+    })).sort((a, b) => a.score - b.score || a.name.localeCompare(b.name)).slice(0, 3).map(({ name }) => name);
+    return { identifier, tool, suggestions };
+  });
+}
 var STOP = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -2354,10 +2431,120 @@ function searchTools(tools, query, server, limit = DEFAULT_SEARCH_LIMIT) {
   return index.search(query).sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id))).slice(0, Math.max(1, Math.min(limit, MAX_SEARCH_LIMIT))).map((result) => byName.get(result.id));
 }
 
+// src/management.ts
+init_config();
+import { truncateToWidth } from "@earendil-works/pi-tui";
+var serverStates = {
+  disconnected: { glyph: "\u25CB", label: "idle" },
+  connected: { glyph: "\u25CF", label: "connected" },
+  connecting: { glyph: "\u25B6\uFE0E", label: "connecting" },
+  failed: { glyph: "\u2718\uFE0E", label: "error" },
+  disabled: { glyph: "\u25CB", label: "disabled" }
+};
+function serverMatrix(servers, loaded, width = 80) {
+  if (width <= 0) return "";
+  const fit = (text) => plain(truncateToWidth(text, width));
+  if (!servers.length) return fit("No MCP servers configured.");
+  const nameWidth = Math.min(40, Math.max(6, ...servers.map(({ name }) => name.length)));
+  const heading = `  ${"Server".padEnd(nameWidth)}  ${"State".padEnd(10)}  ${"Tools".padStart(5)}  ${"Loaded".padStart(6)}`;
+  const rows = servers.map((server) => {
+    const state = serverStates[server.state];
+    const name = plain(truncateToWidth(line(server.name), nameWidth)).padEnd(nameWidth);
+    return `${state.glyph} ${name}  ${state.label.padEnd(10)}  ${String(server.catalogSize ?? "\u2014").padStart(5)}  ${String(loaded.get(server.name) ?? 0).padStart(6)}`;
+  });
+  const errors = servers.filter((server) => server.state === "failed" && server.error).map((server) => `\u2718\uFE0E ${line(server.name)}: [${server.error.code}] ${line(server.error.message)}`);
+  return [
+    heading,
+    ...rows,
+    "",
+    "Connections open on demand. \u2014 = catalog not fetched.",
+    ...errors
+  ].map(fit).join("\n");
+}
+function toolPickerLabel(tool, index, columns = 80) {
+  const width = Math.max(0, columns - 4);
+  const text = `${index + 1}. ${line(tool.name)}: ${line(tool.description) || "No description."}`;
+  return plain(truncateToWidth(text, width, "\u2026"));
+}
+function schemaType(schema, depth = 0) {
+  if (!object(schema) || depth > 2) return "unknown";
+  const alternatives = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(alternatives)) {
+    if (alternatives.length > 4) return "union";
+    return [...new Set(alternatives.map((part) => schemaType(part, depth + 1)))].join(" | ") || "unknown";
+  }
+  if (schema.$ref || schema.allOf) return "unknown";
+  const type = schema.type;
+  if (Array.isArray(type))
+    return type.slice(0, 4).map((part) => schemaType({ ...schema, type: part }, depth + 1)).join(" | ");
+  if (type === "array") return `Array<${schemaType(schema.items, depth + 1)}>`;
+  if (type === "integer") return "integer";
+  if (["string", "number", "boolean", "object", "null"].includes(String(type))) return String(type);
+  return "unknown";
+}
+function toolParameters(tool) {
+  const schema = tool.inputSchema;
+  if (!object(schema)) return [];
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  return Object.entries(object(schema.properties) ? schema.properties : {}).map(([name, value]) => ({
+    name: line(name).slice(0, 80),
+    required: required.has(name),
+    type: schemaType(value),
+    description: object(value) && typeof value.description === "string" ? line(value.description) : ""
+  }));
+}
+function toolSignature(tool, limit = 40) {
+  const parameters = toolParameters(tool);
+  const args = parameters.slice(0, limit).map(
+    (parameter) => `${parameter.name}${parameter.required ? "" : "?"}: ${parameter.type}`
+  );
+  if (parameters.length > limit) args.push(`\u2026 +${parameters.length - limit} more`);
+  const schema = tool.inputSchema;
+  if (object(schema) && schema.additionalProperties !== false) args.push("\u2026");
+  const name = line(tool.name).slice(0, 160);
+  return args.length ? `${name}(
+${args.map((arg) => `  ${arg},`).join("\n")}
+)` : `${name}()`;
+}
+function inspectTool(tool) {
+  const parameters = toolParameters(tool);
+  return [
+    toolSignature(tool),
+    line(tool.description) || "No description.",
+    ...parameters.length ? ["Parameters:"] : [],
+    ...parameters.slice(0, 40).map(
+      (parameter) => `${parameter.name}: ${parameter.type} (${parameter.required ? "required" : "optional"})${parameter.description ? `
+${parameter.description}` : ""}`
+    ),
+    ...parameters.length > 40 ? [`\u2026 ${parameters.length - 40} more parameters`] : [],
+    "Types are summaries; the full schema may impose additional constraints."
+  ].join("\n\n");
+}
+function inspectServer(name, config, status) {
+  return [
+    status,
+    `Server: ${name}`,
+    `Transport: ${config.command ? "stdio" : "HTTP"}`,
+    `Protocol: ${config.protocol ?? "auto"}`,
+    `OAuth: ${config.oauth ? "enabled" : "disabled"}`,
+    `Timeout: ${config.timeoutMs ? `${config.timeoutMs} ms` : "default"}`,
+    ...config.command ? [
+      "Command and working directory: hidden",
+      `Arguments: ${config.args?.length ?? 0} (values hidden)`,
+      `Environment overrides: ${Object.keys(config.env ?? {}).length} (names and values hidden)`
+    ] : [
+      "URL: hidden",
+      `Headers: ${Object.keys(config.headers ?? {}).length} (names and values hidden)`
+    ],
+    `Include tools: ${config.includeTools ? config.includeTools.map(line).join(", ") : "all"}`,
+    `Exclude tools: ${config.excludeTools?.map(line).join(", ") || "none"}`
+  ].join("\n");
+}
+
 // src/auth.ts
 init_config();
 init_diagnostics();
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
 import { createServer } from "node:http";
 import {
   auth
@@ -2407,7 +2594,7 @@ var OAuthProvider = class {
   data;
   verifier;
   discovery;
-  expectedState = randomUUID();
+  expectedState = randomUUID2();
   save() {
     this.store.write(JSON.stringify(this.data));
   }
@@ -2531,9 +2718,9 @@ async function authenticate(url, open, signal, store) {
 
 // src/runtime.ts
 init_config();
-import { mkdir, readFile as readFile2, rename, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile as readFile2, rename as rename2, rm as rm2, stat as stat2, writeFile as writeFile2 } from "node:fs/promises";
 import { join as join2 } from "node:path";
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import {
   Client,
   StreamableHTTPClientTransport
@@ -2542,7 +2729,7 @@ import {
   StdioClientTransport,
   getDefaultEnvironment
 } from "@modelcontextprotocol/client/stdio";
-import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue as withFileMutationQueue2 } from "@earendil-works/pi-coding-agent";
 init_secrets();
 init_diagnostics();
 var ToolContractError = class extends Error {
@@ -2565,11 +2752,18 @@ function waitFor(promise, signal) {
     if (signal.aborted) abort();
   });
 }
-var connectSdk = async (_name, config, signal) => {
+var connectSdk = async (_name, config, signal, onToolsChanged) => {
   const timeout = config.timeoutMs ?? 15e3;
   const client = new Client(
     { name: "pi-mcp-client", version: "0.1.0" },
     {
+      listChanged: {
+        tools: {
+          autoRefresh: false,
+          debounceMs: 0,
+          onChanged: () => onToolsChanged?.()
+        }
+      },
       versionNegotiation: {
         mode: config.protocol ?? "auto",
         probe: { timeoutMs: timeout }
@@ -2585,21 +2779,39 @@ var connectSdk = async (_name, config, signal) => {
   }) : new StreamableHTTPClientTransport(new URL(config.url), {
     requestInit: { headers: config.headers },
     authProvider: config.oauth ? new OAuthProvider(config.url, await credentialStore(config.url)) : void 0,
-    // Bound each HTTP request, including OAuth discovery and token refresh.
-    fetch: (input, init) => fetch(input, {
-      ...init,
-      signal: AbortSignal.any([
-        signal,
-        AbortSignal.timeout(timeout),
-        ...init?.signal ? [init.signal] : []
-      ])
-    })
-  });
-  if (transport instanceof StdioClientTransport) transport.stderr?.on("data", () => {
+    // Bound HTTP responses (including OAuth), but not established SSE streams.
+    // The SDK bounds ordinary MCP requests with their request timeout.
+    fetch: async (input, init) => {
+      const deadline = new AbortController();
+      const timer = setTimeout(
+        () => deadline.abort(new Error("HTTP response timed out.")),
+        timeout
+      );
+      timer.unref();
+      try {
+        const response = await fetch(input, {
+          ...init,
+          signal: AbortSignal.any([
+            signal,
+            deadline.signal,
+            ...init?.signal ? [init.signal] : []
+          ])
+        });
+        if (response.headers.get("content-type")?.split(";")[0].trim() === "text/event-stream")
+          clearTimeout(timer);
+        return response;
+      } catch (error) {
+        clearTimeout(timer);
+        throw error;
+      }
+    }
   });
+  if (transport instanceof StdioClientTransport)
+    transport.stderr?.on("data", () => {
+    });
   try {
     await waitFor(
-      client.connect(transport),
+      client.connect(transport, { signal, timeout }),
       AbortSignal.any([signal, AbortSignal.timeout(timeout)])
     );
     signal.throwIfAborted();
@@ -2621,6 +2833,7 @@ var McpRuntime = class {
   }
   states = /* @__PURE__ */ new Map();
   lifetime = new AbortController();
+  closing;
   identity(name) {
     const config = this.definition(name);
     let resolved;
@@ -2643,18 +2856,21 @@ var McpRuntime = class {
   definition(name) {
     const config = Object.hasOwn(this.config, name) ? this.config[name] : void 0;
     if (!config || config.disabled)
-      throw new ToolContractError("MCP server is not configured or is disabled.");
+      throw new ToolContractError(
+        "MCP server is not configured or is disabled."
+      );
     return config;
   }
   state(name) {
     let state = this.states.get(name);
     if (!state) {
-      state = {};
+      state = { catalogGeneration: 0 };
       this.states.set(name, state);
     }
     return state;
   }
   async client(name) {
+    if (this.closing) throw new Error("MCP session ended.");
     this.lifetime.signal.throwIfAborted();
     const state = this.state(name);
     const identity = this.identity(name);
@@ -2666,6 +2882,8 @@ var McpRuntime = class {
     if (state.connecting) return state.connecting;
     const config = resolveServer(this.definition(name), this.cwd);
     state.connectionIdentity = identity;
+    const token = {};
+    state.connectionToken = token;
     state.connecting = (async () => {
       const { client, transport } = await this.connect(
         name,
@@ -2675,9 +2893,28 @@ var McpRuntime = class {
           this.cwd,
           this.lifetime.signal
         ),
-        this.lifetime.signal
+        this.lifetime.signal,
+        () => {
+          if (this.closing || this.lifetime.signal.aborted || state.connectionToken !== token)
+            return;
+          state.catalogGeneration++;
+          state.catalogDirty = true;
+          state.tools = void 0;
+          state.warnings = void 0;
+          const path = join2(this.cacheDir, `${identity}.json`);
+          state.invalidating = withFileMutationQueue2(
+            path,
+            () => rm2(path, { force: true })
+          ).catch(() => {
+            state.warnings = [
+              `${name}: stale catalog cache could not be removed.`
+            ];
+          });
+        }
       );
-      if (this.lifetime.signal.aborted) {
+      if (this.closing || this.lifetime.signal.aborted) {
+        await client.autoOpenedSubscription?.close().catch(() => {
+        });
         await client.close();
         throw new Error("MCP session ended.");
       }
@@ -2688,10 +2925,12 @@ var McpRuntime = class {
         if (state.client === client) {
           state.client = void 0;
           state.transport = void 0;
+          state.connectionToken = void 0;
         }
       };
       return client;
     })().catch((error) => {
+      if (state.connectionToken === token) state.connectionToken = void 0;
       throw new DiagnosticError(
         diagnose(error, {
           server: name,
@@ -2707,10 +2946,13 @@ var McpRuntime = class {
   }
   async catalog(name, signal, refresh = false) {
     signal?.throwIfAborted();
+    if (this.closing) throw new Error("MCP session ended.");
     this.lifetime.signal.throwIfAborted();
     const state = this.state(name);
     const identity = this.identity(name);
-    if (!refresh && state.tools && state.identity === identity) return state.tools;
+    refresh ||= !!state.catalogDirty;
+    if (!refresh && state.tools && state.identity === identity)
+      return state.tools;
     if (refresh && state.listing && !state.listingLive) {
       await waitFor(state.listing, signal);
       return this.catalog(name, signal, true);
@@ -2718,44 +2960,59 @@ var McpRuntime = class {
     if (!state.listing) {
       state.listingLive = refresh;
       state.listing = (async () => {
-        if (!refresh) {
-          const cached = await this.readCache(name, identity);
-          if (cached) {
-            state.tools = cached;
-            state.identity = identity;
-            return cached;
+        for (let attempt = 0; attempt < 3; attempt++) {
+          const generation = state.catalogGeneration;
+          if (!refresh && !state.catalogDirty) {
+            const cached = await this.readCache(name, identity);
+            if (cached && generation === state.catalogGeneration) {
+              state.tools = cached;
+              state.identity = identity;
+              return cached;
+            }
           }
-        }
-        const client = await this.client(name);
-        const listed = await client.listTools(void 0, {
-          signal: this.lifetime.signal,
-          timeout: this.definition(name).timeoutMs ?? 15e3
-        });
-        const tools = [];
-        const warnings = [];
-        const seen = /* @__PURE__ */ new Set();
-        for (const tool of listed.tools) {
-          if (!allowed(tool.name, this.definition(name))) continue;
-          try {
-            const prepared = prepareTool(name, identity, tool);
-            if (seen.has(prepared.nativeName)) throw new Error("Duplicate tool name.");
-            seen.add(prepared.nativeName);
-            tools.push(prepared);
-          } catch {
-            warnings.push(
-              `${name}: skipped an invalid, duplicate, or unsupported tool schema.`
-            );
+          const client = await this.client(name);
+          const listed = await client.listTools(void 0, {
+            signal: this.lifetime.signal,
+            timeout: this.definition(name).timeoutMs ?? 15e3
+          });
+          const tools = [];
+          const warnings = [];
+          const seen = /* @__PURE__ */ new Set();
+          for (const tool of listed.tools) {
+            if (!allowed(tool.name, this.definition(name))) continue;
+            try {
+              const prepared = prepareTool(name, identity, tool);
+              if (seen.has(prepared.nativeName))
+                throw new Error("Duplicate tool name.");
+              seen.add(prepared.nativeName);
+              tools.push(prepared);
+            } catch {
+              warnings.push(
+                `${name}: skipped an invalid, duplicate, or unsupported tool schema.`
+              );
+            }
           }
+          this.lifetime.signal.throwIfAborted();
+          if (generation !== state.catalogGeneration) continue;
+          await state.invalidating;
+          await this.writeCache(
+            identity,
+            tools,
+            () => generation === state.catalogGeneration
+          ).catch(() => {
+            warnings.push(`${name}: catalog cache could not be saved.`);
+          });
+          if (generation !== state.catalogGeneration) continue;
+          state.tools = tools;
+          state.identity = identity;
+          state.catalogDirty = false;
+          state.error = void 0;
+          state.warnings = warnings;
+          return tools;
         }
-        this.lifetime.signal.throwIfAborted();
-        state.tools = tools;
-        state.identity = identity;
-        state.error = void 0;
-        state.warnings = warnings;
-        await this.writeCache(identity, tools).catch(() => {
-          warnings.push(`${name}: catalog cache could not be saved.`);
-        });
-        return tools;
+        throw new ToolContractError(
+          "MCP tool catalog kept changing. Retry discovery or activation."
+        );
       })().catch((error) => {
         state.error = this.failure(name, error);
         throw new DiagnosticError(state.error);
@@ -2767,8 +3024,8 @@ var McpRuntime = class {
     return waitFor(state.listing, signal);
   }
   async discover(server, signal) {
-    if (server) this.definition(server);
-    const names = server ? [server] : Object.keys(this.config).filter((name) => !this.config[name].disabled).sort();
+    if (typeof server === "string") this.definition(server);
+    const names = Array.isArray(server) ? [...new Set(server)] : server ? [server] : Object.keys(this.config).filter((name) => !this.config[name].disabled).sort();
     const result = {
       tools: [],
       unavailable: [],
@@ -2805,14 +3062,17 @@ var McpRuntime = class {
     const found = current.find((candidate) => candidate.name === tool.name);
     if (!found || found.schemaHash !== tool.schemaHash)
       throw new ToolContractError(
-        "MCP tool was removed or its schema changed. Run mcp_search to load its current definition."
+        "MCP tool was removed or its schema changed. Use mcp_tools with activate and its exact identifier to activate its current definition."
       );
     const client = await waitFor(this.client(tool.server), signal);
     try {
       return await client.callTool(
         { name: tool.name, arguments: args },
         {
-          signal: AbortSignal.any([this.lifetime.signal, ...signal ? [signal] : []]),
+          signal: AbortSignal.any([
+            this.lifetime.signal,
+            ...signal ? [signal] : []
+          ]),
           timeout: config.timeoutMs ?? 3e4,
           onprogress: (event) => progress?.(
             event.message ?? `${event.progress}${event.total === void 0 ? "" : `/${event.total}`}`
@@ -2835,18 +3095,38 @@ var McpRuntime = class {
     const state = this.state(name);
     if (state.connecting || state.listing)
       throw failure("busy", { server: name, operation: "reconnect" });
+    await state.client?.autoOpenedSubscription?.close();
     await state.client?.close();
     state.client = void 0;
     await this.catalog(name, void 0, true);
   }
-  status() {
+  serverStatuses() {
     return Object.entries(this.config).map(([name, config]) => {
       const state = this.states.get(name);
-      const status = config.disabled ? "disabled" : state?.connecting || state?.listing ? "connecting" : state?.error ? formatDiagnostic({ ...state.error, server: void 0 }) : state?.client ? "connected" : "disconnected";
-      return `${name}: ${status} \xB7 ${state?.tools?.length ?? "unknown"} catalog tools`;
+      return {
+        name,
+        state: config.disabled ? "disabled" : state?.connecting || state?.listing ? "connecting" : state?.error ? "failed" : state?.client ? "connected" : "disconnected",
+        catalogSize: state?.tools?.length,
+        error: state?.error
+      };
+    });
+  }
+  status(server) {
+    return this.serverStatuses().filter(({ name }) => server === void 0 || name === server).map((row) => {
+      const status = row.state === "failed" && row.error ? formatDiagnostic({ ...row.error, server: void 0 }) : row.state;
+      return `${row.name}: ${status} \xB7 ${row.catalogSize ?? "unknown"} catalog tools`;
     }).join("\n") || "No MCP servers configured.";
   }
-  async close() {
+  close() {
+    return this.closing ??= this.shutdown();
+  }
+  async shutdown() {
+    await Promise.all(
+      [...this.states.values()].map(
+        (state) => state.client?.autoOpenedSubscription?.close().catch(() => {
+        })
+      )
+    );
     this.lifetime.abort(new Error("MCP session ended."));
     await Promise.all(
       [...this.states.values()].map(async (state) => {
@@ -2856,6 +3136,7 @@ var McpRuntime = class {
         });
         await state.listing?.catch(() => {
         });
+        await state.invalidating;
       })
     );
   }
@@ -2870,8 +3151,9 @@ var McpRuntime = class {
   async readCache(name, identity) {
     try {
       const path = join2(this.cacheDir, `${identity}.json`);
-      const info = await stat(path);
-      if (info.size > 4 * 1024 * 1024 || Date.now() - info.mtimeMs > 864e5) return;
+      const info = await stat2(path);
+      if (info.size > 4 * 1024 * 1024 || Date.now() - info.mtimeMs > 864e5)
+        return;
       const data = JSON.parse(await readFile2(path, "utf8"));
       if (!Array.isArray(data) || data.length > 1e4) return;
       return data.filter((tool) => allowed(tool.name, this.definition(name))).map((tool) => prepareTool(name, identity, tool));
@@ -2879,7 +3161,7 @@ var McpRuntime = class {
       return;
     }
   }
-  async writeCache(identity, tools) {
+  async writeCache(identity, tools, isCurrent) {
     const text = JSON.stringify(
       tools.map(({ name, description, inputSchema }) => ({
         name,
@@ -2890,26 +3172,28 @@ var McpRuntime = class {
     if (Buffer.byteLength(text) > 4 * 1024 * 1024) return;
     await mkdir(this.cacheDir, { recursive: true, mode: 448 });
     const path = join2(this.cacheDir, `${identity}.json`);
-    await withFileMutationQueue(path, async () => {
-      const temp = `${path}.${randomUUID2()}.tmp`;
-      await writeFile(temp, text, { mode: 384 });
-      await rename(temp, path);
+    await withFileMutationQueue2(path, async () => {
+      if (!isCurrent()) return;
+      const temp = `${path}.${randomUUID3()}.tmp`;
+      await writeFile2(temp, text, { mode: 384 });
+      if (isCurrent()) await rename2(temp, path);
+      else await rm2(temp, { force: true });
     });
   }
 };
 
 // src/exposure.ts
 init_config();
-var SEARCH_TOOL = "mcp_search";
+var TOOLS_TOOL = "mcp_tools";
 function restoredTools(entries) {
   const tools = /* @__PURE__ */ new Map();
   for (const entry of entries) {
-    if (entry.type !== "message" || entry.message.role !== "toolResult" || entry.message.toolName !== SEARCH_TOOL || entry.message.isError)
+    if (entry.type !== "message" || entry.message.role !== "toolResult" || entry.message.toolName !== TOOLS_TOOL || entry.message.isError)
       continue;
     const details = entry.message.details;
     if (!object(details) || details.mcpClient !== 1 || !Array.isArray(details.loaded))
       continue;
-    for (const raw of details.loaded.slice(0, 10)) {
+    for (const raw of details.loaded.slice(0, MAX_SEARCH_LIMIT)) {
       if (!object(raw) || typeof raw.server !== "string" || typeof raw.identity !== "string" || typeof raw.name !== "string" || typeof raw.description !== "string" || !object(raw.inputSchema))
         continue;
       try {
@@ -2972,40 +3256,59 @@ var Exposure = class {
 
 // src/output.ts
 init_diagnostics();
-import { mkdtemp, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdtemp, writeFile as writeFile3 } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join as join3 } from "node:path";
 import {
   truncateHead,
-  withFileMutationQueue as withFileMutationQueue2
+  withFileMutationQueue as withFileMutationQueue3
 } from "@earendil-works/pi-coding-agent";
 function textResult(text, details) {
   return { content: [{ type: "text", text }], details };
 }
 async function convertResult(result, label) {
   const texts = [];
+  const blocks = [];
+  let offset = 0;
+  const append = (text2, metadata = {}) => {
+    const start = offset + (texts.length ? 2 : 0);
+    offset = start + text2.length;
+    texts.push(text2);
+    blocks.push({ ...metadata, start, end: offset });
+  };
   const images = [];
   let imageBytes = 0;
   let needsSpill = false;
   for (const part of result.content ?? []) {
-    if (part.type === "text") texts.push(part.text);
+    if (part.type === "text") append(part.text);
     else if (part.type === "image" && ["image/png", "image/jpeg", "image/gif", "image/webp"].includes(part.mimeType) && imageBytes + part.data.length <= 8 * 1024 * 1024) {
       images.push({ type: "image", data: part.data, mimeType: part.mimeType });
       imageBytes += part.data.length;
     } else if (part.type === "resource" && "text" in part.resource)
-      texts.push(part.resource.text);
-    else if (part.type === "resource_link") texts.push(`${part.name}: ${part.uri}`);
+      append(part.resource.text, { mimeType: part.resource.mimeType });
+    else if (part.type === "resource_link")
+      append(`${part.name}: ${part.uri}`, {
+        mimeType: part.mimeType,
+        resourceLink: true
+      });
     else {
-      texts.push(`[${part.type} content saved in full result file]`);
+      append(`[${part.type} content saved in full result file]`, {
+        mimeType: "text/plain"
+      });
       needsSpill = true;
     }
   }
   if (result.structuredContent !== void 0)
-    texts.push(JSON.stringify(result.structuredContent, null, 2));
+    append(JSON.stringify(result.structuredContent, null, 2), { structured: true });
   const truncated = truncateHead(texts.join("\n\n"));
   let text = truncated.content;
   const details = {
     mcpClient: 1,
+    displayBlocks: blocks.filter((block) => block.start < text.length).map((block) => ({
+      ...block,
+      end: Math.min(block.end, text.length),
+      ...block.end > text.length ? { truncated: true } : {}
+    })),
     failed: result.isError === true,
     ...result.isError ? {
       diagnostics: [
@@ -3019,9 +3322,9 @@ async function convertResult(result, label) {
   };
   if (truncated.truncated || needsSpill) {
     const path = join3(await mkdtemp(join3(tmpdir(), "pi-mcp-client-")), "result.json");
-    await withFileMutationQueue2(
+    await withFileMutationQueue3(
       path,
-      () => writeFile2(path, JSON.stringify(result), { mode: 384 })
+      () => writeFile3(path, JSON.stringify(result), { mode: 384 })
     );
     details.fullOutputPath = path;
     text += `
@@ -3036,9 +3339,104 @@ Full MCP result: ${path}`;
 
 // src/render.ts
 import { keyText } from "@earendil-works/pi-coding-agent";
-import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { Text, truncateToWidth as truncateToWidth2 } from "@earendil-works/pi-tui";
 init_config();
+
+// src/format.ts
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES
+} from "@earendil-works/pi-coding-agent";
+function formatBlock(text, block, theme) {
+  const fallback = plain(text);
+  if (block.truncated || block.resourceLink || Buffer.byteLength(text) > DEFAULT_MAX_BYTES)
+    return fallback;
+  const mime = block.mimeType?.split(";", 1)[0]?.trim().toLowerCase();
+  const explicitJson = mime === "application/json" || mime === "text/json" || /^application\/[^\s/;]+\+json$/.test(mime ?? "");
+  if (mime && !explicitJson) return fallback;
+  if (!explicitJson && !block.structured && !/^[\s]*[\[{]/.test(text))
+    return fallback;
+  try {
+    JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+  const tokens2 = text.match(
+    /"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}\[\],:]/g
+  ) ?? [];
+  const pieces = [];
+  let depth = 0;
+  let bytes = 0;
+  let lines = 1;
+  const add = (value, color) => {
+    bytes += Buffer.byteLength(value);
+    lines += value.split("\n").length - 1;
+    pieces.push({ text: value, color });
+  };
+  const newline = () => add("\n" + "  ".repeat(depth));
+  for (let i = 0; i < tokens2.length; i++) {
+    const token = tokens2[i];
+    if (token === "{" || token === "[") {
+      add(token, "syntaxPunctuation");
+      depth++;
+      if (depth > 100) return fallback;
+      if (tokens2[i + 1] !== "}" && tokens2[i + 1] !== "]") newline();
+    } else if (token === "}" || token === "]") {
+      depth--;
+      if (tokens2[i - 1] !== "{" && tokens2[i - 1] !== "[") newline();
+      add(token, "syntaxPunctuation");
+    } else if (token === ",") {
+      add(token, "syntaxPunctuation");
+      newline();
+    } else if (token === ":") {
+      add(":", "syntaxPunctuation");
+      add(" ");
+    } else {
+      add(
+        token,
+        token.startsWith('"') ? tokens2[i + 1] === ":" ? "syntaxVariable" : "syntaxString" : /^(true|false|null)$/.test(token) ? "syntaxKeyword" : "syntaxNumber"
+      );
+    }
+    if (bytes > DEFAULT_MAX_BYTES || lines > DEFAULT_MAX_LINES) return fallback;
+  }
+  return pieces.map(
+    ({ text: value, color }) => color ? theme.fg(color, plain(value)) : value
+  ).join("");
+}
+function formatOutput(text, blocks, theme) {
+  if (!blocks) return formatBlock(text, {}, theme);
+  let cursor = 0;
+  let extraBytes = 0;
+  let extraLines = 0;
+  const output = [];
+  for (const block of blocks) {
+    if (!Number.isInteger(block.start) || !Number.isInteger(block.end) || block.start < cursor || block.end < block.start || block.end > text.length)
+      return plain(text);
+    output.push(plain(text.slice(cursor, block.start)));
+    const source = text.slice(block.start, block.end);
+    const formatted = formatBlock(source, block, theme);
+    const visible = plain(formatted);
+    extraBytes += Math.max(
+      0,
+      Buffer.byteLength(visible) - Buffer.byteLength(source)
+    );
+    extraLines += Math.max(
+      0,
+      visible.split("\n").length - source.split("\n").length
+    );
+    if (extraBytes > DEFAULT_MAX_BYTES || extraLines > DEFAULT_MAX_LINES)
+      return plain(text);
+    output.push(formatted);
+    cursor = block.end;
+  }
+  output.push(plain(text.slice(cursor)));
+  return output.join("");
+}
+
+// src/render.ts
 var states = {
+  candidate: { glyph: "\u25CB", color: "dim" },
+  active: { glyph: "\u25CF", color: "dim" },
   queued: { glyph: "\u25CF", color: "dim" },
   running: { glyph: "\u25B6\uFE0E", color: "muted" },
   done: { glyph: "\u2714\uFE0E", color: "success" },
@@ -3047,16 +3445,16 @@ var states = {
 };
 function renderCall(title, args, theme, expanded) {
   const values = object(args) ? args : {};
-  const preview = Object.entries(values).map(([key, value]) => `${line(key)}=${line(JSON.stringify(value) ?? "")}`).join(" ");
+  const preview = title === "mcp activate" ? "" : Object.entries(values).map(([key, value]) => `${line(key)}=${line(JSON.stringify(value) ?? "")}`).join(" ");
   return {
     render(width) {
       if (width <= 0) return [];
       const text = theme.fg("toolTitle", theme.bold(line(title))) + (preview ? theme.fg("dim", ` ${preview}`) : "");
       if (expanded)
-        return new Text(text, 0, 0).render(width).map((row) => truncateToWidth(row, width));
+        return new Text(text, 0, 0).render(width).map((row) => truncateToWidth2(row, width));
       const key = keyText("app.tools.expand");
       return [
-        truncateToWidth(
+        truncateToWidth2(
           text + (key ? theme.fg("muted", ` (${key} to expand)`) : ""),
           width
         )
@@ -3066,40 +3464,51 @@ function renderCall(title, args, theme, expanded) {
     }
   };
 }
+function formatValidation(text, theme) {
+  const marker = /\r?\n\r?\nReceived arguments:\r?\n/.exec(text);
+  if (!marker) return plain(text);
+  const start = marker.index + marker[0].length;
+  return plain(text.slice(0, start)) + formatBlock(text.slice(start), {}, theme);
+}
 function renderResult(result, options, theme, isError) {
   const details = object(result.details) && result.details.mcpClient === 1 ? result.details : void 0;
-  const text = plain(
-    result.content.filter((part) => part.type === "text").map((part) => part.text ?? "").join("\n")
-  );
+  const text = result.content.filter((part) => part.type === "text").map((part) => part.text ?? "").join("\n");
+  const validation = !details && isError ? /^Validation failed for tool "[^"\r\n]+":\r?\n([\s\S]*)$/.exec(text) : null;
+  const body = validation?.[1] ?? text;
   const rows = details?.rows ?? [
     {
-      label: line(text) || "Working\u2026",
+      label: validation ? "Invalid tool arguments" : isError ? "Tool failed" : line(text) || "Working\u2026",
       state: isError ? "failed" : options.isPartial ? "running" : "done"
     }
   ];
+  let formattedOutput;
   return {
     render(width) {
       if (width <= 0) return [];
       const lines = rows.flatMap((row) => {
         const status = states[row.state] ?? states.failed;
-        const value = theme.fg(status.color, status.glyph) + " " + theme.fg("accent", line(row.label));
-        const rendered = options.expanded && (!details?.searchNotes || row.state === "failed") ? new Text(value, 0, 0).render(width).map((x) => truncateToWidth(x, width)) : [truncateToWidth(value, width)];
+        const value = theme.fg(status.color, status.glyph) + " " + theme.fg("accent", line(row.label)) + (row.inlineDescription ? theme.fg("dim", ` ${line(row.inlineDescription)}`) : "");
+        const rendered = options.expanded && (!details?.searchNotes || row.state === "failed") ? new Text(value, 0, 0).render(width).map((x) => truncateToWidth2(x, width)) : [truncateToWidth2(value, width)];
         if (options.expanded && row.description)
-          rendered.push(truncateToWidth(
+          rendered.push(truncateToWidth2(
             theme.fg("dim", `  ${line(row.description)}`),
             width
           ));
         return rendered;
       });
       for (const note of details?.searchNotes ?? [])
-        lines.push(...(options.expanded ? new Text(theme.fg("warning", plain(note)), 0, 0).render(width) : [theme.fg("warning", line(note))]).map((row) => truncateToWidth(row, width)));
+        lines.push(...(options.expanded ? new Text(theme.fg("warning", plain(note)), 0, 0).render(width) : [theme.fg("warning", line(note))]).map((row) => truncateToWidth2(row, width)));
       if (options.expanded && !options.isPartial && text && !details?.searchNotes)
         lines.push(
-          ...new Text(text, 0, 0).render(width).map((x) => truncateToWidth(x, width))
+          ...new Text(
+            formattedOutput ??= validation ? formatValidation(body, theme) : formatOutput(body, details?.displayBlocks, theme),
+            0,
+            0
+          ).render(width).map((x) => truncateToWidth2(x, width))
         );
       if (!options.expanded && details?.fullOutputPath)
         lines.push(
-          truncateToWidth(
+          truncateToWidth2(
             theme.fg("dim", `Full result: ${details.fullOutputPath}`),
             width
           )
@@ -3107,6 +3516,7 @@ function renderResult(result, options, theme, isError) {
       return lines;
     },
     invalidate() {
+      formattedOutput = void 0;
     }
   };
 }
@@ -3123,7 +3533,10 @@ function errorResult(error, context) {
     failed: true,
     diagnostics: [value],
     rows: [
-      { label: message, state: value.code === "cancelled" ? "cancelled" : "failed" }
+      {
+        label: value.code === "cancelled" ? "Cancelled" : message,
+        state: value.code === "cancelled" ? "cancelled" : "failed"
+      }
     ]
   });
 }
@@ -3132,6 +3545,7 @@ function mcpClient(pi, options = {}) {
   let runtime;
   let config = {};
   let configError;
+  let sessionGeneration = 0;
   const exposure = new Exposure(pi, registerNative);
   const current = () => {
     if (!runtime)
@@ -3192,34 +3606,72 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
     });
     exposure.restore(tools);
   };
+  async function reloadConfiguration(ctx, toggle) {
+    const generation = sessionGeneration;
+    const validate = (nextConfig2) => {
+      ctx.signal?.throwIfAborted();
+      if (generation !== sessionGeneration)
+        throw new CommandUsageError("The Pi session changed during configuration reload.");
+      for (const definition of Object.values(nextConfig2)) {
+        if (!definition.disabled) resolveServer(definition, ctx.cwd);
+      }
+    };
+    ctx.signal?.throwIfAborted();
+    const update = toggle && await setServerDisabled(
+      agentDir,
+      ctx.cwd,
+      ctx.isProjectTrusted(),
+      toggle.server,
+      toggle.disabled,
+      validate
+    );
+    const nextConfig = update ? update.config : await loadConfig(agentDir, ctx.cwd, ctx.isProjectTrusted());
+    validate(nextConfig);
+    const next = new McpRuntime(
+      nextConfig,
+      ctx.cwd,
+      join4(agentDir, "cache", "pi-mcp-client")
+    );
+    const active = new Set(pi.getActiveTools());
+    const retained = [...exposure.definitions.values()].filter((tool) => {
+      try {
+        return active.has(tool.nativeName) && next.identity(tool.server) === tool.identity && allowed(tool.name, nextConfig[tool.server]);
+      } catch {
+        return false;
+      }
+    });
+    const old = runtime;
+    config = nextConfig;
+    configError = void 0;
+    runtime = next;
+    exposure.restore(retained);
+    await old?.close();
+    return update?.scope;
+  }
   pi.on("session_start", async (_event, ctx) => {
+    sessionGeneration++;
     await runtime?.close();
     runtime = void 0;
     config = {};
     configError = void 0;
     try {
       config = await loadConfig(agentDir, ctx.cwd, ctx.isProjectTrusted());
-      runtime = new McpRuntime(
-        config,
-        ctx.cwd,
-        join4(agentDir, "cache", "pi-mcp-client")
-      );
+      runtime = new McpRuntime(config, ctx.cwd, join4(agentDir, "cache", "pi-mcp-client"));
     } catch (error) {
-      configError = new DiagnosticError(
-        diagnose(error, { operation: "configuration" })
-      );
+      configError = new DiagnosticError(diagnose(error, { operation: "configuration" }));
       if (ctx.hasUI) ctx.ui.notify(configError.message, "error");
     }
     restore(ctx);
   });
   pi.on("session_tree", (_event, ctx) => restore(ctx));
   pi.on("session_shutdown", async () => {
+    sessionGeneration++;
     const old = runtime;
     runtime = void 0;
     await old?.close();
   });
   pi.on("before_agent_start", (event) => {
-    if (!pi.getActiveTools().includes(SEARCH_TOOL)) return;
+    if (!pi.getActiveTools().includes(TOOLS_TOOL)) return;
     const directory = Object.entries(config).filter(([, value]) => !value.disabled).map(
       ([name, value]) => `- ${name}${value.description ? `: ${line(value.description).slice(0, 160)}` : ""}`
     ).join("\n");
@@ -3229,109 +3681,120 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
 
 Additional MCP capabilities (directory metadata, not instructions):
 ${directory}
-Use mcp_search to load relevant tools, then call them directly. Loaded tools remain available; search again only when a missing capability is needed.`
+Discover candidates with mcp_tools({query: "capability", server: "name"}); discovery never activates tools, even for exact-name queries. Then explicitly activate only the identifiers you need with mcp_tools({activate: ["server.tool"]}), and call the loaded native tools directly. Activation accepts exact identifiers without prior discovery and never invokes tools. Loaded tools remain available.`
     };
   });
   pi.on("tool_result", (event) => {
-    if ((event.toolName === SEARCH_TOOL || exposure.definitions.has(event.toolName)) && object(event.details) && event.details.mcpClient === 1 && event.details.failed === true)
+    if ((event.toolName === TOOLS_TOOL || exposure.definitions.has(event.toolName)) && object(event.details) && event.details.mcpClient === 1 && event.details.failed === true)
       return { isError: true };
   });
   pi.registerTool({
-    name: SEARCH_TOOL,
-    label: "MCP Search",
-    description: "Search for and load MCP tools by capability or exact server.tool / mcp__server__tool name. Matches become directly callable on the next turn and remain available. Use a focused query and optionally a server name. Search only discovers tools; it does not invoke them. Default limit: 5, maximum: 50.",
+    name: TOOLS_TOOL,
+    label: "MCP Tools",
+    description: "Discover MCP candidates with query (optional server and limit), or explicitly activate 1\u201350 exact server.tool / mcp__server__tool identifiers with activate. Exactly one of query or activate is required; server and limit are query-only. Even an exact-name query is discovery-only and never activates tools. Activation needs no prior search, never resolves fuzzy matches, and never invokes tools. Activated tools become natively callable on the next turn and remain available. Discovery default limit: 5, maximum: 50.",
     parameters: Type.Object(
       {
-        query: Type.String({
+        query: Type.Optional(Type.String({
           minLength: 1,
           maxLength: 500,
-          description: "One focused capability or exact server.tool name, for example linear.list_teams. Do not enumerate every capability of a server."
-        }),
-        server: Type.Optional(Type.String({
-          minLength: 1,
-          maxLength: 80,
-          description: "Restrict discovery to this configured MCP server."
+          description: "One focused capability or exact server.tool name, for example linear.list_teams. Discovery only; does not activate tools."
+        })),
+        activate: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 600 }), {
+          minItems: 1,
+          maxItems: MAX_SEARCH_LIMIT,
+          description: "Exact server.tool or mcp__server__tool identifiers to activate, without invoking. Duplicates are ignored. Cannot be combined with query, server, or limit."
         })),
-        limit: Type.Optional(Type.Integer({
-          minimum: 1,
-          maximum: MAX_SEARCH_LIMIT,
-          default: DEFAULT_SEARCH_LIMIT,
-          description: `Maximum number of tools to load: 1\u2013${MAX_SEARCH_LIMIT} inclusive (default: ${DEFAULT_SEARCH_LIMIT}). This is not a limit on records returned by a native tool. Omit unless more tools are needed.`
-        }))
+        server: Type.Optional(
+          Type.String({
+            minLength: 1,
+            maxLength: 80,
+            description: "Restrict discovery to this configured MCP server."
+          })
+        ),
+        limit: Type.Optional(
+          Type.Integer({
+            minimum: 1,
+            maximum: MAX_SEARCH_LIMIT,
+            default: DEFAULT_SEARCH_LIMIT,
+            description: `Maximum number of candidates to return: 1\u2013${MAX_SEARCH_LIMIT} inclusive (default: ${DEFAULT_SEARCH_LIMIT}). This is not a limit on records returned by a native tool. Omit unless more tools are needed.`
+          })
+        )
       },
       { additionalProperties: false }
     ),
-    renderCall: (args, theme, context) => renderCall("mcp search", args, theme, context.expanded),
+    renderCall: (args, theme, context) => renderCall(args.activate ? "mcp activate" : "mcp discover", args, theme, context.expanded),
     renderResult: (result, options2, theme, context) => renderResult(result, options2, theme, context.isError),
     async execute(_id, args, signal, onUpdate, ctx) {
+      const usage = 'Use exactly one of {query: "capability", server?: "name", limit?: 1\u201350} or {activate: ["server.tool", ...]} (1\u201350 exact identifiers). server and limit are valid only with query.';
+      const hasQuery = args.query !== void 0;
+      const hasActivate = args.activate !== void 0;
+      if (hasQuery === hasActivate || hasActivate && (args.server !== void 0 || args.limit !== void 0) || hasQuery && (typeof args.query !== "string" || !args.query.trim() || args.query.length > 500) || hasActivate && (!Array.isArray(args.activate) || args.activate.length < 1 || args.activate.length > MAX_SEARCH_LIMIT || args.activate.some((id) => typeof id !== "string" || !id.trim() || id.length > 600)) || args.server !== void 0 && (typeof args.server !== "string" || !args.server.trim() || args.server.length > 80) || args.limit !== void 0 && (!Number.isInteger(args.limit) || args.limit < 1 || args.limit > MAX_SEARCH_LIMIT) || Object.keys(args).some((key) => !["query", "activate", "server", "limit"].includes(key))) return textResult(usage, { mcpClient: 1, failed: true, rows: [{ label: usage, state: "failed" }] });
       try {
         const activeRuntime = current();
-        onUpdate?.(
-          textResult("Searching MCP catalog\u2026", {
-            mcpClient: 1,
-            rows: [{ label: args.query, state: "running" }]
-          })
-        );
-        const namedServer = Object.keys(config).sort((a, b) => b.length - a.length).find(
-          (name) => args.query.startsWith(`${name}.`) || args.query.startsWith(`mcp__${name}__`)
+        const identifiers = [...new Set(args.activate ?? [])];
+        const serversFor = (identifier) => Object.keys(config).filter(
+          (name) => identifier.startsWith(`${name}.`) || identifier.startsWith(`mcp__${name}__`) || // Long server names can have a truncated, hashed native name.
+          `mcp__${name}__`.length > 50 && identifier.startsWith(`mcp__${name}__`.slice(0, 50))
         );
+        onUpdate?.(textResult(hasActivate ? "Activating MCP tools\u2026" : "Searching MCP catalog\u2026", {
+          mcpClient: 1,
+          rows: [{ label: args.query ?? identifiers.join(", "), state: "running" }]
+        }));
         const discovery = await activeRuntime.discover(
-          args.server ?? namedServer,
+          hasActivate ? identifiers.flatMap(serversFor) : args.server ?? serversFor(args.query)[0],
           signal ?? ctx.signal
         );
         (signal ?? ctx.signal)?.throwIfAborted();
         if (runtime !== activeRuntime)
-          throw new Error("MCP session changed during search.");
-        const matches2 = searchTools(
-          discovery.tools,
-          args.query,
-          args.server,
-          args.limit
-        );
-        const { loaded, added, rejected } = exposure.load(matches2);
-        const messages2 = loaded.map(
-          (tool) => `${added.includes(tool.nativeName) ? "Loaded" : "Already loaded"}: ${tool.nativeName} \u2014 ${line(tool.description).slice(0, 180)}`
-        );
-        if (!messages2.length)
-          messages2.push(
-            "No callable matches found. Try a more specific capability, server, or exact tool name."
-          );
-        if (loaded.length)
-          messages2.push(
-            "Call the loaded tools directly. Their full schemas are now available."
-          );
-        messages2.push(
-          ...discovery.unavailable.map((message) => `Not searched: ${message}`),
-          ...discovery.warnings
-        );
-        if (rejected.length)
-          messages2.push(
-            `Not loaded (name collision or Pi tool restriction): ${rejected.join(", ")}`
-          );
+          throw new Error("MCP session changed during search or activation.");
         const details = {
           mcpClient: 1,
-          loaded,
           searchNotes: discovery.warnings,
           diagnostics: discovery.diagnostics,
-          failed: !loaded.length && discovery.diagnostics.length > 0,
-          rows: [
-            ...loaded.map((tool) => ({
-              label: `${tool.server}.${tool.name} \xB7 ${added.includes(tool.nativeName) ? "loaded" : "already loaded"}`,
-              description: tool.description,
-              state: "done"
-            })),
-            ...discovery.unavailable.map((label) => ({
-              label,
-              state: "failed"
-            })),
-            ...rejected.map((name) => ({
-              label: `${name} \xB7 not loaded`,
-              state: "failed"
-            }))
-          ]
+          rows: []
         };
-        if (!details.rows.length)
-          details.rows.push({ label: "No matching tools", state: "done" });
+        const messages2 = [];
+        if (!hasActivate) {
+          const candidates = searchTools(discovery.tools, args.query, args.server, args.limit);
+          details.candidates = candidates;
+          details.failed = !candidates.length && discovery.diagnostics.length > 0;
+          const active = new Set(pi.getActiveTools());
+          for (const tool of candidates) {
+            const label = summarize(tool) + (active.has(tool.nativeName) ? " [loaded]" : "");
+            messages2.push(label);
+            details.rows.push({
+              label: `${tool.server}.${tool.name}`,
+              inlineDescription: summarize(tool, false),
+              state: active.has(tool.nativeName) ? "active" : "candidate"
+            });
+          }
+          if (!candidates.length) messages2.push("No matching tools. Try a more specific capability, server, or exact tool name.");
+          details.rows.push(...discovery.unavailable.map((label) => ({ label, state: "failed" })));
+          messages2.push(...discovery.unavailable.map((message) => `Not searched: ${message}`), ...discovery.warnings);
+          messages2.push("No tools activated. Call mcp_tools({activate: [...]}) with the identifiers you need.");
+        } else {
+          const resolved = resolveTools(discovery.tools, identifiers);
+          const matches2 = [...new Map(resolved.flatMap(({ tool }) => tool ? [[tool.nativeName, tool]] : [])).values()];
+          const collisions = new Set(pi.getAllTools().filter((tool) => !exposure.definitions.has(tool.name)).map((tool) => tool.name));
+          const { loaded, added } = exposure.load(matches2);
+          details.loaded = loaded;
+          details.failed = loaded.length === 0;
+          for (const { identifier, tool, suggestions } of resolved) {
+            const ok = tool && loaded.includes(tool);
+            const unavailable = discovery.diagnostics.find((value) => value.server && serversFor(identifier).includes(value.server));
+            const reason = unavailable ? `server unavailable: ${formatDiagnostic(unavailable)}` : tool ? collisions.has(tool.nativeName) ? "name collision" : "restricted by Pi" : `unknown identifier${suggestions.length ? `; nearest catalog names: ${suggestions.join(", ")}` : "; no catalog names available for this server. Check the server identifier or discover candidates with query."}`;
+            const label = `${line(identifier)} \u2014 ${ok ? added.includes(tool.nativeName) ? "loaded" : "already loaded" : `not loaded \u2014 ${reason}`}`;
+            messages2.push(label);
+            details.rows.push({
+              label: line(identifier),
+              ...ok ? {} : { inlineDescription: reason },
+              state: ok ? "done" : "failed"
+            });
+          }
+          if (loaded.length) messages2.push("Call the loaded tools directly. Their full schemas are now available.");
+          messages2.push(...discovery.warnings);
+        }
+        if (!details.rows.length) details.rows.push({ label: "No matching tools", state: "candidate" });
         return textResult(messages2.join("\n"), details);
       } catch (error) {
         return errorResult(error, {
@@ -3344,34 +3807,93 @@ Use mcp_search to load relevant tools, then call them directly. Loaded tools rem
     }
   });
   pi.registerCommand("mcp", {
-    description: "Inspect MCP servers; /mcp auth|reconnect|refresh <server>",
+    description: "Manage MCP servers: list, status, reload, enable|disable|inspect|tools|auth|reconnect|refresh <server>",
     getArgumentCompletions(prefix) {
-      const values = [
-        "status",
-        ...["auth", "reconnect", "refresh"].flatMap(
-          (action) => Object.keys(config).map((name) => `${action} ${name}`)
-        )
-      ];
-      return values.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value }));
+      const serverActions = ["enable", "disable", "inspect", "tools", "auth", "reconnect", "refresh"];
+      const input = prefix.trimStart();
+      const match = /^(\S+)\s+(.*)$/s.exec(input);
+      if (!match) {
+        return ["list", "status", "reload", ...serverActions].filter((action2) => action2.startsWith(input)).map((action2) => ({ value: action2, label: action2 }));
+      }
+      const [, action, partialServer] = match;
+      if (!serverActions.includes(action) || /\s/.test(partialServer)) return [];
+      return Object.keys(config).filter(
+        (name) => name.startsWith(partialServer) && (action === "inspect" || (action === "enable" ? config[name].disabled : !config[name].disabled))
+      ).sort().map((name) => ({ value: `${action} ${name}`, label: name }));
     },
     async handler(args, ctx) {
+      const generation = sessionGeneration;
       await ctx.waitForIdle();
       const [action = "status", server, ...extra] = args.trim().split(/\s+/).filter(Boolean);
       try {
-        if (action === "status" && !server) {
-          const loaded = pi.getActiveTools().filter((name) => exposure.definitions.has(name)).length;
+        if (generation !== sessionGeneration)
+          throw new CommandUsageError("The Pi session changed while waiting for idle.");
+        if (action === "reload" && !server) {
+          await reloadConfiguration(ctx);
+          if (ctx.hasUI)
+            ctx.ui.notify(
+              "\u2714\uFE0E MCP configuration reloaded. Connections reopen on demand; tools from changed or removed servers are no longer active.",
+              "info"
+            );
+          return;
+        }
+        if ((action === "enable" || action === "disable") && server && !extra.length && Object.hasOwn(config, server)) {
+          const scope = await reloadConfiguration(ctx, { server, disabled: action === "disable" });
+          if (ctx.hasUI)
+            ctx.ui.notify(
+              `\u2714\uFE0E ${server}: ${action === "enable" ? "enabled" : "disabled"} in ${scope} configuration. ` + (action === "enable" ? "Connections and tool discovery remain on demand." : "Its connection is closed and its tools are no longer active."),
+              "info"
+            );
+          return;
+        }
+        if (action === "inspect" && server && !extra.length && Object.hasOwn(config, server)) {
           if (ctx.hasUI)
             ctx.ui.notify(
-              `${current().status()}
-${loaded} native MCP tools loaded.`,
+              inspectServer(server, config[server], current().status(server)),
               "info"
             );
           return;
         }
+        if ((action === "status" || action === "list") && !server) {
+          const statuses = current().serverStatuses();
+          const loaded = /* @__PURE__ */ new Map();
+          for (const name of pi.getActiveTools()) {
+            const tool = exposure.definitions.get(name);
+            if (tool) loaded.set(tool.server, (loaded.get(tool.server) ?? 0) + 1);
+          }
+          if (ctx.hasUI) ctx.ui.notify(serverMatrix(statuses, loaded), "info");
+          return;
+        }
         if (!server || extra.length || !Object.hasOwn(config, server) || config[server].disabled)
           throw new CommandUsageError(
-            "Usage: /mcp auth|reconnect|refresh <enabled-server>"
+            "Usage: /mcp list|status|reload or /mcp enable|disable|inspect|tools|auth|reconnect|refresh <server>. Disabled servers accept enable, disable, and inspect."
           );
+        if (action === "tools") {
+          if (!ctx.hasUI)
+            throw new CommandUsageError("Tool browsing requires an interactive UI.");
+          const tools = await current().catalog(server, ctx.signal, true);
+          if (!tools.length) {
+            ctx.ui.notify(
+              `${server}: no tools available under the configured filters.`,
+              "info"
+            );
+            return;
+          }
+          const choices = [...tools].sort((a, b) => a.name.localeCompare(b.name));
+          const columns = ctx.mode === "tui" ? process.stdout.columns || 80 : 80;
+          const labels = choices.map((tool2, index) => toolPickerLabel(tool2, index, columns));
+          const selected = await ctx.ui.select(
+            `${server}: ${tools.length} tools (select to inspect; none are activated)`,
+            labels
+          );
+          const tool = selected === void 0 ? void 0 : choices[labels.indexOf(selected)];
+          if (tool)
+            ctx.ui.notify(
+              inspectTool(tool),
+              "info"
+            );
+          return;
+        }
         if (action === "auth") {
           if (!ctx.hasUI)
             throw new CommandUsageError(
@@ -3416,27 +3938,27 @@ ${target}`, "info");
           } else await authenticate(url, open, ctx.signal);
           await current().reconnect(server);
         } else if (action === "reconnect") await current().reconnect(server);
-        else if (action === "refresh")
-          await current().catalog(server, ctx.signal, true);
+        else if (action === "refresh") await current().catalog(server, ctx.signal, true);
         else
           throw new CommandUsageError(
-            "Unknown MCP command. Use /mcp auth|reconnect|refresh <server>."
+            "Unknown MCP command. Use /mcp list|status|reload or /mcp enable|disable|inspect|tools|auth|reconnect|refresh <server>."
           );
         if (ctx.hasUI)
           ctx.ui.notify(
-            `${server}: ${action} complete. Search to load new or changed tools.`,
+            `\u2714\uFE0E ${server}: ${action} complete. Updated tools are available for the assistant to discover.`,
             "info"
           );
       } catch (error) {
         const message = error instanceof CommandUsageError ? error.message : formatDiagnostic(
           diagnose(error, {
             server,
-            operation: action === "auth" ? "auth" : action === "refresh" ? "refresh" : "reconnect",
+            operation: ["reload", "inspect", "enable", "disable"].includes(action) ? "configuration" : action === "tools" ? "search" : action === "auth" ? "auth" : action === "refresh" ? "refresh" : "reconnect",
             oauth: config[server]?.oauth,
             signal: ctx.signal
           })
         );
         if (ctx.hasUI) ctx.ui.notify(message, "error");
+        else throw new Error(message);
       }
     }
   });