pi-mcp-adapter 2.26.1 → 2.27.0

package/index.ts

@@ -1,10 +1,10 @@
 import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
-import type { DirectToolSpec, McpAdapterOptions, McpConfig, PromptMetadata } from "./types.ts";
+import type { DirectToolSpec, McpAdapterOptions, McpConfig, PromptMetadata, ServerEntry } from "./types.ts";
 import type { McpOAuthRuntime } from "./mcp-auth-flow.ts";
 import { Type } from "typebox";
 import type { TSchema } from "typebox";
-import { showStatus, showTools, showPrompts, reconnectServer, reconnectServers, authenticateServer, logoutServer, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
+import { showStatus, showTools, showPrompts, reconnectServer, reconnectServers, authenticateServer, logoutServer, manageBearerToken, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
 import { cloneMcpConfig, loadMcpConfig, writeProjectServerDisabledOverride } from "./config.ts";
 import { buildProxyDescription, createDirectToolExecutor, getMissingConfiguredDirectToolServers, resolveDirectTools } from "./direct-tools.ts";
 import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.ts";
@@ -22,6 +22,7 @@ import { runMcpScript } from "./mcp-code.ts";
 import { cleanupMaterializedBinaryResources } from "./tool-registrar.ts";
 
 export type { McpAdapterOptions } from "./types.ts";
+export type { ServerEntry } from "./types.ts";
 export {
   MCP_STATUS_EVENT,
   MCP_STATUS_SNAPSHOT_VERSION,
@@ -38,6 +39,14 @@ export {
 const INIT_WAIT_TIMEOUT_MS = 30_000;
 const INIT_WAIT_TIMED_OUT: unique symbol = Symbol("init-wait-timed-out");
 
+export interface McpServerRegistration {
+  dispose(): Promise<void>;
+}
+
+// Routes runtime registrations to the adapter installed for a specific Pi
+// instance, so a process with several adapters cannot cross-register.
+const runtimeRegistrars = new WeakMap<ExtensionAPI, (name: string, definition: ServerEntry) => McpServerRegistration>();
+
 async function awaitWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | typeof INIT_WAIT_TIMED_OUT> {
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
@@ -130,6 +139,19 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   let proxyToolRegistered = false;
   let proxyToolDescription: string | null = null;
   let directToolsFrozen = false;
+  // Session/runtime scoped server registrations from other extensions. They
+  // survive session restarts within this install and die with the process.
+  const runtimeServers = new Map<string, ServerEntry>();
+
+  // Mirrors init's per-server lifecycle registration so runtime servers get
+  // idle cleanup and keep-alive health recovery like configured servers.
+  function attachRuntimeServerLifecycle(targetState: McpExtensionState, name: string, definition: ServerEntry): void {
+    const lifecycleMode = definition.lifecycle ?? "lazy";
+    const persistsAfterFirstSpawn = lifecycleMode === "eager" || lifecycleMode === "lazy-keep-alive";
+    const idleOverride = definition.idleTimeout ?? (persistsAfterFirstSpawn ? 0 : undefined);
+    targetState.lifecycle.registerServer(name, definition, idleOverride !== undefined ? { idleTimeout: idleOverride } : undefined);
+    if (lifecycleMode === "keep-alive") targetState.lifecycle.markKeepAlive(name, definition);
+  }
 
   // OMP remaps `typebox` to a host shim that historically lacked Type.Unsafe.
   // Prefer Unsafe when present (real TypeBox / fixed OMP shim); otherwise pass
@@ -282,6 +304,45 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 
   registerPromptCommands(resolveCachedPrompts(earlyConfig));
 
+  runtimeRegistrars.set(pi, (name: string, definition: ServerEntry): McpServerRegistration => {
+    if (typeof name !== "string" || name.trim() === "") {
+      throw new Error("MCP server name must be a non-empty string");
+    }
+    if (typeof definition !== "object" || definition === null || Array.isArray(definition)) {
+      throw new Error(`MCP server definition for "${name}" must be an object`);
+    }
+    const effective = state?.config ?? earlyConfig;
+    if (runtimeServers.has(name) || Object.hasOwn(effective.mcpServers, name)) {
+      throw new Error(`MCP server "${name}" is already registered`);
+    }
+    // Runtime-registered servers are proxy-tool-only: direct tools are frozen
+    // at startup and must not be rebuilt for late registrations.
+    const entry: ServerEntry = { ...structuredClone(definition), directTools: false };
+    runtimeServers.set(name, entry);
+    const registeredState = state;
+    if (registeredState) {
+      registeredState.config.mcpServers[name] = entry;
+      attachRuntimeServerLifecycle(registeredState, name, entry);
+      syncToolSurface();
+      updateStatusBar(registeredState);
+    }
+    let disposed = false;
+    return {
+      dispose: async (): Promise<void> => {
+        if (disposed) return;
+        disposed = true;
+        runtimeServers.delete(name);
+        const currentState = state;
+        if (!currentState || currentState.config.mcpServers[name] !== entry) return;
+        delete currentState.config.mcpServers[name];
+        currentState.lifecycle.unregisterServer(name);
+        await currentState.manager.close(name);
+        syncToolSurface();
+        updateStatusBar(currentState);
+      },
+    };
+  });
+
   const getPiTools = (): ToolInfo[] => pi.getAllTools();
 
   pi.registerFlag("mcp-config", {
@@ -299,7 +360,6 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           }
         : {}),
       oauthRuntime,
-      statusEvents: pi.events,
     });
     initPromise = promise;
 
@@ -314,6 +374,14 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       }
 
       state = nextState;
+      for (const [name, definition] of runtimeServers) {
+        if (Object.hasOwn(nextState.config.mcpServers, name)) {
+          console.error(`MCP: runtime-registered server "${name}" now collides with a configured server; keeping the configured server`);
+          continue;
+        }
+        nextState.config.mcpServers[name] = definition;
+        attachRuntimeServerLifecycle(nextState, name, definition);
+      }
       nextState.onToolMetadataUpdated = (_serverName, _reason) => {
         if (state !== nextState || !owner.isActive()) return;
         syncPromptCommands();
@@ -325,6 +393,9 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       };
       syncPromptCommands();
       syncToolSurface(ctx);
+      // A connected snapshot is readiness-like external state. Publish it only
+      // after Pi's model-facing direct-tool surface reflects live metadata.
+      nextState.statusEvents = pi.events;
       updateStatusBar(nextState);
       initPromise = null;
       if (earlyConfig.settings?.freezeDirectTools === true) {
@@ -467,7 +538,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   // Re-flag returned MCP tool failures so pi registers them as errors (see toolErrorOverride).
   pi.on("tool_result", (event) => toolErrorOverride(event.details));
 
-  pi.registerCommand("mcp", {
+  const registerMcpCommand = (commandName: string) => pi.registerCommand(commandName, {
     description: "Show MCP server status",
     getArgumentCompletions: (prefix: string) => {
       const normalized = prefix.trimStart();
@@ -479,6 +550,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           { value: "prompts", label: "prompts — List all MCP prompts" },
           { value: "setup", label: "setup — Configure MCP servers" },
           { value: "logout", label: "logout — Clear server credentials" },
+          { value: "token", label: "token — Manage stored bearer tokens" },
           { value: "disable", label: "disable — Disable a server" },
           { value: "enable", label: "enable — Enable a server" },
           { value: "status", label: "status — Show server status" },
@@ -488,11 +560,27 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 
       const [, subcommand, argumentPrefix] = argumentMatch;
       if (
-        (subcommand !== "reconnect" && subcommand !== "logout" && subcommand !== "disable" && subcommand !== "enable")
+        (subcommand !== "reconnect" && subcommand !== "logout" && subcommand !== "disable" && subcommand !== "enable" && subcommand !== "token")
         || argumentPrefix === undefined
         || !state
       ) return null;
 
+      if (subcommand === "token") {
+        const tokenMatch = argumentPrefix.trimStart().match(/^(set|remove|status)\s+(.*)$/);
+        if (!tokenMatch) {
+          const actions = ["set", "remove", "status"]
+            .filter(action => action.startsWith(argumentPrefix.trimStart()))
+            .map(action => ({ value: `token ${action} `, label: `${action} — Bearer token ${action}` }));
+          return actions.length > 0 ? actions : null;
+        }
+        const action = tokenMatch[1] ?? "";
+        const serverPrefix = tokenMatch[2] ?? "";
+        const servers = Object.keys(state.config.mcpServers)
+          .filter(serverName => serverName.startsWith(serverPrefix.trimStart()))
+          .map(serverName => ({ value: `token ${action} ${serverName}`, label: serverName }));
+        return servers.length > 0 ? servers : null;
+      }
+
       const servers = Object.keys(state.config.mcpServers)
         .filter((serverName) => serverName.startsWith(argumentPrefix.trimStart()))
         .map((serverName) => ({ value: `${subcommand} ${serverName}`, label: serverName }));
@@ -568,6 +656,21 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           await logoutServer(serverName, state, commandCtx);
           break;
         }
+        case "token": {
+          const action = parts[1];
+          const serverName = parts.slice(2).join(" ");
+          if (action !== "set" && action !== "remove" && action !== "status") {
+            if (commandCtx.hasUI) commandCtx.ui?.notify("Usage: /mcp token set|remove|status <server>", "error");
+            return;
+          }
+          if (!serverName) {
+            if (commandCtx.hasUI) commandCtx.ui?.notify("Usage: /mcp token set|remove|status <server>", "error");
+            return;
+          }
+          commandOwner?.throwIfInactive();
+          await manageBearerToken(action, serverName, state, commandCtx);
+          break;
+        }
         case "disable":
         case "enable": {
           const serverName = rest;
@@ -618,6 +721,8 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       }
     },
   });
+  registerMcpCommand("mcp");
+  registerMcpCommand("pi-mcp");
 
   pi.registerCommand("mcp-auth", {
     description: "Authenticate with an MCP server (OAuth)",
@@ -782,6 +887,28 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           }
           return args as Record<string, unknown>;
         };
+        const validateNestedGatewayParams = (value: Record<string, unknown>): typeof params => {
+          for (const key of ["tool", "connect", "describe", "instructions", "search", "server", "action"] as const) {
+            if (value[key] !== undefined && typeof value[key] !== "string") {
+              throw new Error(`Invalid nested gateway param \`${key}\`: expected string, got ${Array.isArray(value[key]) ? "array" : typeof value[key]}`);
+            }
+          }
+          for (const key of ["regex", "includeSchemas"] as const) {
+            if (value[key] !== undefined && typeof value[key] !== "boolean") {
+              throw new Error(`Invalid nested gateway param \`${key}\`: expected boolean, got ${Array.isArray(value[key]) ? "array" : typeof value[key]}`);
+            }
+          }
+          for (const key of ["limit", "offset"] as const) {
+            if (value[key] !== undefined && typeof value[key] !== "number") {
+              throw new Error(`Invalid nested gateway param \`${key}\`: expected number, got ${Array.isArray(value[key]) ? "array" : typeof value[key]}`);
+            }
+          }
+          const args = value.args;
+          if (args !== undefined && typeof args !== "string" && (typeof args !== "object" || args === null || Array.isArray(args))) {
+            throw new Error(`Invalid nested gateway param \`args\`: expected JSON object or JSON string, got ${Array.isArray(args) ? "array" : args === null ? "null" : typeof args}`);
+          }
+          return value as typeof params;
+        };
         let parsedArgs = parseArgs(params.args);
         let dispatchParams = params;
         const hasGatewayMode = (value: typeof params): boolean =>
@@ -793,7 +920,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           || value.server !== undefined
           || value.action !== undefined;
         if (!hasGatewayMode(params) && parsedArgs) {
-          const nestedParams = parsedArgs as typeof params;
+          const nestedParams = validateNestedGatewayParams(parsedArgs);
           if (hasGatewayMode(nestedParams)) {
             dispatchParams = nestedParams;
             parsedArgs = parseArgs(nestedParams.args);
@@ -939,4 +1066,20 @@ export function createMcpAdapter(options: McpAdapterOptions = {}) {
   };
 }
 
+/**
+ * Register an MCP server with the adapter installed for this Pi instance.
+ * Registrations are session/runtime scoped and never persisted. Duplicate
+ * names fail closed. Registered servers are proxy-tool-only; their tools
+ * become visible at the next tool sync. To change a definition, dispose the
+ * registration and register again.
+ */
+export function registerMcpServer(options: { pi: ExtensionAPI; name: string; definition: ServerEntry }): McpServerRegistration {
+  const { pi, name, definition } = options;
+  const register = runtimeRegistrars.get(pi);
+  if (!register) {
+    throw new Error("pi-mcp-adapter is not installed for this Pi instance");
+  }
+  return register(name, definition);
+}
+
 export default createMcpAdapter();

package/init.ts

@@ -1,12 +1,13 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
-import { formatToolName, isServerDisabled, resolveToolPrefix, type McpAdapterOptions, type PromptMetadata, type ToolMetadata } from "./types.ts";
+import { formatToolName, isServerDisabled, resolveToolPrefix, type McpAdapterOptions, type PromptMetadata, type ToolMetadata, type ToolSelectorCandidateIndex } from "./types.ts";
 import { existsSync } from "node:fs";
 import { cloneMcpConfig, loadMcpConfig } from "./config.ts";
 import { ConsentManager } from "./consent-manager.ts";
 import { McpLifecycleManager } from "./lifecycle.ts";
 import {
   computeServerHash,
+  createCachedToolSelectorCandidateIndex,
   getMetadataCachePath,
   getMissingConfiguredDirectToolServers,
   isServerCacheValid,
@@ -239,6 +240,7 @@ export async function initializeMcp(
   }
 
   const prefix = config.settings?.toolPrefix ?? "server";
+  let cachedSelectorCandidateIndex: ToolSelectorCandidateIndex | undefined;
 
   for (const [name, definition] of serverEntries) {
     const lifecycleMode = definition.lifecycle ?? "lazy";
@@ -255,7 +257,13 @@ export async function initializeMcp(
 
     const cachedEntry = cache?.servers?.[name];
     if (cachedEntry && isServerCacheValid(cachedEntry, definition)) {
-      const metadata = reconstructToolMetadata(name, cachedEntry, prefix, definition, config.mcpServers, cache ?? undefined);
+      const hasToolFilters =
+        (Array.isArray(definition.includeTools) && definition.includeTools.length > 0) ||
+        (Array.isArray(definition.excludeTools) && definition.excludeTools.length > 0);
+      if (hasToolFilters && !cachedSelectorCandidateIndex && cache) {
+        cachedSelectorCandidateIndex = createCachedToolSelectorCandidateIndex(config.mcpServers, cache, prefix);
+      }
+      const metadata = reconstructToolMetadata(name, cachedEntry, prefix, definition, config.mcpServers, cache ?? undefined, cachedSelectorCandidateIndex);
       toolMetadata.set(name, metadata);
       if (Array.isArray(cachedEntry.resources)) {
         resourceCounts.set(name, cachedEntry.resources.length);

package/lifecycle.ts

@@ -73,6 +73,14 @@ export class McpLifecycleManager {
     if (settings?.idleTimeout !== undefined) this.serverSettings.set(name, settings);
   }
 
+  unregisterServer(name: string): void {
+    this.allServers.delete(name);
+    this.keepAliveServers.delete(name);
+    this.serverSettings.delete(name);
+    this.retryStates.delete(name);
+    this.pendingMetadataPublications.delete(name);
+  }
+
   setGlobalIdleTimeout(minutes: number): void {
     this.globalIdleTimeout = minutes * 60 * 1000;
   }
@@ -155,6 +163,10 @@ export class McpLifecycleManager {
     retrySuperseded = true,
   ): Promise<void> {
     if (isServerDisabled(definition) || this.stopped || signal?.aborted) return;
+    // Fence against unregisterServer racing an in-flight convergence pass.
+    // Identity comparison also rejects stale passes after a same-name
+    // replacement registration, which a name check would wrongly accept.
+    if (this.keepAliveServers.get(name) !== definition) return;
     const connection = this.manager.getConnection(name);
     if (connection?.status === "needs-auth") {
       this.pendingMetadataPublications.delete(name);
@@ -171,17 +183,18 @@ export class McpLifecycleManager {
         freshConnection = await this.manager.connect(name, definition, signal);
       } catch (error) {
         if (this.stopped || signal?.aborted) return;
-        this.reportConnectionFailure(name, error, "reconnect", this.manager.getConnection(name));
+        this.reportConnectionFailure(name, definition, error, "reconnect", this.manager.getConnection(name));
         return;
       }
       if (this.stopped || signal?.aborted) return;
       if (freshConnection.status === "needs-auth") {
-        await this.notifyAuthRequired(name);
+        await this.notifyAuthRequired(name, definition, freshConnection);
         return;
       }
       if (freshConnection.status !== "connected") {
         this.reportConnectionFailure(
           name,
+          definition,
           new Error(`MCP server ${name} did not return a connected session`),
           "reconnect",
           freshConnection,
@@ -189,12 +202,12 @@ export class McpLifecycleManager {
         return;
       }
       logger.debug(`Reconnected to ${name}`);
-      await this.publishConnectedMetadata(name, freshConnection);
+      await this.publishConnectedMetadata(name, definition, freshConnection);
       return;
     }
 
     if (this.pendingMetadataPublications.has(name)) {
-      await this.publishConnectedMetadata(name, connection);
+      await this.publishConnectedMetadata(name, definition, connection);
       return;
     }
     if (!definition.url) return;
@@ -210,7 +223,7 @@ export class McpLifecycleManager {
         return;
       }
       if (!shouldReconnectAfterRefresh(error, hadSessionId)) {
-        this.reportConnectionFailure(name, error, "refresh", connection);
+        this.reportConnectionFailure(name, definition, error, "refresh", connection);
         return;
       }
       if (this.hasPendingAuthForServer(name)) {
@@ -222,17 +235,18 @@ export class McpLifecycleManager {
         freshConnection = await this.manager.reconnect(name, definition, connection, signal);
       } catch (reconnectError) {
         if (this.stopped || signal?.aborted) return;
-        this.reportConnectionFailure(name, reconnectError, "reconnect", this.manager.getConnection(name));
+        this.reportConnectionFailure(name, definition, reconnectError, "reconnect", this.manager.getConnection(name));
         return;
       }
       if (this.stopped || signal?.aborted) return;
       if (freshConnection.status === "needs-auth") {
-        await this.notifyAuthRequired(name);
+        await this.notifyAuthRequired(name, definition, freshConnection);
         return;
       }
       if (freshConnection.status !== "connected") {
         this.reportConnectionFailure(
           name,
+          definition,
           new Error(`MCP server ${name} did not return a connected session`),
           "reconnect",
           freshConnection,
@@ -240,7 +254,7 @@ export class McpLifecycleManager {
         return;
       }
       logger.debug(`Reconnected stale MCP session for ${name}`);
-      await this.publishConnectedMetadata(name, freshConnection);
+      await this.publishConnectedMetadata(name, definition, freshConnection);
       return;
     }
 
@@ -248,6 +262,11 @@ export class McpLifecycleManager {
       await this.handleSupersededConnection(name, definition, connection, signal, retrySuperseded);
       return;
     }
+    if (refreshResult === "refresh-timeout") {
+      this.deferRefreshTimeout(name, definition, connection);
+      return;
+    }
+    if (this.keepAliveServers.get(name) !== definition) return;
     if (this.retryStates.delete(name)) {
       await this.onHealthRestored?.(name);
     }
@@ -261,16 +280,17 @@ export class McpLifecycleManager {
     retrySuperseded: boolean,
   ): Promise<void> {
     const current = this.manager.getConnection(name);
+    if (this.keepAliveServers.get(name) !== definition) return;
     if (current === staleConnection && current.status === "connected") {
       if (this.retryStates.delete(name)) await this.onHealthRestored?.(name);
       return;
     }
     if (current?.status === "connected") {
-      await this.publishConnectedMetadata(name, current);
+      await this.publishConnectedMetadata(name, definition, current);
       return;
     }
     if (current?.status === "needs-auth") {
-      await this.notifyAuthRequired(name);
+      await this.notifyAuthRequired(name, definition, current);
       return;
     }
     if (retrySuperseded) {
@@ -278,7 +298,15 @@ export class McpLifecycleManager {
     }
   }
 
-  private async publishConnectedMetadata(name: string, connection: ServerConnection): Promise<void> {
+  private async publishConnectedMetadata(name: string, definition: ServerDefinition, connection: ServerConnection): Promise<void> {
+    // Fence stale convergence passes by definition identity so disposal, and
+    // disposal followed by a same-name replacement, never re-track this
+    // server. Close the pass's own connection only when it is still current,
+    // so a replacement's connection is never touched.
+    if (this.keepAliveServers.get(name) !== definition) {
+      if (this.manager.getConnection(name) === connection) await this.manager.close(name);
+      return;
+    }
     this.pendingMetadataPublications.add(name);
     try {
       await this.onReconnect?.(name);
@@ -286,11 +314,19 @@ export class McpLifecycleManager {
       this.retryStates.delete(name);
     } catch (error) {
       if (this.stopped) return;
-      this.reportConnectionFailure(name, error, "publish", connection);
+      this.reportConnectionFailure(name, definition, error, "publish", connection);
     }
   }
 
-  private async notifyAuthRequired(name: string): Promise<void> {
+  private async notifyAuthRequired(name: string, definition: ServerDefinition, connection: ServerConnection): Promise<void> {
+    // Fence stale convergence passes by definition identity. Close the
+    // leftover needs-auth connection only while it is still the manager's
+    // current entry, so a replacement's connection is never touched and the
+    // stale client/transport cannot leak when a replacement connects later.
+    if (this.keepAliveServers.get(name) !== definition) {
+      if (this.manager.getConnection(name) === connection) await this.manager.close(name);
+      return;
+    }
     this.pendingMetadataPublications.delete(name);
     this.retryStates.delete(name);
     try {
@@ -313,10 +349,39 @@ export class McpLifecycleManager {
 
   private reportConnectionFailure(
     name: string,
+    definition: ServerDefinition,
     error: unknown,
     action: "refresh" | "reconnect" | "publish",
     connection: ServerConnection | undefined,
   ): void {
+    if (!this.recordRetry(name, definition, connection)) return;
+    this.onReconnectFailure?.(name, error);
+    const message = error instanceof Error ? error.message : String(error);
+    const target = action === "reconnect"
+      ? `reconnect to ${name}`
+      : action === "publish"
+        ? `publish metadata for ${name}`
+        : `refresh ${name}`;
+    console.error(`MCP: Failed to ${target}: ${sanitizeTerminalText(message)}`);
+  }
+
+  private deferRefreshTimeout(
+    name: string,
+    definition: ServerDefinition,
+    connection: ServerConnection | undefined,
+  ): void {
+    if (!this.recordRetry(name, definition, connection)) return;
+    logger.debug(`MCP: keep-alive tools/list refresh timed out for ${name}; retrying after backoff`);
+  }
+
+  private recordRetry(
+    name: string,
+    definition: ServerDefinition,
+    connection: ServerConnection | undefined,
+  ): boolean {
+    // Do not recreate retry/failure state from a stale convergence pass after
+    // disposal or a same-name replacement registration.
+    if (this.keepAliveServers.get(name) !== definition) return false;
     const attempts = (this.retryStates.get(name)?.attempts ?? 0) + 1;
     const delay = Math.min(
       KEEP_ALIVE_RETRY_BASE_MS * 2 ** Math.min(attempts - 1, 10),
@@ -328,14 +393,7 @@ export class McpLifecycleManager {
       connection,
       status: connection?.status,
     });
-    this.onReconnectFailure?.(name, error);
-    const message = error instanceof Error ? error.message : String(error);
-    const target = action === "reconnect"
-      ? `reconnect to ${name}`
-      : action === "publish"
-        ? `publish metadata for ${name}`
-        : `refresh ${name}`;
-    console.error(`MCP: Failed to ${target}: ${sanitizeTerminalText(message)}`);
+    return true;
   }
 
   private getIdleTimeout(name: string): number {

package/mcp-auth-flow.ts

@@ -18,6 +18,7 @@ import {
   waitForCallback,
   cancelPendingCallback,
   stopCallbackServer,
+  stopCallbackServerIfIdle,
   releaseCallbackServer,
 } from "./mcp-callback-server.ts"
 import {
@@ -387,7 +388,7 @@ export async function startAuth(
   } catch (error) {
     releaseCallbackServer(oauthState)
     try {
-      await clearOAuthState(serverName, authStorageOptions)
+      await cleanupAndReleaseCallbackServerIfIdle(() => clearOAuthState(serverName, authStorageOptions))
     } catch (cleanupError) {
       throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed")
     }
@@ -429,6 +430,7 @@ export async function startAuth(
       authProvider.deactivate()
       releaseCallbackServer(oauthState)
       await clearOAuthState(serverName, authStorageOptions)
+      await stopCallbackServerIfIdle()
       return { authorizationUrl: "" }
     }
     if (!capturedUrl) {
@@ -439,7 +441,7 @@ export async function startAuth(
   } catch (error) {
     authProvider.deactivate()
     try {
-      await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions)
+      await clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, authStorageOptions)
     } catch (cleanupError) {
       throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed")
     }
@@ -463,7 +465,7 @@ async function setPendingAuth(
   state.pendingAuths.set(key, pendingAuth)
   state.pendingAuthStates.set(key, oauthState)
   const cleanupTimer = setTimeout(() => {
-    void clearPendingAuth(runtime, serverName, oauthState, pendingAuth.authStorageOptions).catch(error => {
+    void clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, pendingAuth.authStorageOptions).catch(error => {
       console.error(`MCP Auth: Timed-out flow cleanup failed: ${formatTerminalError(error)}`)
     })
   }, MANUAL_AUTH_TIMEOUT_MS)
@@ -498,6 +500,37 @@ async function clearPendingAuth(runtime: McpOAuthRuntime, serverName: string, oa
   }
 }
 
+async function clearPendingAuthAndReleaseIfIdle(
+  runtime: McpOAuthRuntime,
+  serverName: string,
+  oauthState: string | undefined,
+  fallbackStorageOptions: AuthStorageOptions = {},
+): Promise<void> {
+  await cleanupAndReleaseCallbackServerIfIdle(
+    () => clearPendingAuth(runtime, serverName, oauthState, fallbackStorageOptions),
+  )
+}
+
+async function cleanupAndReleaseCallbackServerIfIdle(cleanup: () => void | Promise<void>): Promise<void> {
+  let cleanupFailure: { error: unknown } | undefined
+  try {
+    await cleanup()
+  } catch (error) {
+    cleanupFailure = { error }
+  }
+
+  try {
+    await stopCallbackServerIfIdle()
+  } catch (releaseError) {
+    if (cleanupFailure) {
+      throw new AggregateError([cleanupFailure.error, releaseError], "OAuth callback cleanup failed")
+    }
+    throw releaseError
+  }
+
+  if (cleanupFailure) throw cleanupFailure.error
+}
+
 function getSearchParamsFromInput(input: string): URLSearchParams | undefined {
   try {
     const url = new URL(input)
@@ -701,7 +734,7 @@ export async function completeAuth(
   } finally {
     if (!keepPendingForRetry) {
       try {
-        await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions)
+        await clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, authStorageOptions)
       } catch (cleanupError) {
         if (caughtError !== undefined) {
           throw new AggregateError([caughtError, cleanupError], "OAuth completion cleanup failed")
@@ -801,7 +834,7 @@ export async function authenticate(
     } catch (error) {
       if (oauthState) cancelPendingCallback(oauthState)
       try {
-        await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions)
+        await clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, authStorageOptions)
       } catch (cleanupError) {
         throw new AggregateError([error, cleanupError], "OAuth cancellation cleanup failed")
       }
@@ -922,7 +955,7 @@ export async function removeAuth(serverName: string, options: AuthenticateOption
   if (oauthState) {
     cancelPendingCallback(oauthState)
   }
-  await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions)
+  await clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, authStorageOptions)
   throwIfAborted(signal)
   clearAllCredentials(serverName, authStorageOptions)
   await clearOAuthState(serverName, authStorageOptions)