pi-mcp-client 0.2.0 → 0.3.1

package/README.md

@@ -29,22 +29,66 @@ Start a new Pi session and ask it to search Cloudflare's documentation. Use `/mc
 to inspect the connection. For authenticated services, see [OAuth](#oauth) or
 [secret commands](#secret-commands).
 
-Pi searches for the tools it needs, then calls those tools directly. Search
-loads up to five matching tools by default, or up to 50 with `limit`. Results
-use local BM25-based ranking, with tool names weighted more strongly than
-descriptions and support for prefix matching. Full schemas become available on
-the next model turn, without a separate describe step. Previously loaded tools
-remain available as the conversation continues.
+Pi discovers candidates, explicitly activates the tools it needs, then calls
+those tools natively. One `mcp_tools` tool supports both steps:
+
+```js
+// Discover candidates. Never activates, even for an exact-name query.
+mcp_tools({ query: "list teams", server: "linear", limit: 5 })
+
+// Activate exact identifiers. Never invokes.
+mcp_tools({ activate: ["linear.list_teams", "linear.get_team"] })
+```
+
+Pass exactly one of `query` or `activate`. The optional `server` and `limit`
+fields are valid only with `query`. Discovery returns up to five candidates by
+default, or up to 50 with `limit`. Each candidate shows its exact activation
+identifier, a short description, required parameter names only, and `[loaded]`
+if already active. Results use local BM25-based ranking, with tool names weighted
+more strongly than descriptions and support for prefix matching.
+
+Activation accepts 1–50 exact `server.tool` or `mcp__server__tool` identifiers,
+ignores duplicates, and works without a prior search. Typos never activate fuzzy
+matches: failures list nearby catalog names when available so the assistant can
+retry with an exact identifier. Each identifier reports `loaded`, `already loaded`,
+or `not loaded` with a reason. Partial success keeps the tools that loaded.
+
+Full schemas become available on the model turn after activation. First use of a
+capability now takes three turns—discover, activate, call—so a fuzzy search match
+can never become an active tool. Previously loaded tools remain available.
+
+`mcp_tools` replaces `mcp_search` without backward compatibility. Update explicit
+Pi tool allowlists to use `mcp_tools` and activate the tools you need again in
+existing sessions. The UI labels discovery calls **mcp discover** and activation
+calls **mcp activate**.
+
+### Result display
+
+Discovery rows show `○` for inactive candidates and `●` for already active tools,
+without a status suffix. These reflect the state when discovery runs; earlier
+results don't update retroactively. Activation results use `✔︎` for success and
+`✘︎` for failure. Descriptions stay gray; identifiers remain prominent.
+
+Expand a tool result to see JSON objects and arrays formatted with two-space
+indentation and syntax highlighting. Explicit JSON resource MIME types (including
+`application/*+json`) and structured content identify JSON without guessing.
+Other explicit MIME types stay plain text; unlabeled text is checked for JSON.
+
+Formatting changes only the display, not the response sent to the assistant.
+Invalid or truncated JSON stays plain text. Results that would exceed formatting
+limits also stay plain text. Resource-link MIME types describe the linked content,
+not the displayed link label.
 
 ### Session behavior
 
 - Tools accumulate rather than rotating with each prompt.
-- Resume and branch navigation restore tools acquired on the selected branch.
+- Resume and branch navigation restore tools activated through `mcp_tools` on
+  the selected branch. Discovery results never restore tools.
 - Compaction retains the acquired tool set. New sessions start fresh.
 - Pi uses native deferred loading where supported by the model and provider.
   Other providers receive the expanded tool list normally.
-- Search respects server filters and Pi's tool exclusions. An explicit tool
-  allowlist must include both `mcp_search` and the native tools you want to load.
+- Discovery respects server filters; activation also respects Pi's tool exclusions. An explicit tool
+  allowlist must include both `mcp_tools` and the native tools you want to load.
 
 ### Commands
 
@@ -54,6 +98,8 @@ remain available as the conversation continues.
 | `/mcp inspect <server>` | Inspect status and configuration, including disabled servers. Connection values are hidden. |
 | `/mcp tools <server>` | Browse the server's tools and inspect descriptions without activating tools. |
 | `/mcp reload` | Apply configuration changes without restarting Pi. |
+| `/mcp enable <server>` | Enable a server in its effective configuration file. |
+| `/mcp disable <server>` | Disable a server, close its connection, and deactivate its tools. |
 | `/mcp auth <server>` | Authenticate an OAuth-enabled HTTP server. |
 | `/mcp reconnect <server>` | Replace a connection and refresh its catalog. |
 | `/mcp refresh <server>` | Refresh a server's catalog without loading additional tools. |
@@ -64,8 +110,8 @@ connections open on demand. A dash (`—`) means the catalog hasn't been fetched
 not that the server has no tools. The **Loaded** column counts tools currently
 active for the assistant.
 
-After refreshing a changed schema, search for the tool again to load its current
-definition. Calls validate the live catalog before execution and refuse removed
+After refreshing a changed schema, activate the tool again with its exact
+identifier to load its current definition. Calls validate the live catalog before execution and refuse removed
 or changed tools. The extension does not retry failed tool invocations; after an
 interrupted call, check whether the operation completed before trying again.
 
@@ -145,12 +191,12 @@ Commands use `/bin/sh` on Unix or Pi's shell selection on Windows, inherit Pi's
 process environment, and run in the server's configured `cwd` (the project
 directory by default). They run once per connection, including reconnections,
 not during configuration loading, status display, or cached discovery. Cold
-searches can connect and therefore execute commands. Concurrent connection
+searches and activations can connect and therefore execute commands. Concurrent connection
 requests share the same resolution.
 
 The client trims stdout and rejects empty output, nonzero exits, output above
 64 KiB, and resolution taking more than 10 seconds (or a shorter `timeoutMs`).
-Session shutdown cancels pending commands. Cancelling an individual search stops
+Session shutdown cancels pending commands. Cancelling an individual search or activation stops
 waiting but leaves shared connection work running for other callers. The client
 discards command stderr and does not include resolved secrets in errors, session
 records, or catalog caches. Commands themselves remain responsible for avoiding
@@ -200,6 +246,21 @@ invalid configuration leaves the previous setup intact. It closes existing
 connections, which reopen on demand, and deactivates tools from changed, removed,
 or disabled server definitions. Unchanged active tools remain available.
 
+To toggle a server without editing JSON, use `/mcp disable <server>` or
+`/mcp enable <server>`. The change persists in the trusted project's `.mcp.json`
+if that file defines the server; otherwise, it persists in the global
+`~/.pi/agent/mcp.json`. Untrusted project files are neither read nor changed.
+The command reports which scope changed. It updates only the `disabled` option,
+preserves other values (including secret references), and reformats the file as
+indented JSON. Repeating a toggle that's already set leaves the file unchanged.
+
+Both commands wait for active agent work to finish, then apply configuration as
+`/mcp reload` does: connections close and reopen on demand, while unchanged active
+tools from other servers remain available. Disabling removes the server from
+search and deactivates its tools. Enabling does not connect, authenticate, or load
+tools; ask the assistant to discover the capabilities you need. Other running Pi
+sessions pick up the saved change when they reload their MCP configuration.
+
 Use `/mcp inspect <server>` to check the effective transport, protocol, filters,
 and connection status without connecting or running secret commands. Connection
 values—including commands, arguments, URLs, headers, and environment variables—
@@ -216,19 +277,21 @@ context. This command requires an interactive UI.
 
 Connections start on demand, never while the extension factory loads. A search
 without a cached catalog contacts configured servers, with at most four discoveries
-in flight. A server-scoped search only contacts that server. Failed servers are
-reported as unsearched, not mistaken for an empty catalog.
+in flight. A server-scoped search only contacts that server. Activation discovers
+only the servers named by its identifiers, with the same concurrency bound.
+Failed servers are reported as unavailable, not mistaken for an empty catalog.
 
 Catalogs are cached privately under `~/.pi/agent/cache/pi-mcp-client/`, keyed by
 server configuration and working directory. Disk caches expire after 24 hours.
-They contain tool metadata, not configured credentials. Cached search needs no
-connection; invocation refreshes the live catalog before calling the tool.
+They contain tool metadata, not configured credentials. Cached discovery and
+activation need no connection; invocation refreshes the live catalog before
+calling the tool.
 Connections remain open until shutdown or explicit reconnection.
 
 When a connected server reports a tool-list change, the extension invalidates its
-memory and disk catalogs. The next search fetches the current list, including new
-or removed tools. Notifications don't replace active tool definitions: changed
-schemas require another `mcp_search` before use. Disconnected, cache-only searches
+memory and disk catalogs. The next discovery or activation fetches the current
+list, including new or removed tools. Notifications don't replace active tool
+definitions: changed schemas require another `mcp_tools({activate: [...]})` before use. Disconnected, cache-only searches
 can't receive notifications and still use the 24-hour disk-cache expiry.
 
 ### OAuth
@@ -255,8 +318,9 @@ Only load configuration you trust. Server executables and secret commands run
 with your user permissions; trusted project configuration can replace global
 connections and settings.
 
-Server metadata is untrusted. Search activates tools but does not approve their
-side effects or provide per-call confirmation. Use tool filters and Pi permission
+Server metadata is untrusted. Discovery never activates tools. Explicit
+activation exposes schemas but does not approve tool side effects or provide
+per-call confirmation. Use tool filters and Pi permission
 extensions for additional controls. Cancelling a call does not guarantee that the
 server rolled back its effects.
 
@@ -297,7 +361,7 @@ unavailable server is not an empty catalog.
 | `connection_failed` | Server executable, working directory, endpoint, network, and TLS configuration. |
 | `timeout` | Server responsiveness and the applicable request, secret-command, or OAuth time limit. |
 | `protocol_error` | Server compatibility and the `protocol` setting. |
-| `tool_changed` | Server filters and the current tool schema; search again. Reload Pi if connection configuration changed. |
+| `tool_changed` | Server filters and the current tool schema; activate the exact identifier again. Reload Pi if connection configuration changed. |
 | `tool_error` | The server's tool result and inputs; verify the outcome before retrying. |
 | `oauth_failed` | Browser access to the callback and support for dynamically registered public clients. |
 | `callback_unavailable` | Another process using local port 19847. |

package/dist/index.js

@@ -30,7 +30,9 @@ 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.",
+    server_unknown: "Choose a configured MCP server from the capability directory or run /mcp to list servers. Omit server in mcp_tools to search all enabled servers.",
+    server_disabled: `Run /mcp enable ${target}, or omit server in mcp_tools to search all enabled servers.`,
+    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.",
@@ -137,6 +139,8 @@ var init_diagnostics = __esm({
       cancelled: "The operation was cancelled.",
       connection_failed: "The server connection failed.",
       protocol_error: "The server response or protocol is not supported.",
+      server_unknown: "The MCP server is not configured.",
+      server_disabled: "The MCP server is disabled.",
       tool_changed: "The tool is unavailable or its configuration or schema changed.",
       tool_error: "The tool reported an error.",
       oauth_failed: "OAuth authentication did not complete.",
@@ -285,12 +289,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 +392,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 +593,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 +1949,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 +2356,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",
@@ -2467,7 +2548,7 @@ function inspectServer(name, config, status) {
 // 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
@@ -2517,7 +2598,7 @@ var OAuthProvider = class {
   data;
   verifier;
   discovery;
-  expectedState = randomUUID();
+  expectedState = randomUUID2();
   save() {
     this.store.write(JSON.stringify(this.data));
   }
@@ -2641,9 +2722,9 @@ async function authenticate(url, open, signal, store) {
 
 // src/runtime.ts
 init_config();
-import { mkdir, readFile as readFile2, rename, rm, 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
@@ -2652,7 +2733,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 {
@@ -2825,9 +2906,9 @@ var McpRuntime = class {
           state.tools = void 0;
           state.warnings = void 0;
           const path = join2(this.cacheDir, `${identity}.json`);
-          state.invalidating = withFileMutationQueue(
+          state.invalidating = withFileMutationQueue2(
             path,
-            () => rm(path, { force: true })
+            () => rm2(path, { force: true })
           ).catch(() => {
             state.warnings = [
               `${name}: stale catalog cache could not be removed.`
@@ -2934,7 +3015,7 @@ var McpRuntime = class {
           return tools;
         }
         throw new ToolContractError(
-          "MCP tool catalog kept changing. Search again."
+          "MCP tool catalog kept changing. Retry discovery or activation."
         );
       })().catch((error) => {
         state.error = this.failure(name, error);
@@ -2947,8 +3028,15 @@ 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") {
+      const config = Object.hasOwn(this.config, server) ? this.config[server] : void 0;
+      if (!config || config.disabled)
+        throw new DiagnosticError(diagnostic(
+          config ? "server_disabled" : "server_unknown",
+          { server, operation: "search" }
+        ));
+    }
+    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: [],
@@ -2985,7 +3073,7 @@ 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 {
@@ -3074,7 +3162,7 @@ var McpRuntime = class {
   async readCache(name, identity) {
     try {
       const path = join2(this.cacheDir, `${identity}.json`);
-      const info = await stat(path);
+      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"));
@@ -3095,28 +3183,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 () => {
+    await withFileMutationQueue2(path, async () => {
       if (!isCurrent()) return;
-      const temp = `${path}.${randomUUID2()}.tmp`;
-      await writeFile(temp, text, { mode: 384 });
-      if (isCurrent()) await rename(temp, path);
-      else await rm(temp, { force: true });
+      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 {
@@ -3179,40 +3267,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: [
@@ -3226,9 +3333,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 += `
@@ -3245,7 +3352,102 @@ Full MCP result: ${path}`;
 import { keyText } from "@earendil-works/pi-coding-agent";
 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" },
@@ -3254,7 +3456,7 @@ 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 [];
@@ -3273,23 +3475,31 @@ 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"
     }
   ];
+  const bodyInRow = details?.rows.length === 1 && details.rows[0].state === "failed" && details.rows[0].label === text && !/[\r\n]/.test(text);
+  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 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(truncateToWidth2(
@@ -3300,9 +3510,13 @@ function renderResult(result, options, theme, isError) {
       });
       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) => truncateToWidth2(row, width)));
-      if (options.expanded && !options.isPartial && text && !details?.searchNotes)
+      if (options.expanded && !options.isPartial && text && !details?.searchNotes && !bodyInRow)
         lines.push(
-          ...new Text(text, 0, 0).render(width).map((x) => truncateToWidth2(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(
@@ -3314,6 +3528,7 @@ function renderResult(result, options, theme, isError) {
       return lines;
     },
     invalidate() {
+      formattedOutput = void 0;
     }
   };
 }
@@ -3330,7 +3545,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"
+      }
     ]
   });
 }
@@ -3400,16 +3618,27 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
     });
     exposure.restore(tools);
   };
-  async function reloadConfiguration(ctx) {
+  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 nextConfig = await loadConfig(agentDir, ctx.cwd, ctx.isProjectTrusted());
-    ctx.signal?.throwIfAborted();
-    if (generation !== sessionGeneration)
-      throw new CommandUsageError("The Pi session changed during configuration reload.");
-    for (const definition of Object.values(nextConfig)) {
-      if (!definition.disabled) resolveServer(definition, ctx.cwd);
-    }
+    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,
@@ -3429,6 +3658,7 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
     runtime = next;
     exposure.restore(retained);
     await old?.close();
+    return update?.scope;
   }
   pi.on("session_start", async (_event, ctx) => {
     sessionGeneration++;
@@ -3453,7 +3683,7 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
     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");
@@ -3463,24 +3693,29 @@ 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."
-        }),
+          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."
+        })),
         server: Type.Optional(
           Type.String({
             minLength: 1,
@@ -3493,78 +3728,85 @@ Use mcp_search to load relevant tools, then call them directly. Loaded tools rem
             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.`
+            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, {
@@ -3577,9 +3819,9 @@ Use mcp_search to load relevant tools, then call them directly. Loaded tools rem
     }
   });
   pi.registerCommand("mcp", {
-    description: "Manage MCP servers: list, status, reload, inspect|tools|auth|reconnect|refresh <server>",
+    description: "Manage MCP servers: list, status, reload, enable|disable|inspect|tools|auth|reconnect|refresh <server>",
     getArgumentCompletions(prefix) {
-      const serverActions = ["inspect", "tools", "auth", "reconnect", "refresh"];
+      const serverActions = ["enable", "disable", "inspect", "tools", "auth", "reconnect", "refresh"];
       const input = prefix.trimStart();
       const match = /^(\S+)\s+(.*)$/s.exec(input);
       if (!match) {
@@ -3588,13 +3830,16 @@ Use mcp_search to load relevant tools, then call them directly. Loaded tools rem
       const [, action, partialServer] = match;
       if (!serverActions.includes(action) || /\s/.test(partialServer)) return [];
       return Object.keys(config).filter(
-        (name) => name.startsWith(partialServer) && (action === "inspect" || !config[name].disabled)
+        (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 (generation !== sessionGeneration)
+          throw new CommandUsageError("The Pi session changed while waiting for idle.");
         if (action === "reload" && !server) {
           await reloadConfiguration(ctx);
           if (ctx.hasUI)
@@ -3604,6 +3849,15 @@ Use mcp_search to load relevant tools, then call them directly. Loaded tools rem
             );
           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(
@@ -3624,7 +3878,7 @@ Use mcp_search to load relevant tools, then call them directly. Loaded tools rem
         }
         if (!server || extra.length || !Object.hasOwn(config, server) || config[server].disabled)
           throw new CommandUsageError(
-            "Usage: /mcp list|status|reload or /mcp inspect|tools|auth|reconnect|refresh <server>. Only inspect accepts a disabled 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)
@@ -3699,7 +3953,7 @@ ${target}`, "info");
         else if (action === "refresh") await current().catalog(server, ctx.signal, true);
         else
           throw new CommandUsageError(
-            "Unknown MCP command. Use /mcp list|status|reload or /mcp inspect|tools|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(
@@ -3710,7 +3964,7 @@ ${target}`, "info");
         const message = error instanceof CommandUsageError ? error.message : formatDiagnostic(
           diagnose(error, {
             server,
-            operation: action === "reload" || action === "inspect" ? "configuration" : action === "tools" ? "search" : 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
           })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-client",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "MCP tools for Pi, discovered on demand and called natively through the official SDK.",
   "type": "module",
   "license": "MIT",