dynmcp 0.3.0 → 0.4.0

package/dist/index.js

@@ -7,7 +7,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "dynmcp",
-  version: "0.3.0",
+  version: "0.4.0",
   description: "Dynamic MCP context management tool for AI MCP-enabled agents and clients.",
   author: "Brandon Burrus <brandon@burrus.io>",
   license: "MIT",
@@ -111,8 +111,12 @@ var mcpName = z.string().regex(MCP_NAME_PATTERN);
 var envModeSchema = z.enum(["enable", "dotenv", "process", "disable"]).describe(
   'Controls environment variable interpolation in config values. "enable" (default) merges .env and process.env (.env wins). "dotenv" loads .env only. "process" uses process.env only. "disable" turns interpolation off.'
 );
+var description = z.string().min(1, { message: "description must be a non-empty string" }).refine((value) => value.trim().length > 0, {
+  message: "description must not be whitespace-only"
+}).optional();
 var stdioTransport = z.object({
   transport: z.literal("stdio"),
+  description,
   command: z.string(),
   args: z.array(z.string()).optional(),
   env: z.record(z.string(), z.string()).optional()
@@ -122,11 +126,13 @@ var httpUrl = z.string().url().refine((u) => u.startsWith("http://") || u.starts
 });
 var streamableHttpTransport = z.object({
   transport: z.literal("streamable-http"),
+  description,
   url: httpUrl,
   headers: z.record(z.string(), z.string()).optional()
 }).strict();
 var sseTransport = z.object({
   transport: z.literal("sse"),
+  description,
   url: httpUrl,
   headers: z.record(z.string(), z.string()).optional()
 }).strict();
@@ -399,124 +405,87 @@ function aggregateCapabilities(upstreams) {
   return aggregated;
 }
 
-// src/proxy/tool-catalog.ts
-var DISCOVER_TOOL_PREAMBLE = `Use this tool to look up the full schema of a tool before calling it with use_tool.
-Call discover_tool with a tool name from the list below to get its complete description,
-input parameters, and output schema. Always discover a tool before using it.`;
-var ToolCatalog = class _ToolCatalog {
-  tools;
-  discoverToolDescription;
-  constructor(tools, description) {
-    this.tools = tools;
-    this.discoverToolDescription = description;
-  }
-  static fromFlat(upstreamTools) {
-    const toolMap = /* @__PURE__ */ new Map();
-    for (const tool of upstreamTools) {
-      toolMap.set(tool.name, tool);
+// src/proxy/lazy-registry.ts
+var LazyRegistry = class {
+  entries = /* @__PURE__ */ new Map();
+  failureCounts = /* @__PURE__ */ new Map();
+  register(name, entry) {
+    if (this.entries.has(name)) {
+      throw new Error(`LazyRegistry: duplicate registration for "${name}"`);
     }
-    const description = buildFlatDescription(upstreamTools);
-    return new _ToolCatalog(toolMap, description);
+    this.entries.set(name, entry);
   }
-  static fromGrouped(groups) {
-    const toolMap = /* @__PURE__ */ new Map();
-    for (const [mcpName2, tools] of groups) {
-      for (const tool of tools) {
-        toolMap.set(`${mcpName2}/${tool.name}`, tool);
-      }
-    }
-    const description = buildGroupedDescription(groups);
-    return new _ToolCatalog(toolMap, description);
+  has(name) {
+    return this.entries.has(name);
   }
-  getToolDetails(toolName) {
-    const tool = this.tools.get(toolName);
-    if (tool === void 0) {
-      const sortedNames = [...this.tools.keys()].sort().join(", ");
-      return `Unknown tool: "${toolName}". Available tools: ${sortedNames}`;
-    }
-    return buildToolDetailsString(toolName, tool);
+  get(name) {
+    return this.entries.get(name);
   }
-};
-function buildFlatDescription(tools) {
-  const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
-  const toolLines = sortedTools.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n");
-  return `${DISCOVER_TOOL_PREAMBLE}
-
-<tools>
-${toolLines}
-</tools>`;
-}
-function buildGroupedDescription(groups) {
-  const sortedMcpNames = [...groups.keys()].sort();
-  const sections = sortedMcpNames.map((mcpName2) => {
-    const tools = groups.get(mcpName2);
-    const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
-    const toolLines = sortedTools.map((tool) => `- ${mcpName2}/${tool.name}: ${tool.description}`).join("\n");
-    return `${mcpName2}:
-${toolLines}`;
-  });
-  return `${DISCOVER_TOOL_PREAMBLE}
-
-<tools>
-${sections.join("\n\n")}
-</tools>`;
-}
-function buildToolDetailsString(displayName, tool) {
-  const lines = [
-    `Tool: ${displayName}`,
-    `Description: ${tool.description}`,
-    "",
-    "Input Schema:",
-    JSON.stringify(tool.inputSchema, null, 2)
-  ];
-  if (tool.outputSchema !== void 0) {
-    lines.push("", "Output Schema:", JSON.stringify(tool.outputSchema, null, 2));
-  }
-  const annotationLines = buildAnnotationLines(tool);
-  if (annotationLines.length > 0) {
-    lines.push("", "Annotations:", ...annotationLines);
-  }
-  return lines.join("\n");
-}
-function buildAnnotationLines(tool) {
-  if (tool.annotations === void 0) {
-    return [];
+  /**
+   * Records a failed load attempt and returns the new total. The orchestrator's
+   * retry-budget logic uses this to decide whether to evict the entry. A
+   * subsequent successful load (or {@link take}) clears the count.
+   */
+  recordFailure(name) {
+    const next = (this.failureCounts.get(name) ?? 0) + 1;
+    this.failureCounts.set(name, next);
+    return next;
   }
-  const { annotations } = tool;
-  const lines = [];
-  if (annotations.title !== void 0) {
-    lines.push(`- title: ${annotations.title}`);
+  failureCount(name) {
+    return this.failureCounts.get(name) ?? 0;
   }
-  if (annotations.readOnlyHint !== void 0) {
-    lines.push(`- readOnlyHint: ${annotations.readOnlyHint}`);
+  /**
+   * Returns the descriptions of every still-lazy MCP in insertion order. Consumed
+   * by {@link ToolCatalog.fromGroupedWithLazy} to render the `<mcp_servers>` block.
+   */
+  descriptions() {
+    const result = /* @__PURE__ */ new Map();
+    for (const [name, entry] of this.entries) {
+      result.set(name, entry.description);
+    }
+    return result;
   }
-  if (annotations.destructiveHint !== void 0) {
-    lines.push(`- destructiveHint: ${annotations.destructiveHint}`);
+  /**
+   * Returns the names of every still-lazy MCP in insertion order. Used by error
+   * messages that need to hint the agent at what is loadable.
+   */
+  names() {
+    return [...this.entries.keys()];
   }
-  if (annotations.idempotentHint !== void 0) {
-    lines.push(`- idempotentHint: ${annotations.idempotentHint}`);
+  size() {
+    return this.entries.size;
   }
-  if (annotations.openWorldHint !== void 0) {
-    lines.push(`- openWorldHint: ${annotations.openWorldHint}`);
+  /**
+   * Removes and returns the entry, signalling that the upstream has been (or is
+   * about to be) promoted to a connected client (or evicted after exhausting
+   * its retry budget). The caller is responsible for ensuring the promotion
+   * actually succeeds — failed loads should re-register via {@link register} to
+   * roll back the state. Clears the failure count along with the entry.
+   */
+  take(name) {
+    const entry = this.entries.get(name);
+    if (entry === void 0) return void 0;
+    this.entries.delete(name);
+    this.failureCounts.delete(name);
+    return entry;
   }
-  return lines;
-}
+};
 
 // src/proxy/notification-forwarder.ts
 var NotificationForwarder = class {
-  constructor(registry, resourceRouter, promptRouter, toolsByMcp, setToolCatalog, namespaced) {
+  constructor(registry, resourceRouter, promptRouter, toolsByMcp, rebuildToolCatalog, namespaced) {
     this.registry = registry;
     this.resourceRouter = resourceRouter;
     this.promptRouter = promptRouter;
     this.toolsByMcp = toolsByMcp;
-    this.setToolCatalog = setToolCatalog;
+    this.rebuildToolCatalog = rebuildToolCatalog;
     this.namespaced = namespaced;
   }
   registry;
   resourceRouter;
   promptRouter;
   toolsByMcp;
-  setToolCatalog;
+  rebuildToolCatalog;
   namespaced;
   hostHandlers = {};
   setHostHandlers(handlers) {
@@ -527,8 +496,7 @@ var NotificationForwarder = class {
     if (client === void 0) return;
     const tools = await client.listTools().catch(() => []);
     this.toolsByMcp.set(mcpName2, tools);
-    const rebuilt = this.namespaced ? ToolCatalog.fromGrouped(this.toolsByMcp) : ToolCatalog.fromFlat([...this.toolsByMcp.values()][0] ?? []);
-    this.setToolCatalog(rebuilt);
+    this.rebuildToolCatalog();
     await this.hostHandlers.onToolsListChanged?.();
   }
   async handleResourcesListChanged(mcpName2) {
@@ -546,6 +514,22 @@ var NotificationForwarder = class {
   async handleResourceUpdated(params) {
     await this.hostHandlers.onResourceUpdated?.(params);
   }
+  /**
+   * Fire-only emitters. Unlike `handleXListChanged`, these do not re-fetch the
+   * affected data from any upstream — the caller has already populated the relevant
+   * state directly. Used by the orchestrator's load_mcp pipeline, which already has
+   * the freshly-queried tools/resources/prompts in hand and just needs to nudge the
+   * host to refetch.
+   */
+  async notifyToolsListChanged() {
+    await this.hostHandlers.onToolsListChanged?.();
+  }
+  async notifyResourcesListChanged() {
+    await this.hostHandlers.onResourcesListChanged?.();
+  }
+  async notifyPromptsListChanged() {
+    await this.hostHandlers.onPromptsListChanged?.();
+  }
   async handlePromptsListChanged(mcpName2) {
     const router = this.promptRouter();
     const client = this.registry.get(mcpName2);
@@ -608,6 +592,14 @@ var PromptRouter = class {
   collisions() {
     return this.detectedCollisions;
   }
+  /**
+   * Returns the prompts contributed by a single upstream MCP. Used by the load_mcp
+   * pipeline to construct its structured response. Returns an empty array if the MCP
+   * has not contributed any prompts (or if `mcpName` is unknown).
+   */
+  promptsFor(mcpName2) {
+    return this.perMcp.get(mcpName2) ?? [];
+  }
   rebuild() {
     this.nameOwners = /* @__PURE__ */ new Map();
     const collisions = [];
@@ -696,6 +688,19 @@ var ResourceRouter = class {
   collisions() {
     return this.detectedCollisions;
   }
+  /**
+   * Returns the resources contributed by a single upstream MCP. Used by the load_mcp
+   * pipeline to construct its structured response, which lists what a just-loaded MCP
+   * (or an already-loaded MCP, in the idempotent no-op path) brought to the proxy.
+   * Returns an empty array if the MCP has not contributed any resources (or if
+   * `mcpName` is unknown).
+   */
+  resourcesFor(mcpName2) {
+    return this.perMcp.get(mcpName2)?.resources ?? [];
+  }
+  templatesFor(mcpName2) {
+    return this.perMcp.get(mcpName2)?.templates ?? [];
+  }
   rebuild() {
     this.uriOwners = /* @__PURE__ */ new Map();
     this.templateOwners = [];
@@ -727,6 +732,145 @@ function literalPrefixOf(uriTemplate) {
   return idx === -1 ? uriTemplate : uriTemplate.slice(0, idx);
 }
 
+// src/proxy/tool-catalog.ts
+var DISCOVER_TOOL_PREAMBLE = `Use this tool to look up the full schema of a tool before calling it with use_tool.
+Call discover_tool with a tool name from the list below to get its complete description,
+input parameters, and output schema. Always discover a tool before using it.`;
+var DYNAMIC_DISCOVERY_PREAMBLE = `Some MCP servers below are not loaded yet and are listed under <mcp_servers> with a
+short description of what they do. To make a server's tools (and any resources or
+prompts it exposes) available, call load_mcp with its name. Once loaded, the server's
+tools will appear in the <tools> list and become callable via use_tool. Loading is
+permanent for the remainder of this session.`;
+var NO_TOOLS_LOADED_FOOTER = "No tools are currently loaded. Call load_mcp to make a server's tools available.";
+var ToolCatalog = class _ToolCatalog {
+  tools;
+  discoverToolDescription;
+  constructor(tools, description2) {
+    this.tools = tools;
+    this.discoverToolDescription = description2;
+  }
+  static fromFlat(upstreamTools) {
+    const toolMap = /* @__PURE__ */ new Map();
+    for (const tool of upstreamTools) {
+      toolMap.set(tool.name, tool);
+    }
+    const description2 = buildFlatDescription(upstreamTools);
+    return new _ToolCatalog(toolMap, description2);
+  }
+  static fromGrouped(groups) {
+    return _ToolCatalog.fromGroupedWithLazy(groups, /* @__PURE__ */ new Map());
+  }
+  /**
+   * Same as {@link fromGrouped} but additionally accepts a map of lazy upstream MCPs
+   * (those declared with a `description` field but not yet loaded). When the map is
+   * non-empty, the rendered `discover_tool` description includes a `<mcp_servers>`
+   * block listing them with their descriptions and an explanatory paragraph telling
+   * the agent how to call `load_mcp`. When `groups` is empty, the `<tools>` block is
+   * omitted in favor of a trailing sentence directing the agent to `load_mcp`.
+   */
+  static fromGroupedWithLazy(groups, lazyDescriptions) {
+    const toolMap = /* @__PURE__ */ new Map();
+    for (const [mcpName2, tools] of groups) {
+      for (const tool of tools) {
+        toolMap.set(`${mcpName2}/${tool.name}`, tool);
+      }
+    }
+    const description2 = buildGroupedDescription(groups, lazyDescriptions);
+    return new _ToolCatalog(toolMap, description2);
+  }
+  getToolDetails(toolName) {
+    const tool = this.tools.get(toolName);
+    if (tool === void 0) {
+      const sortedNames = [...this.tools.keys()].sort().join(", ");
+      return `Unknown tool: "${toolName}". Available tools: ${sortedNames}`;
+    }
+    return buildToolDetailsString(toolName, tool);
+  }
+};
+function buildFlatDescription(tools) {
+  const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
+  const toolLines = sortedTools.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n");
+  return `${DISCOVER_TOOL_PREAMBLE}
+
+<tools>
+${toolLines}
+</tools>`;
+}
+function buildGroupedDescription(groups, lazyDescriptions) {
+  const parts = [DISCOVER_TOOL_PREAMBLE];
+  if (lazyDescriptions.size > 0) {
+    parts.push(DYNAMIC_DISCOVERY_PREAMBLE);
+    parts.push(buildMcpServersBlock(lazyDescriptions));
+  }
+  if (groups.size > 0) {
+    parts.push(buildToolsBlock(groups));
+  } else if (lazyDescriptions.size > 0) {
+    parts.push(NO_TOOLS_LOADED_FOOTER);
+  } else {
+    parts.push("<tools>\n</tools>");
+  }
+  return parts.join("\n\n");
+}
+function buildToolsBlock(groups) {
+  const sortedMcpNames = [...groups.keys()].sort();
+  const sections = sortedMcpNames.map((mcpName2) => {
+    const tools = groups.get(mcpName2);
+    const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
+    const toolLines = sortedTools.map((tool) => `- ${mcpName2}/${tool.name}: ${tool.description}`).join("\n");
+    return `${mcpName2}:
+${toolLines}`;
+  });
+  return `<tools>
+${sections.join("\n\n")}
+</tools>`;
+}
+function buildMcpServersBlock(lazyDescriptions) {
+  const lines = [...lazyDescriptions].map(([name, desc]) => `- ${name}: ${desc}`).join("\n");
+  return `<mcp_servers>
+${lines}
+</mcp_servers>`;
+}
+function buildToolDetailsString(displayName, tool) {
+  const lines = [
+    `Tool: ${displayName}`,
+    `Description: ${tool.description}`,
+    "",
+    "Input Schema:",
+    JSON.stringify(tool.inputSchema, null, 2)
+  ];
+  if (tool.outputSchema !== void 0) {
+    lines.push("", "Output Schema:", JSON.stringify(tool.outputSchema, null, 2));
+  }
+  const annotationLines = buildAnnotationLines(tool);
+  if (annotationLines.length > 0) {
+    lines.push("", "Annotations:", ...annotationLines);
+  }
+  return lines.join("\n");
+}
+function buildAnnotationLines(tool) {
+  if (tool.annotations === void 0) {
+    return [];
+  }
+  const { annotations } = tool;
+  const lines = [];
+  if (annotations.title !== void 0) {
+    lines.push(`- title: ${annotations.title}`);
+  }
+  if (annotations.readOnlyHint !== void 0) {
+    lines.push(`- readOnlyHint: ${annotations.readOnlyHint}`);
+  }
+  if (annotations.destructiveHint !== void 0) {
+    lines.push(`- destructiveHint: ${annotations.destructiveHint}`);
+  }
+  if (annotations.idempotentHint !== void 0) {
+    lines.push(`- idempotentHint: ${annotations.idempotentHint}`);
+  }
+  if (annotations.openWorldHint !== void 0) {
+    lines.push(`- openWorldHint: ${annotations.openWorldHint}`);
+  }
+  return lines;
+}
+
 // src/proxy/upstream-client.ts
 import process3 from "process";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -961,6 +1105,41 @@ var UpstreamRegistry = class {
       throw error;
     }
   }
+  /**
+   * Connects a single additional upstream. Unlike {@link connectAll}, a failure here
+   * leaves any other connected clients untouched — the caller (typically the
+   * Orchestrator's `loadMcp` pipeline) needs that isolation because other lazy MCPs
+   * may have already been promoted to loaded, or eager MCPs are still healthy.
+   *
+   * Throws if `mcpName` is already in the registry; callers should check beforehand
+   * (the orchestrator handles the idempotency-success case before reaching here).
+   */
+  async connectOne(mcpName2, config) {
+    if (this.clients.has(mcpName2)) {
+      throw new Error(`UpstreamRegistry: "${mcpName2}" is already connected`);
+    }
+    const client = new UpstreamClient({
+      name: mcpName2,
+      transport: config.transport,
+      onTransportError: config.onTransportError,
+      notifications: config.notifications,
+      serverRequests: config.serverRequests
+    });
+    await client.connect();
+    this.clients.set(mcpName2, client);
+    return client;
+  }
+  /**
+   * Disconnects and removes a single upstream. Used by `loadMcp` to roll back a
+   * partially-loaded MCP when a post-connect catalog query fails. No-op if the name
+   * is not present.
+   */
+  async deleteOne(mcpName2) {
+    const client = this.clients.get(mcpName2);
+    if (client === void 0) return;
+    this.clients.delete(mcpName2);
+    await client.disconnect();
+  }
   get(mcpName2) {
     return this.clients.get(mcpName2);
   }
@@ -990,10 +1169,18 @@ var UpstreamRegistry = class {
 };
 
 // src/proxy/orchestrator.ts
+var MAX_LOAD_ATTEMPTS = 3;
 var Orchestrator = class {
   config;
   registry = new UpstreamRegistry();
+  lazyRegistry = new LazyRegistry();
   toolsByMcp = /* @__PURE__ */ new Map();
+  /**
+   * In-flight loads, keyed by mcpName. Used by {@link loadMcp} to coalesce concurrent
+   * calls for the same name onto a single underlying connection attempt — per SPEC.md
+   * § "Dynamic Discovery > Concurrency".
+   */
+  inFlightLoads = /* @__PURE__ */ new Map();
   resourceRouter = null;
   promptRouter = null;
   toolCatalog = null;
@@ -1001,9 +1188,14 @@ var Orchestrator = class {
   serverRequestForwarders = {};
   forwarder;
   constructor(config) {
-    if (!config.namespaced && config.mcps.size !== 1) {
+    if (!config.namespaced && config.eagerMcps.size !== 1) {
       throw new Error(
-        `Single-MCP (non-namespaced) mode requires exactly one upstream; got ${config.mcps.size}.`
+        `Single-MCP (non-namespaced) mode requires exactly one upstream; got ${config.eagerMcps.size}.`
+      );
+    }
+    if (!config.namespaced && config.lazyMcps !== void 0 && config.lazyMcps.size > 0) {
+      throw new Error(
+        "Single-MCP (non-namespaced) mode does not support lazy upstreams (descriptions)."
       );
     }
     this.config = config;
@@ -1012,9 +1204,7 @@ var Orchestrator = class {
       () => this.resourceRouter,
       () => this.promptRouter,
       this.toolsByMcp,
-      (catalog) => {
-        this.toolCatalog = catalog;
-      },
+      () => this.rebuildToolCatalog(),
       this.config.namespaced
     );
   }
@@ -1024,32 +1214,26 @@ var Orchestrator = class {
   setServerRequestForwarders(forwarders) {
     this.serverRequestForwarders = forwarders;
   }
+  /**
+   * True when the orchestrator was configured with at least one lazy upstream MCP.
+   * The `index.ts` wiring uses this to decide whether to register the `load_mcp`
+   * meta-tool with the host-facing {@link ProxyServer}.
+   */
+  get hasDynamicDiscovery() {
+    return this.config.lazyMcps !== void 0 && this.config.lazyMcps.size > 0;
+  }
   async connect() {
-    const resourceRouter = new ResourceRouter([...this.config.mcps.keys()]);
-    const promptRouter = new PromptRouter([...this.config.mcps.keys()]);
-    const upstreamEntries = [
-      ...this.config.mcps
-    ].map(([mcpName2, { transport }]) => [
-      mcpName2,
-      {
-        transport,
-        onTransportError: (error) => {
-          this.config.onTransportError?.(mcpName2, error);
-        },
-        notifications: {
-          onToolsListChanged: () => this.forwarder.handleToolsListChanged(mcpName2),
-          onResourcesListChanged: () => this.forwarder.handleResourcesListChanged(mcpName2),
-          onResourceUpdated: (params) => this.forwarder.handleResourceUpdated(params),
-          onPromptsListChanged: () => this.forwarder.handlePromptsListChanged(mcpName2),
-          onLogMessage: (params) => this.forwarder.handleLogMessage(mcpName2, params)
-        },
-        serverRequests: {
-          onCreateMessage: (params, opts) => this.forwardCreateMessage(params, opts),
-          onElicitInput: (params, opts) => this.forwardElicitInput(params, opts),
-          onListRoots: (params, opts) => this.forwardListRoots(params, opts)
-        }
+    const allNames = [...this.config.eagerMcps.keys(), ...this.config.lazyMcps?.keys() ?? []];
+    const resourceRouter = new ResourceRouter(allNames);
+    const promptRouter = new PromptRouter(allNames);
+    if (this.config.lazyMcps !== void 0) {
+      for (const [name, { transport, description: description2 }] of this.config.lazyMcps) {
+        this.lazyRegistry.register(name, { transport, description: description2 });
       }
-    ]);
+    }
+    const upstreamEntries = [
+      ...this.config.eagerMcps
+    ].map(([mcpName2, { transport }]) => [mcpName2, this.buildUpstreamConfig(mcpName2, transport)]);
     await this.registry.connectAll(upstreamEntries);
     const capabilityList = [];
     this.toolsByMcp.clear();
@@ -1071,10 +1255,10 @@ var Orchestrator = class {
         promptRouter.setPrompts(mcpName2, prompts);
       }
     }
-    this.toolCatalog = this.config.namespaced ? ToolCatalog.fromGrouped(this.toolsByMcp) : ToolCatalog.fromFlat([...this.toolsByMcp.values()][0] ?? []);
-    this.aggregatedCapabilities = aggregateCapabilities(capabilityList);
     this.resourceRouter = resourceRouter;
     this.promptRouter = promptRouter;
+    this.aggregatedCapabilities = aggregateCapabilities(capabilityList);
+    this.rebuildToolCatalog();
     logCollisions(resourceRouter, promptRouter);
   }
   async disconnectAll() {
@@ -1084,6 +1268,177 @@ var Orchestrator = class {
     this.aggregatedCapabilities = null;
     this.resourceRouter = null;
     this.promptRouter = null;
+    this.inFlightLoads.clear();
+  }
+  // === Dynamic discovery ===
+  /**
+   * Loads a lazy upstream MCP on demand. Implements the semantics of SPEC.md §
+   * "Tools > load_mcp" and § "Dynamic Discovery > Lifecycle of a Lazy MCP":
+   *
+   * - Already-loaded (eager or previously-loaded lazy) names succeed as a no-op
+   *   returning the current listing; no notifications fire.
+   * - Unknown names throw an error that hints at the still-lazy alternatives.
+   * - Concurrent calls for the same name coalesce onto the same in-flight load.
+   * - A failure during connect/initialize/catalog-query rolls back atomically:
+   *   the upstream is disconnected, the lazy entry stays registered, no host
+   *   notifications fire.
+   * - On success the loaded MCP is promoted into the connected registry, its
+   *   tools/resources/prompts populate the routers, the discover_tool catalog
+   *   is regenerated, and the host receives `tools/list_changed` plus
+   *   `resources/list_changed` and/or `prompts/list_changed` for any non-empty
+   *   surface the MCP contributed.
+   */
+  async loadMcp(mcpName2) {
+    if (this.registry.get(mcpName2) !== void 0) {
+      return this.getListing(mcpName2);
+    }
+    const inFlight = this.inFlightLoads.get(mcpName2);
+    if (inFlight !== void 0) {
+      return inFlight;
+    }
+    if (!this.lazyRegistry.has(mcpName2)) {
+      const lazyNames = this.lazyRegistry.names().join(", ");
+      const hint = lazyNames.length > 0 ? lazyNames : "(none)";
+      throw new Error(`Unknown MCP server: "${mcpName2}". Available servers to load: ${hint}`);
+    }
+    const loadPromise = this.runLoadPipeline(mcpName2).finally(() => {
+      this.inFlightLoads.delete(mcpName2);
+    });
+    this.inFlightLoads.set(mcpName2, loadPromise);
+    return loadPromise;
+  }
+  async runLoadPipeline(mcpName2) {
+    const entry = this.lazyRegistry.get(mcpName2);
+    if (entry === void 0) {
+      throw new Error(`Internal error: lazy entry "${mcpName2}" vanished mid-load.`);
+    }
+    const client = await this.registry.connectOne(
+      mcpName2,
+      this.buildUpstreamConfig(mcpName2, entry.transport)
+    );
+    let tools;
+    let resources = [];
+    let templates = [];
+    let prompts = [];
+    let caps;
+    try {
+      caps = client.getCapabilities();
+      tools = await client.listTools();
+      if (caps?.resources !== void 0) {
+        [resources, templates] = await Promise.all([
+          client.listResources(),
+          client.listResourceTemplates()
+        ]);
+      }
+      if (caps?.prompts !== void 0) {
+        prompts = await client.listPrompts();
+      }
+    } catch (error) {
+      await this.registry.deleteOne(mcpName2);
+      const failures = this.lazyRegistry.recordFailure(mcpName2);
+      if (failures >= MAX_LOAD_ATTEMPTS) {
+        this.lazyRegistry.take(mcpName2);
+        this.rebuildToolCatalog();
+        await this.forwarder.notifyToolsListChanged();
+        const base = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `Failed to load "${mcpName2}" after ${failures} attempts; the server will no longer be offered for discovery. Underlying error: ${base}`
+        );
+      }
+      throw error;
+    }
+    this.lazyRegistry.take(mcpName2);
+    this.toolsByMcp.set(mcpName2, tools);
+    const resourceRouter = this.requireResourceRouter();
+    const promptRouter = this.requirePromptRouter();
+    if (caps?.resources !== void 0) {
+      resourceRouter.setResources(mcpName2, resources);
+      resourceRouter.setTemplates(mcpName2, templates);
+    }
+    if (caps?.prompts !== void 0) {
+      promptRouter.setPrompts(mcpName2, prompts);
+    }
+    this.rebuildToolCatalog();
+    await this.forwarder.notifyToolsListChanged();
+    if (caps?.resources !== void 0 && (resources.length > 0 || templates.length > 0)) {
+      await this.forwarder.notifyResourcesListChanged();
+    }
+    if (caps?.prompts !== void 0 && prompts.length > 0) {
+      await this.forwarder.notifyPromptsListChanged();
+    }
+    return this.getListing(mcpName2);
+  }
+  /**
+   * Builds the structured response shape documented for `load_mcp` from existing
+   * per-MCP state. Pulled out into a helper so the no-op path (already-loaded)
+   * and the success path share one source of truth.
+   */
+  getListing(mcpName2) {
+    const tools = this.toolsByMcp.get(mcpName2) ?? [];
+    const namespacedToolName = (name) => this.config.namespaced ? `${mcpName2}/${name}` : name;
+    const resources = this.resourceRouter?.resourcesFor(mcpName2) ?? [];
+    const templates = this.resourceRouter?.templatesFor(mcpName2) ?? [];
+    const prompts = this.promptRouter?.promptsFor(mcpName2) ?? [];
+    return {
+      mcp_name: mcpName2,
+      tools: tools.map((tool) => ({
+        name: namespacedToolName(tool.name),
+        description: tool.description
+      })),
+      resources: resources.map((resource) => ({
+        uri: resource.uri,
+        name: resource.name,
+        description: resource.description,
+        mimeType: resource.mimeType
+      })),
+      resource_templates: templates.map((template) => ({
+        uriTemplate: template.uriTemplate,
+        name: template.name,
+        description: template.description,
+        mimeType: template.mimeType
+      })),
+      prompts: prompts.map((prompt) => ({
+        name: prompt.name,
+        description: prompt.description,
+        arguments: prompt.arguments
+      }))
+    };
+  }
+  // === Internal helpers used by connect() and loadMcp() ===
+  buildUpstreamConfig(mcpName2, transport) {
+    return {
+      transport,
+      onTransportError: (error) => {
+        this.config.onTransportError?.(mcpName2, error);
+      },
+      notifications: {
+        onToolsListChanged: () => this.forwarder.handleToolsListChanged(mcpName2),
+        onResourcesListChanged: () => this.forwarder.handleResourcesListChanged(mcpName2),
+        onResourceUpdated: (params) => this.forwarder.handleResourceUpdated(params),
+        onPromptsListChanged: () => this.forwarder.handlePromptsListChanged(mcpName2),
+        onLogMessage: (params) => this.forwarder.handleLogMessage(mcpName2, params)
+      },
+      serverRequests: {
+        onCreateMessage: (params, opts) => this.forwardCreateMessage(params, opts),
+        onElicitInput: (params, opts) => this.forwardElicitInput(params, opts),
+        onListRoots: (params, opts) => this.forwardListRoots(params, opts)
+      }
+    };
+  }
+  /**
+   * Rebuilds the `ToolCatalog` from current state. Called whenever `toolsByMcp` or the
+   * lazy-registry membership changes — including initial connect, upstream-emitted
+   * `tools/list_changed`, and successful `loadMcp`.
+   */
+  rebuildToolCatalog() {
+    if (this.config.namespaced) {
+      this.toolCatalog = ToolCatalog.fromGroupedWithLazy(
+        this.toolsByMcp,
+        this.lazyRegistry.descriptions()
+      );
+    } else {
+      this.toolCatalog = ToolCatalog.fromFlat([...this.toolsByMcp.values()][0] ?? []);
+    }
   }
   get catalog() {
     if (this.toolCatalog === null) {
@@ -1285,7 +1640,9 @@ import {
 import { z as z3 } from "zod";
 var DISCOVER_TOOL_NAME = "discover_tool";
 var USE_TOOL_NAME = "use_tool";
+var LOAD_MCP_NAME = "load_mcp";
 var USE_TOOL_DESCRIPTION = "Use a tool that was previously discovered with the discover_tool tool.";
+var LOAD_MCP_DESCRIPTION = "Load a previously-deferred MCP server so that its tools, resources, and prompts become available. Pass the server name as shown in the <mcp_servers> block of the discover_tool description. Loading is permanent for the remainder of this session.";
 var DISCOVER_TOOL_INPUT_SCHEMA = {
   type: "object",
   properties: {
@@ -1301,11 +1658,19 @@ var USE_TOOL_INPUT_SCHEMA = {
   },
   required: ["tool_name"]
 };
+var LOAD_MCP_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    mcp_name: { type: "string" }
+  },
+  required: ["mcp_name"]
+};
 var DiscoverToolArgsSchema = z3.object({ tool_name: z3.string() });
 var UseToolArgsSchema = z3.object({
   tool_name: z3.string(),
   tool_input: z3.record(z3.string(), z3.unknown()).default({})
 });
+var LoadMcpArgsSchema = z3.object({ mcp_name: z3.string() });
 var ProxyServer = class {
   catalog;
   callTool;
@@ -1315,6 +1680,7 @@ var ProxyServer = class {
   complete;
   setLoggingLevelCallback;
   onRootsListChangedCallback;
+  loadMcpCallback;
   sdkServer = null;
   constructor({
     catalog,
@@ -1324,7 +1690,8 @@ var ProxyServer = class {
     prompts,
     complete,
     setLoggingLevel,
-    onRootsListChanged
+    onRootsListChanged,
+    loadMcp
   }) {
     this.catalog = catalog;
     this.callTool = callTool;
@@ -1334,6 +1701,7 @@ var ProxyServer = class {
     this.complete = complete;
     this.setLoggingLevelCallback = setLoggingLevel;
     this.onRootsListChangedCallback = onRootsListChanged;
+    this.loadMcpCallback = loadMcp;
   }
   buildServer() {
     const server = new Server(
@@ -1440,9 +1808,34 @@ var ProxyServer = class {
       await this.sdkServer.sendPromptListChanged();
     }
   }
+  /**
+   * Builds per-call options for a request handler. Extracts the host's
+   * `progressToken` from `_meta` (if any) and wires an `onprogress` callback that
+   * re-emits progress notifications back to the host under that same token. This
+   * is the single seam where progress translation lives — every forward-direction
+   * handler routes through here.
+   */
+  buildCallOptions(request, extra) {
+    const options = { signal: extra.signal };
+    const progressToken = request.params._meta?.progressToken;
+    if (progressToken !== void 0) {
+      options.onprogress = (progress) => {
+        void extra.sendNotification({
+          method: "notifications/progress",
+          params: {
+            progressToken,
+            progress: progress.progress,
+            total: progress.total,
+            message: progress.message
+          }
+        });
+      };
+    }
+    return options;
+  }
   registerToolHandlers(server) {
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-      tools: [
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+      const tools = [
         {
           name: DISCOVER_TOOL_NAME,
           description: this.catalog().discoverToolDescription,
@@ -1453,8 +1846,16 @@ var ProxyServer = class {
           description: USE_TOOL_DESCRIPTION,
           inputSchema: USE_TOOL_INPUT_SCHEMA
         }
-      ]
-    }));
+      ];
+      if (this.loadMcpCallback !== void 0) {
+        tools.push({
+          name: LOAD_MCP_NAME,
+          description: LOAD_MCP_DESCRIPTION,
+          inputSchema: LOAD_MCP_INPUT_SCHEMA
+        });
+      }
+      return { tools };
+    });
     server.setRequestHandler(
       CallToolRequestSchema,
       async (request, extra) => {
@@ -1473,7 +1874,30 @@ var ProxyServer = class {
               content: [{ type: "text", text: catalog.getToolDetails(args.tool_name) }]
             };
           }
-          return await this.callTool(args.tool_name, args.tool_input, { signal: extra.signal });
+          return await this.callTool(
+            args.tool_name,
+            args.tool_input,
+            this.buildCallOptions(request, extra)
+          );
+        }
+        if (name === LOAD_MCP_NAME && this.loadMcpCallback !== void 0) {
+          const args = LoadMcpArgsSchema.parse(rawArgs ?? {});
+          try {
+            const result = await this.loadMcpCallback(args.mcp_name);
+            return {
+              // The structured payload is JSON-serialized into a text block. We also
+              // populate `structuredContent` so MCP clients that prefer typed data can
+              // consume the same response without parsing the text body.
+              content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+              structuredContent: result
+            };
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+              isError: true,
+              content: [{ type: "text", text: message }]
+            };
+          }
         }
         return {
           isError: true,
@@ -1498,15 +1922,18 @@ var ProxyServer = class {
     server.setRequestHandler(
       ReadResourceRequestSchema,
       async (request, extra) => {
-        return callbacks.readResource(request.params.uri, { signal: extra.signal });
+        return callbacks.readResource(request.params.uri, this.buildCallOptions(request, extra));
       }
     );
     server.setRequestHandler(SubscribeRequestSchema, async (request, extra) => {
-      await callbacks.subscribeResource(request.params.uri, { signal: extra.signal });
+      await callbacks.subscribeResource(request.params.uri, this.buildCallOptions(request, extra));
       return {};
     });
     server.setRequestHandler(UnsubscribeRequestSchema, async (request, extra) => {
-      await callbacks.unsubscribeResource(request.params.uri, { signal: extra.signal });
+      await callbacks.unsubscribeResource(
+        request.params.uri,
+        this.buildCallOptions(request, extra)
+      );
       return {};
     });
   }
@@ -1520,9 +1947,11 @@ var ProxyServer = class {
     server.setRequestHandler(
       GetPromptRequestSchema,
       async (request, extra) => {
-        return callbacks.getPrompt(request.params.name, request.params.arguments, {
-          signal: extra.signal
-        });
+        return callbacks.getPrompt(
+          request.params.name,
+          request.params.arguments,
+          this.buildCallOptions(request, extra)
+        );
       }
     );
   }
@@ -1530,13 +1959,13 @@ var ProxyServer = class {
     server.setRequestHandler(
       CompleteRequestSchema,
       async (request, extra) => {
-        return callback(request.params, { signal: extra.signal });
+        return callback(request.params, this.buildCallOptions(request, extra));
       }
     );
   }
   registerLoggingHandler(server, callback) {
     server.setRequestHandler(SetLevelRequestSchema, async (request, extra) => {
-      await callback(request.params.level, { signal: extra.signal });
+      await callback(request.params.level, this.buildCallOptions(request, extra));
       return {};
     });
   }
@@ -1584,9 +2013,9 @@ function createTransport(config) {
 var SINGLE_MCP_NAME = "__default__";
 async function startProxy(command, args) {
   const transport = new StdioClientTransport2({ command, args });
-  const mcps = /* @__PURE__ */ new Map([[SINGLE_MCP_NAME, { transport }]]);
+  const eagerMcps = /* @__PURE__ */ new Map([[SINGLE_MCP_NAME, { transport }]]);
   const orchestrator = buildOrchestrator({
-    mcps,
+    eagerMcps,
     namespaced: false,
     transportErrorPrefix: () => "Upstream MCP"
   });
@@ -1594,12 +2023,19 @@ async function startProxy(command, args) {
 }
 async function startProxyFromConfig(options = {}) {
   const config = loadConfig(options);
-  const mcps = /* @__PURE__ */ new Map();
+  const eagerMcps = /* @__PURE__ */ new Map();
+  const lazyMcps = /* @__PURE__ */ new Map();
   for (const [name, entry] of Object.entries(config.mcp)) {
-    mcps.set(name, { transport: createTransport(entry) });
+    const transport = createTransport(entry);
+    if (entry.description !== void 0) {
+      lazyMcps.set(name, { transport, description: entry.description });
+    } else {
+      eagerMcps.set(name, { transport });
+    }
   }
   const orchestrator = buildOrchestrator({
-    mcps,
+    eagerMcps,
+    lazyMcps,
     namespaced: true,
     transportErrorPrefix: (mcpName2) => `Upstream MCP "${mcpName2}"`
   });
@@ -1608,7 +2044,8 @@ async function startProxyFromConfig(options = {}) {
 var activeShutdown = { shutdown: null };
 function buildOrchestrator(params) {
   return new Orchestrator({
-    mcps: params.mcps,
+    eagerMcps: params.eagerMcps,
+    lazyMcps: params.lazyMcps,
     namespaced: params.namespaced,
     onTransportError: (mcpName2, error) => {
       process6.stderr.write(
@@ -1657,7 +2094,10 @@ async function runProxy(orchestrator) {
     } : void 0,
     complete: orchestrator.capabilities.completions !== void 0 ? (params, options) => orchestrator.complete(params, options) : void 0,
     setLoggingLevel: orchestrator.capabilities.logging !== void 0 ? (level, options) => orchestrator.setLoggingLevel(level, options) : void 0,
-    onRootsListChanged: () => orchestrator.broadcastRootsListChanged()
+    onRootsListChanged: () => orchestrator.broadcastRootsListChanged(),
+    // Only register the `load_mcp` meta-tool when dynamic discovery is enabled —
+    // i.e. when the config declared at least one lazy upstream MCP.
+    loadMcp: orchestrator.hasDynamicDiscovery ? (mcpName2) => orchestrator.loadMcp(mcpName2) : void 0
   });
   orchestrator.setNotificationHandlers({
     onToolsListChanged: () => proxyServer.sendToolListChanged(),