@gajae-code/coding-agent 0.17.2 → 0.17.5

package/src/runtime-mcp/manager.ts

@@ -35,6 +35,7 @@ import {
 	MCPPoolLeaseReleaseError,
 } from "./pool";
 import type { MCPProtocolObservation } from "./protocol";
+import { DEFAULT_MCP_STARTUP_WAIT_MS, MAX_MCP_STARTUP_WAIT_MS, MCP_STARTUP_WAIT_GRACE_MS } from "./startup-policy";
 import type { MCPToolDetails } from "./tool-bridge";
 import { DeferredMCPTool, MCPTool } from "./tool-bridge";
 import type { MCPToolCache } from "./tool-cache";
@@ -51,7 +52,7 @@ import type {
 	MCPServerConnection,
 	MCPToolDefinition,
 } from "./types";
-import { MCPExpectedFailure, MCPNotificationMethods } from "./types";
+import { MCPExpectedFailure, MCPHttpRequestError, MCPJsonRpcError, MCPNotificationMethods } from "./types";
 
 type ToolLoadResult = {
 	connection: MCPServerConnection;
@@ -101,16 +102,23 @@ type RetiredLeaseRelease = {
 	promise: Promise<void>;
 };
 
-const STARTUP_TIMEOUT_MS = 250;
-const STARTUP_TIMEOUT_GRACE_MS = 500;
+const STARTUP_TIMEOUT_MS = DEFAULT_MCP_STARTUP_WAIT_MS;
+const STARTUP_TIMEOUT_GRACE_MS = MCP_STARTUP_WAIT_GRACE_MS;
 /**
  * Default ceiling on how long `discoverAndConnect` waits for a server batch to
  * come up. Deliberately short: a config with a large `timeout` must not be able
  * to hang ordinary startup. ACP lifecycle launches carry their own, larger
  * budget derived from the readiness deadline (see `maxStartupTimeoutMs`).
  */
-const MAX_STARTUP_TIMEOUT_MS = 1_750;
+const MAX_STARTUP_TIMEOUT_MS = MAX_MCP_STARTUP_WAIT_MS;
 const DEFAULT_EXACT_CONFIG_STARTUP_TIMEOUT_MS = 30_000;
+const MCP_STARTUP_TIMEOUT_PREFIX = "MCP server connection timed out during startup:";
+
+export function isMCPStartupTimeoutError(error: unknown): boolean {
+	return typeof error === "string"
+		? error.startsWith(MCP_STARTUP_TIMEOUT_PREFIX)
+		: error instanceof Error && error.message.startsWith(MCP_STARTUP_TIMEOUT_PREFIX);
+}
 
 export function resolveStartupTimeoutMs(configs: MCPServerConfig[], maxStartupTimeoutMs?: number): number {
 	const ceiling =
@@ -150,6 +158,24 @@ export function withinDeclaredConnectionWindow(config: MCPServerConfig, elapsedM
 	return elapsedMs < timeout;
 }
 
+/** Keep startup logs bounded and free of remote response text. */
+function classifyMCPStartupFailure(error: unknown): string {
+	if (error instanceof MCPExpectedFailure) {
+		return error.cause === undefined ? "expected-mcp-failure" : classifyMCPStartupFailure(error.cause);
+	}
+	if (error instanceof MCPHttpRequestError) {
+		return Number.isInteger(error.status) && error.status >= 100 && error.status <= 599
+			? `http-status:${error.status}`
+			: "http-request-error";
+	}
+	if (error instanceof MCPJsonRpcError) {
+		return Number.isInteger(error.code) && Math.abs(error.code) <= 1_000_000
+			? `json-rpc-code:${error.code}`
+			: "json-rpc-error";
+	}
+	return "transport-error";
+}
+
 function trackPromise<T>(promise: Promise<T>): TrackedPromise<T> {
 	const tracked: TrackedPromise<T> = { promise, status: "pending" };
 	promise.then(
@@ -260,6 +286,22 @@ export interface MCPLoadResult {
 	exaApiKeys: string[];
 }
 
+export type MCPToolCatalogPublication = "unpublished" | "published" | "fenced";
+
+/**
+ * Atomic view of the manager's fenced tool catalog and its publication state.
+ *
+ * `unpublished` is reserved for the initial deferred window where no manager
+ * catalog has been published and no exact control is fencing it. An empty
+ * `published` or `fenced` catalog is authoritative and must not be replaced
+ * with an in-flight discovery result.
+ */
+export interface MCPToolCatalogSnapshot {
+	tools: CustomTool<TSchema, MCPToolDetails>[];
+	publication: MCPToolCatalogPublication;
+	generation: number;
+}
+
 /** Options for discovering and connecting to MCP servers */
 export interface MCPDiscoverOptions {
 	/** Whether to load project-level config (default: true) */
@@ -288,10 +330,10 @@ export interface MCPManagerOptions {
 	/** Restrict this instance to tools from an explicit MCP config. */
 	toolsOnly?: boolean;
 	/**
-	 * Ceiling for the startup wait, in milliseconds. Only ACP lifecycle launches
-	 * set this, so a slow ACP MCP handshake gets the readiness budget while every
-	 * other consumer keeps the short default. Non-positive or non-finite values
-	 * are ignored and the default applies.
+	 * Ceiling for the startup wait, in milliseconds. ACP lifecycle launches and
+	 * plugin MCP startup use bounded caller-owned budgets; other consumers keep
+	 * the short default. Non-positive or non-finite values are ignored and the
+	 * default applies.
 	 */
 	maxStartupTimeoutMs?: number;
 	/** Connection pool used for every physical MCP open/close. */
@@ -300,12 +342,49 @@ export interface MCPManagerOptions {
 	sessionId?: string;
 	/** Idle retention for shared pool entries. */
 	sharedPoolIdleMs?: number;
+	/** Limit tool-cache reads and writes to this manager's conventional servers. */
+	toolCacheServerNames?: ReadonlySet<string>;
 	/** Test seam for deterministic reconnect backoff scheduling. */
 	sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
 	/** Test seam for fencing the acquisition-to-registration replacement race. */
 	afterLeaseAcquiredForTests?: (name: string, lease: MCPPoolLease) => void | Promise<void>;
 }
 
+export type ExactMcpServerControlStatus =
+	| "suspended"
+	| "already-suspended"
+	| "resumed"
+	| "not-suspended"
+	| "reconnected"
+	| "unavailable"
+	| "unknown-server";
+
+export interface ExactMcpServerControlResult {
+	readonly name: string;
+	readonly status: ExactMcpServerControlStatus;
+	readonly toolCount: number;
+}
+
+/**
+ * A staged catalog the caller can validate against before it is published.
+ * `commit` is the single publication point; `abort` releases anything the
+ * preparation opened and leaves the manager on its predecessor.
+ */
+export interface PreparedExactMcpCatalog {
+	readonly tools: CustomTool<TSchema, MCPToolDetails>[];
+	canCommit(): boolean;
+	commit(): Promise<void>;
+	abort(): Promise<void>;
+}
+
+export interface PreparedExactMcpServerControl extends PreparedExactMcpCatalog {
+	readonly result: ExactMcpServerControlResult;
+	/** Validate a resumed replacement before an atomic multi-server publication. */
+	precommit?(): void;
+	/** Publish after every replacement in the catalog has passed precommit. */
+	publish?(): void;
+}
+
 /**
  * MCP Server Manager.
  *
@@ -342,6 +421,8 @@ export class MCPManager {
 	readonly #retiredLeaseReleases = new Set<RetiredLeaseRelease>();
 	#nextScopedOperationId = 1;
 	#tools: CustomTool<TSchema, MCPToolDetails>[] = [];
+	#toolCatalogGeneration = 0;
+	#toolCatalogPublished = false;
 	#pendingConnections = new Map<string, Promise<MCPServerConnection>>();
 	#pendingConnectionControllers = new Map<string, AbortController>();
 	#pendingToolLoads = new Map<string, Promise<ToolLoadResult>>();
@@ -351,7 +432,8 @@ export class MCPManager {
 	#authStorage: AuthStorage | null = null;
 	#inputRequestHandler: MCPInputRequestHandler | null = null;
 	#onNotification?: (serverName: string, method: string, params: unknown) => void;
-	#onToolsChanged?: (tools: CustomTool<TSchema, MCPToolDetails>[]) => void;
+	#onToolsChanged?: (tools: readonly Readonly<CustomTool<TSchema, MCPToolDetails>>[]) => void;
+	readonly #toolChangeListeners = new Set<(tools: readonly Readonly<CustomTool<TSchema, MCPToolDetails>>[]) => void>();
 	#onResourcesChanged?: (serverName: string, uri: string) => void;
 	#onPromptsChanged?: (serverName: string) => void;
 	#notificationsEnabled = false;
@@ -365,18 +447,33 @@ export class MCPManager {
 	#reconnectBackoffs = new Map<string, AbortController>();
 	/** Preserved configs for reconnection after connection loss. */
 	#serverConfigs = new Map<string, MCPServerConfig>();
+	// Exact MCP replacements retain cleanup ownership and cancel in-flight candidates.
+	/** Session-local operator suppression; never persisted to MCP config. */
+	#suppressedServers = new Set<string>();
+	/** Prepare-phase fence that prevents a concurrent close/rebind publication. */
+	#pendingExactSuspensions = new Set<string>();
+	/** Single per-server candidate axis shared against automatic reconnect. */
+	#pendingExactControlServers = new Set<string>();
 	/** Monotonic epoch incremented on disconnectAll to invalidate stale reconnections. */
 	#epoch = 0;
 	#scopedLifecycle: "open" | "disconnecting" | "reconnecting" = "open";
 	#scopedLifecycleEpoch = 0;
 	readonly #toolsOnly: boolean;
+	#toolCacheServerNames: Set<string> | undefined;
 	#toolsOnlyConfigLoaded = false;
+	#connectionSetMutationBlocked = false;
 	#connectionSetSealed = false;
 
 	#serverError(message: string): string {
 		return this.#toolsOnly ? "MCP server unavailable" : message;
 	}
 
+	#shouldCacheServerTools(name: string): boolean {
+		return (
+			this.toolCache !== null && (this.#toolCacheServerNames === undefined || this.#toolCacheServerNames.has(name))
+		);
+	}
+
 	#removePendingAcquireCleanup(name: string, error: MCPPoolAcquireAbortError): void {
 		const pending = this.#pendingAcquireCleanups.get(name);
 		pending?.delete(error);
@@ -480,13 +577,27 @@ export class MCPManager {
 		return this.#scopedLifecycleEpoch;
 	}
 	#assertConnectionSetMutable(): void {
-		if (this.#connectionSetSealed) throw new Error("MCP manager connection set is sealed");
+		if (this.#connectionSetMutationBlocked) {
+			throw new Error(
+				this.#connectionSetSealed ? "MCP manager connection set is sealed" : "MCP manager connection set is frozen",
+			);
+		}
+	}
+
+	/** Block config mutations and reloads while keeping existing servers reconnectable. */
+	freezeConnectionSet(): void {
+		this.#connectionSetMutationBlocked = true;
 	}
 
 	sealConnectionSet(): void {
+		this.freezeConnectionSet();
 		this.#connectionSetSealed = true;
 	}
 
+	isConnectionSetMutationBlocked(): boolean {
+		return this.#connectionSetMutationBlocked;
+	}
+
 	isConnectionSetSealed(): boolean {
 		return this.#connectionSetSealed;
 	}
@@ -539,7 +650,11 @@ export class MCPManager {
 	}
 
 	#scheduleSharedRebind(name: string, lease: MCPPoolLease): void {
-		if (this.#scopedLifecycle === "disconnecting") return;
+		if (this.#pendingExactSuspensions.has(name) || this.#pendingExactControlServers.has(name)) {
+			this.#queueDeferredSharedRebind(name, lease, this.#epoch);
+			return;
+		}
+		if (this.#scopedLifecycle === "disconnecting" || this.#suppressedServers.has(name)) return;
 		const active = this.#activeSharedRebinds.get(name);
 		if (active) {
 			if (active.lease !== lease) this.#queueDeferredSharedRebind(name, lease, this.#epoch);
@@ -562,6 +677,15 @@ export class MCPManager {
 	#drainDeferredSharedRebinds(): void {
 		if (this.#scopedLifecycle !== "open" || this.#deferredSharedRebinds.size === 0) return;
 		for (const [name, pending] of this.#deferredSharedRebinds.entries()) {
+			// A suspended or in-flight control still owns this server. Keep the newest
+			// replacement queued so the manager rebinds after suppression clears instead
+			// of staying bound to a retired pool generation.
+			if (
+				this.#suppressedServers.has(name) ||
+				this.#pendingExactSuspensions.has(name) ||
+				this.#pendingExactControlServers.has(name)
+			)
+				continue;
 			if (pending.managerEpoch !== this.#epoch) {
 				this.#deferredSharedRebinds.delete(name);
 				continue;
@@ -614,7 +738,14 @@ export class MCPManager {
 					this.#handleServerNotification(name, event.method, event.params);
 					return;
 				}
-				if (event.type !== "close" || this.#connectionSetSealed) return;
+				if (
+					event.type !== "close" ||
+					this.#connectionSetSealed ||
+					this.#suppressedServers.has(name) ||
+					this.#pendingExactSuspensions.has(name) ||
+					this.#pendingExactControlServers.has(name)
+				)
+					return;
 				void this.reconnectServer(name);
 			}),
 		);
@@ -622,7 +753,12 @@ export class MCPManager {
 
 	async #rebindAfterSharedRestart(name: string, lease: MCPPoolLease): Promise<void> {
 		const managerEpoch = this.#epoch;
-		if (this.#scopedLifecycle === "disconnecting") return;
+		if (
+			this.#scopedLifecycle === "disconnecting" ||
+			this.#pendingExactSuspensions.has(name) ||
+			this.#pendingExactControlServers.has(name)
+		)
+			return;
 		if (this.#scopedLifecycle === "reconnecting") {
 			this.#queueDeferredSharedRebind(name, lease, managerEpoch);
 			return;
@@ -858,6 +994,7 @@ export class MCPManager {
 		options: MCPManagerOptions = {},
 	) {
 		this.#toolsOnly = options.toolsOnly === true;
+		this.#toolCacheServerNames = options.toolCacheServerNames ? new Set(options.toolCacheServerNames) : undefined;
 		this.#maxStartupTimeoutMs = options.maxStartupTimeoutMs;
 		this.#sleep = options.sleep ?? delay;
 		this.#afterLeaseAcquiredForTests = options.afterLeaseAcquiredForTests;
@@ -879,13 +1016,46 @@ export class MCPManager {
 	}
 
 	/**
-	 * Set a callback to fire when any server's tools change.
+	 * Set a callback to receive a read-only catalog snapshot when server tools change.
 	 */
-	setOnToolsChanged(handler: (tools: CustomTool<TSchema, MCPToolDetails>[]) => void): void {
+	setOnToolsChanged(handler: (tools: readonly Readonly<CustomTool<TSchema, MCPToolDetails>>[]) => void): void {
 		if (this.#toolsOnly) return;
 		this.#onToolsChanged = handler;
 	}
 
+	/** Subscribe to readonly catalog snapshots without replacing the manager owner's callback. */
+	subscribeToToolsChanged(
+		handler: (tools: readonly Readonly<CustomTool<TSchema, MCPToolDetails>>[]) => void,
+	): () => void {
+		if (this.#toolsOnly) return () => {};
+		this.#toolChangeListeners.add(handler);
+		return () => {
+			this.#toolChangeListeners.delete(handler);
+		};
+	}
+
+	#notifyToolsChanged(): void {
+		const listeners = [...this.#toolChangeListeners];
+		// Keep live MCPTool instances for reconnect behavior, but never expose the
+		// manager-owned array; callback types make their tool descriptors readonly.
+		const snapshot = this.#onToolsChanged || listeners.length > 0 ? Object.freeze([...this.#tools]) : undefined;
+		if (snapshot && this.#onToolsChanged) {
+			try {
+				this.#onToolsChanged(snapshot);
+			} catch (error) {
+				logger.warn("MCP tool catalog owner callback failed", { error: classifyMCPStartupFailure(error) });
+			}
+		}
+		if (!snapshot) return;
+		for (const listener of listeners) {
+			try {
+				listener(snapshot);
+			} catch (error) {
+				logger.warn("MCP tool catalog listener failed", { error: classifyMCPStartupFailure(error) });
+			}
+		}
+	}
+
 	/**
 	 * Set a callback to fire when any server's resources change.
 	 */
@@ -1014,6 +1184,11 @@ export class MCPManager {
 			nativeOnly: options?.nativeOnly,
 			configPath: options?.configPath,
 		});
+		if (this.#toolCacheServerNames !== undefined) {
+			this.#toolCacheServerNames = new Set(
+				Object.keys(configs).filter(name => sources[name]?.provider !== "gjc-plugins"),
+			);
+		}
 		const result = await this.#connectServers(configs, sources, options?.onConnecting);
 		if (configurationWarning) result.errors.set("$config", "MCP configuration unavailable");
 		result.exaApiKeys = exaApiKeys;
@@ -1067,6 +1242,13 @@ export class MCPManager {
 					"MCP connection cleanup pending";
 				errors.set(name, this.#serverError(message));
 				reportedErrors.add(name);
+				if (!this.#toolsOnly) {
+					logger.warn("Skipping MCP autoload registration", {
+						path: `mcp:${name}`,
+						serverName: name,
+						reason: message,
+					});
+				}
 				continue;
 			}
 			if (sources[name]) {
@@ -1080,11 +1262,14 @@ export class MCPManager {
 			// Skip if already connected.
 			if (this.#connections.has(name)) {
 				connectedServers.add(name);
-				allTools.push(
-					...this.#tools.filter(
-						tool => (tool instanceof MCPTool || tool instanceof DeferredMCPTool) && tool.mcpServerName === name,
-					),
-				);
+				if (this.#isExactToolPublicationAllowed(name)) {
+					allTools.push(
+						...this.#tools.filter(
+							tool =>
+								(tool instanceof MCPTool || tool instanceof DeferredMCPTool) && tool.mcpServerName === name,
+						),
+					);
+				}
 				continue;
 			}
 
@@ -1093,14 +1278,29 @@ export class MCPManager {
 				this.#pendingToolLoads.has(name) ||
 				this.#pendingReconnections.has(name)
 			) {
+				if (!this.#toolsOnly) {
+					logger.warn("Skipping MCP autoload registration", {
+						path: `mcp:${name}`,
+						serverName: name,
+						reason: "connection already pending",
+					});
+				}
 				continue;
 			}
 
 			// Validate config
 			const validationErrors = validateServerConfig(name, config);
 			if (validationErrors.length > 0) {
-				errors.set(name, this.#serverError(validationErrors.join("; ")));
+				const reason = validationErrors.join("; ");
+				errors.set(name, this.#serverError(reason));
 				reportedErrors.add(name);
+				if (!this.#toolsOnly) {
+					logger.warn("Skipping MCP autoload registration", {
+						path: `mcp:${name}`,
+						serverName: name,
+						reason,
+					});
+				}
 				continue;
 			}
 
@@ -1237,22 +1437,31 @@ export class MCPManager {
 						return;
 					this.#pendingToolLoads.delete(name);
 					const reconnect = () => this.reconnectServer(name);
-					const customTools = MCPTool.fromTools(this.#connectionForLease(connection), serverTools, reconnect, {
-						noReplay: config.sharing === "shared",
-						inputHandler: () => this.#inputRequestHandler ?? undefined,
-					});
+					const customTools = MCPTool.fromTools(
+						this.#connectionForLease(connection),
+						serverTools,
+						reconnect,
+						this.#exactToolOptions(name, config.sharing === "shared"),
+					);
 					this.#replaceServerTools(name, customTools);
-					if (!this.#toolsOnly) this.#onToolsChanged?.(this.#tools);
-					if (!this.#toolsOnly) void this.toolCache?.set(name, config, serverTools);
+					if (!this.#toolsOnly) this.#notifyToolsChanged();
+					if (!this.#toolsOnly && this.#shouldCacheServerTools(name))
+						void this.toolCache?.set(name, config, serverTools);
 					if (!this.#toolsOnly) await this.#loadServerResourcesAndPrompts(name, connection);
 				})
 				.catch(error => {
 					this.#retainConnectionCleanupFailure(name, error);
 					if (this.#pendingToolLoads.get(name) !== toolsPromise) return;
 					this.#pendingToolLoads.delete(name);
-					if (!allowBackgroundLogging || reportedErrors.has(name) || this.#toolsOnly) return;
+					if (!allowBackgroundLogging || this.#toolsOnly || reportedErrors.has(name)) return;
 					const message = error instanceof Error ? error.message : String(error);
-					logger.error("MCP tool load failed", { path: `mcp:${name}`, error: message });
+					errors.set(name, this.#serverError(message));
+					reportedErrors.add(name);
+					logger.error("MCP tool load failed", {
+						path: `mcp:${name}`,
+						serverName: name,
+						error: classifyMCPStartupFailure(error),
+					});
 				});
 		}
 
@@ -1308,6 +1517,7 @@ export class MCPManager {
 				if (this.toolCache && !this.#toolsOnly) {
 					await Promise.all(
 						pendingTasks.map(async task => {
+							if (!this.#shouldCacheServerTools(task.name)) return;
 							const cached = await this.toolCache?.get(task.name, task.config);
 							if (cached) {
 								cachedTools.set(task.name, cached);
@@ -1316,41 +1526,55 @@ export class MCPManager {
 					);
 				}
 
-				const pendingWithoutCache = pendingTasks.filter(task => !cachedTools.has(task.name));
-				if (pendingWithoutCache.length > 0) {
-					// The startup wait elapsing means "stop blocking session start", not
-					// "this server failed". A server whose operator declared a `timeout`
-					// (`gjc mcp add --timeout`) asked to wait that long for it, so while it
-					// is still inside that window it keeps connecting in the background
-					// under `connectToServer`'s own timeout, and the background tool load
-					// adopts it. Only a server that declared no window, or already spent it,
-					// is torn down and reported. Exact-config (`toolsOnly`) startup still
-					// fails fast: it builds a catalog once, so a missing server is an error.
-					const startupElapsedMs = Date.now() - startupStartedAt;
-					for (const task of pendingWithoutCache) {
-						if (!this.#toolsOnly && withinDeclaredConnectionWindow(task.config, startupElapsedMs)) {
-							logger.warn("MCP server still connecting after the startup wait", {
-								path: `mcp:${task.name}`,
-								startupWaitMs: startupTimeoutMs,
-								declaredTimeoutMs: task.config.timeout,
-							});
-							continue;
-						}
-						const message = `MCP server connection timed out during startup: ${task.name}`;
-						errors.set(task.name, this.#serverError(message));
-						reportedErrors.add(task.name);
-						task.connectionAbort.abort(new Error(message));
-						if (this.#pendingConnections.has(task.name)) this.#pendingConnections.delete(task.name);
-						if (this.#pendingToolLoads.get(task.name) === task.toolsPromise)
-							this.#pendingToolLoads.delete(task.name);
-						this.#pendingConnectionControllers.delete(task.name);
-						void this.#disconnectServer(task.name).catch(error => {
-							this.#logLeaseReleaseFailure(task.name, undefined, error);
+				// Cached tools are only a fallback snapshot; they do not exempt the live
+				// connection from the startup cleanup contract. The startup wait elapsing
+				// means "stop blocking session start", not "this server failed". A server
+				// whose operator declared a `timeout` (`gjc mcp add --timeout`) asked to
+				// wait that long for it, so while it is still inside that window it keeps
+				// connecting in the background under `connectToServer`'s own timeout, and
+				// the background tool load adopts it. Only a server that declared no
+				// window, or already spent it, is torn down and reported. Exact-config
+				// (`toolsOnly`) startup still fails fast: it builds a catalog once, so a
+				// missing server is an error.
+				// Abort and disconnect in the background: a misbehaving stdio/MCP transport can
+				// ignore AbortSignal and keep startup blocked indefinitely, but it must not remain
+				// registered if it eventually connects.
+				const startupElapsedMs = Date.now() - startupStartedAt;
+				for (const task of pendingTasks) {
+					if (task.tracked.status !== "pending") continue;
+					if (!this.#toolsOnly && withinDeclaredConnectionWindow(task.config, startupElapsedMs)) {
+						logger.warn("MCP server still connecting after the startup wait", {
+							path: `mcp:${task.name}`,
+							serverName: task.name,
+							startupWaitMs: startupTimeoutMs,
+							declaredTimeoutMs: task.config.timeout,
+						});
+						continue;
+					}
+					const message = `MCP server connection timed out during startup: ${task.name}`;
+					if (!this.#toolsOnly) {
+						logger.warn("MCP server connection timed out during startup", {
+							path: `mcp:${task.name}`,
+							serverName: task.name,
+							startupWaitMs: startupTimeoutMs,
+							declaredTimeoutMs: task.config.timeout,
+							remediation: "Set a per-server timeout with `gjc mcp add --timeout <ms>` for slower servers.",
 						});
 					}
-					// Abort and disconnect in the background: a misbehaving stdio/MCP transport can
-					// ignore AbortSignal and keep startup blocked indefinitely, but it must not remain
-					// registered if it eventually connects.
+					errors.set(task.name, this.#serverError(message));
+					reportedErrors.add(task.name);
+					task.connectionAbort.abort(new Error(message));
+					if (this.#pendingConnections.has(task.name)) this.#pendingConnections.delete(task.name);
+					if (this.#pendingToolLoads.get(task.name) === task.toolsPromise)
+						this.#pendingToolLoads.delete(task.name);
+					this.#pendingConnectionControllers.delete(task.name);
+					void this.#disconnectServer(task.name, {
+						preserveConfig: this.#toolsOnly || cachedTools.has(task.name),
+						preserveSource: cachedTools.has(task.name),
+						preserveTools: cachedTools.has(task.name),
+					}).catch(error => {
+						this.#logLeaseReleaseFailure(task.name, undefined, error);
+					});
 				}
 			}
 
@@ -1368,26 +1592,39 @@ export class MCPManager {
 						continue;
 					}
 					connectedServers.add(name);
-					const reconnect = () => this.reconnectServer(name);
-					try {
-						allTools.push(
-							...MCPTool.fromTools(this.#connectionForLease(connection), serverTools, reconnect, {
-								noReplay: task.config.sharing === "shared",
-								inputHandler: () => this.#inputRequestHandler ?? undefined,
-							}),
-						);
-					} catch (error) {
-						await this.#cleanupConnectionTasks(connectionTasks);
-						throw error;
+					if (this.#isExactToolPublicationAllowed(name)) {
+						const reconnect = () => this.reconnectServer(name);
+						try {
+							allTools.push(
+								...MCPTool.fromTools(
+									this.#connectionForLease(connection),
+									serverTools,
+									reconnect,
+									this.#exactToolOptions(name, task.config.sharing === "shared"),
+								),
+							);
+						} catch (error) {
+							await this.#cleanupConnectionTasks(connectionTasks);
+							throw error;
+						}
 					}
 				} else if (task.tracked.status === "rejected") {
 					const reason = task.tracked.reason;
 					this.#retainConnectionCleanupFailure(name, reason);
 					const message = reason instanceof Error ? reason.message : String(reason);
+					if (!(this.#toolsOnly && reason instanceof MCPExpectedFailure)) {
+						logger.warn("MCP server connection failed during startup", {
+							path: `mcp:${name}`,
+							serverName: name,
+							error: classifyMCPStartupFailure(reason),
+							remediation:
+								"Check the server command and set --timeout <ms> when startup is expected to be slow.",
+						});
+					}
 					errors.set(name, this.#serverError(message));
 					reportedErrors.add(name);
 					if (this.#toolsOnly && reason instanceof MCPExpectedFailure) {
-						await this.#disconnectServer(name).catch(error => {
+						await this.#disconnectServer(name, { preserveConfig: true }).catch(error => {
 							this.#logLeaseReleaseFailure(name, this.#connections.get(name), error);
 						});
 					}
@@ -1396,7 +1633,7 @@ export class MCPManager {
 					}
 				} else {
 					const cached = cachedTools.get(name);
-					if (cached) {
+					if (cached && this.#isExactToolPublicationAllowed(name)) {
 						const source = this.#sources.get(name);
 						const reconnect = () => this.reconnectServer(name);
 						try {
@@ -1407,10 +1644,7 @@ export class MCPManager {
 									() => this.#waitForConnection(name).then(connection => this.#connectionForLease(connection)),
 									source,
 									reconnect,
-									{
-										noReplay: task.config.sharing === "shared",
-										inputHandler: () => this.#inputRequestHandler ?? undefined,
-									},
+									this.#exactToolOptions(name, task.config.sharing === "shared"),
 								),
 							);
 						} catch (error) {
@@ -1431,7 +1665,10 @@ export class MCPManager {
 		}
 
 		// Update cached tools
-		if (shouldPublishToolSnapshot) this.#tools = allTools;
+		if (shouldPublishToolSnapshot) {
+			this.#publishToolCatalog(allTools);
+			this.#notifyToolsChanged();
+		}
 		allowBackgroundLogging = true;
 
 		return {
@@ -1443,13 +1680,25 @@ export class MCPManager {
 	}
 
 	#replaceServerTools(name: string, tools: CustomTool<TSchema, MCPToolDetails>[]): void {
-		this.#tools = this.#tools.filter(
+		if (!this.#isExactToolPublicationAllowed(name)) return;
+		const publishedTools = this.#tools.filter(
 			tool => !((tool instanceof MCPTool || tool instanceof DeferredMCPTool) && tool.mcpServerName === name),
 		);
-		this.#tools.push(...tools);
+		if (!this.#suppressedServers.has(name)) publishedTools.push(...tools);
 		// Stable sort by name so reconnect order does not perturb the array.
 		// See `sortMCPToolsByName` for the cache-stability rationale.
-		sortMCPToolsByName(this.#tools);
+		sortMCPToolsByName(publishedTools);
+		this.#publishToolCatalog(publishedTools);
+	}
+
+	#exactToolOptions(
+		name: string,
+		noReplay: boolean,
+	): { noReplay: boolean; isAvailable?: () => boolean; inputHandler: () => MCPInputRequestHandler | undefined } {
+		const inputHandler = () => this.#inputRequestHandler ?? undefined;
+		return this.#toolsOnly
+			? { noReplay, isAvailable: () => !this.#suppressedServers.has(name), inputHandler }
+			: { noReplay, inputHandler };
 	}
 
 	#triggerNotificationRefresh(serverName: string, kind: "tools" | "resources" | "prompts"): void {
@@ -1525,7 +1774,463 @@ export class MCPManager {
 	 * Get all loaded tools.
 	 */
 	getTools(): CustomTool<TSchema, MCPToolDetails>[] {
-		return [...this.#tools];
+		return this.#tools.filter(tool => !tool.mcpServerName || this.#isExactToolPublicationAllowed(tool.mcpServerName));
+	}
+
+	/**
+	 * Read the fenced catalog and publication state atomically.
+	 *
+	 * An empty catalog is still authoritative after publication or while an
+	 * exact control is in flight. Deferred startup may fall back to its discovery
+	 * result only for the explicit `unpublished` state.
+	 */
+	getToolCatalogSnapshot(): MCPToolCatalogSnapshot {
+		const exactControlFence =
+			this.#toolsOnly &&
+			(this.#suppressedServers.size > 0 ||
+				this.#pendingExactSuspensions.size > 0 ||
+				this.#pendingExactControlServers.size > 0);
+		return {
+			tools: this.getTools(),
+			publication: exactControlFence ? "fenced" : this.#toolCatalogPublished ? "published" : "unpublished",
+			generation: this.#toolCatalogGeneration,
+		};
+	}
+
+	#publishToolCatalog(tools: CustomTool<TSchema, MCPToolDetails>[]): void {
+		this.#tools = tools;
+		this.#toolCatalogGeneration++;
+		this.#toolCatalogPublished = true;
+	}
+
+	#isExactToolPublicationAllowed(name: string): boolean {
+		return (
+			!this.#toolsOnly ||
+			(!this.#suppressedServers.has(name) &&
+				!this.#pendingExactSuspensions.has(name) &&
+				!this.#pendingExactControlServers.has(name))
+		);
+	}
+
+	isExactServerSuppressed(name: string): boolean {
+		this.#assertExactServerControl();
+		return this.#suppressedServers.has(name);
+	}
+
+	#exactServerToolCount(name: string): number {
+		return this.#tools.reduce((count, tool) => (tool.mcpServerName === name ? count + 1 : count), 0);
+	}
+
+	#assertExactServerControl(): void {
+		if (!this.#toolsOnly) throw new Error("Exact MCP server controls require a tools-only manager");
+	}
+
+	/**
+	 * Prepare one exact-config control without publishing manager state. Session
+	 * registry and prompt validation run against `tools`; commit is the single
+	 * publication point and abort releases only an unpublished candidate.
+	 */
+	async prepareExactServerControl(
+		action: "suspend" | "resume" | "reconnect",
+		name: string,
+	): Promise<PreparedExactMcpServerControl> {
+		this.#assertExactServerControl();
+		if (!this.#serverConfigs.has(name) && !this.#connections.has(name)) {
+			return this.#settledExactControl({ name, status: "unknown-server", toolCount: 0 });
+		}
+		if (action === "suspend") {
+			if (this.#suppressedServers.has(name)) {
+				return this.#settledExactControl({ name, status: "already-suspended", toolCount: 0 });
+			}
+			this.#pendingExactSuspensions.add(name);
+			await this.#activeSharedRebinds.get(name)?.promise;
+			const tools = this.#tools.filter(
+				tool =>
+					tool.mcpServerName !== name && (!tool.mcpServerName || !this.#suppressedServers.has(tool.mcpServerName)),
+			);
+			return {
+				result: { name, status: "suspended", toolCount: 0 },
+				tools,
+				canCommit: () => true,
+				commit: async () => {
+					this.#suppressedServers.add(name);
+					this.#pendingExactSuspensions.delete(name);
+					this.#reconnectBackoffs.get(name)?.abort(new Error(`MCP server suspended: ${name}`));
+					for (const tool of this.#tools) {
+						if (tool.mcpServerName === name) (tool as MCPTool | DeferredMCPTool).invalidateForSessionControl();
+					}
+					await this.#activeSharedRebinds.get(name)?.promise;
+				},
+				abort: async () => {
+					this.#pendingExactSuspensions.delete(name);
+				},
+			};
+		}
+		if (action === "resume" && !this.#suppressedServers.has(name)) {
+			return this.#settledExactControl({
+				name,
+				status: "not-suspended",
+				toolCount: this.#exactServerToolCount(name),
+			});
+		}
+		if (action === "reconnect" && this.#suppressedServers.has(name)) {
+			return this.#settledExactControl({ name, status: "unavailable", toolCount: 0 });
+		}
+		const automaticReconnect = this.#pendingReconnections.get(name);
+		if (automaticReconnect) {
+			this.#pendingExactControlServers.add(name);
+			let connection: MCPServerConnection | null;
+			try {
+				connection = await automaticReconnect;
+			} catch (error) {
+				this.#pendingExactControlServers.delete(name);
+				this.#drainDeferredSharedRebinds();
+				throw error;
+			}
+			if (!connection) {
+				this.#pendingExactControlServers.delete(name);
+				this.#drainDeferredSharedRebinds();
+				return this.#settledExactControl({ name, status: "unavailable", toolCount: 0 });
+			}
+			let candidateTools: CustomTool<TSchema, MCPToolDetails>[];
+			try {
+				candidateTools = await this.#buildExactServerTools(name, connection);
+			} catch (error) {
+				this.#pendingExactControlServers.delete(name);
+				this.#drainDeferredSharedRebinds();
+				throw error;
+			}
+			return this.#preparedCatalogCommit(
+				name,
+				action === "resume" ? "resumed" : "reconnected",
+				candidateTools,
+				undefined,
+				connection,
+			);
+		}
+		this.#pendingExactControlServers.add(name);
+		const existing = this.#connections.get(name);
+		if (action === "resume" && existing?.transport.connected) {
+			try {
+				const candidateTools = await this.#buildExactServerTools(name, existing);
+				return this.#preparedCatalogCommit(name, "resumed", candidateTools, undefined, existing);
+			} catch {
+				// A mapped transport can close while suppressed; recover with an
+				// unpublished physical candidate instead of exposing stale state.
+			}
+		}
+		try {
+			const candidate = await this.#prepareExactReplacement(name);
+			return this.#preparedCatalogCommit(
+				name,
+				action === "resume" ? "resumed" : "reconnected",
+				candidate.tools,
+				candidate,
+				undefined,
+			);
+		} catch (error) {
+			const cleanupFailure = this.#retainConnectionCleanupFailure(name, error);
+			if (cleanupFailure) {
+				logger.error("MCP exact replacement cleanup failed", {
+					path: `mcp:${name}`,
+					error: cleanupFailure,
+				});
+			}
+			this.#pendingExactControlServers.delete(name);
+			this.#drainDeferredSharedRebinds();
+			return this.#settledExactControl({ name, status: "unavailable", toolCount: 0 });
+		}
+	}
+
+	/** Clear all session-local suppression before this owner adopts a new identity. */
+	async prepareExactServerControlReset(): Promise<PreparedExactMcpCatalog> {
+		this.#assertExactServerControl();
+		const prepared: PreparedExactMcpServerControl[] = [];
+		for (const name of [...this.#suppressedServers]) {
+			try {
+				const candidate = await this.prepareExactServerControl("resume", name);
+				if (candidate.result.status !== "resumed") {
+					logger.warn("MCP server did not resume during identity reset", {
+						path: `mcp:${name}`,
+						status: candidate.result.status,
+					});
+					await candidate.abort();
+					continue;
+				}
+				prepared.push(candidate);
+			} catch (error) {
+				// A suspended server's reachability must not block identity adoption.
+				logger.warn("MCP server resume failed during identity reset", { path: `mcp:${name}`, error });
+			}
+		}
+		const resumedNames = new Set(prepared.map(candidate => candidate.result.name));
+		const carriedOver = this.#tools.filter(
+			tool =>
+				!tool.mcpServerName ||
+				(!this.#suppressedServers.has(tool.mcpServerName) && !resumedNames.has(tool.mcpServerName)),
+		);
+		const resumedTools = prepared.flatMap(candidate =>
+			candidate.tools.filter(tool => tool.mcpServerName === candidate.result.name),
+		);
+		const tools = [...carriedOver, ...resumedTools];
+		sortMCPToolsByName(tools);
+		return {
+			tools,
+			canCommit: () => prepared.every(candidate => candidate.canCommit()),
+			commit: async () => {
+				try {
+					for (const candidate of prepared) {
+						if (!candidate.precommit)
+							throw new Error("Exact MCP reset candidate does not support atomic publication");
+						candidate.precommit();
+					}
+				} catch (error) {
+					await Promise.allSettled(prepared.map(candidate => candidate.abort()));
+					throw error;
+				}
+				for (const candidate of prepared) {
+					if (!candidate.publish) throw new Error("Exact MCP reset candidate does not support atomic publication");
+					candidate.publish();
+				}
+				this.#publishToolCatalog(tools);
+				this.#suppressedServers.clear();
+				this.#pendingExactSuspensions.clear();
+				this.#drainDeferredSharedRebinds();
+			},
+			abort: async () => {
+				await Promise.allSettled(prepared.map(candidate => candidate.abort()));
+			},
+		};
+	}
+
+	#settledExactControl(result: ExactMcpServerControlResult): PreparedExactMcpServerControl {
+		return { result, tools: this.getTools(), canCommit: () => true, commit: async () => {}, abort: async () => {} };
+	}
+
+	async #buildExactServerTools(
+		name: string,
+		connection: MCPServerConnection,
+	): Promise<CustomTool<TSchema, MCPToolDetails>[]> {
+		const config = this.#serverConfigs.get(name) ?? connection.config;
+		const serverTools = await listTools(this.#connectionForLease(connection));
+		const reconnect = () => this.reconnectServer(name);
+		return MCPTool.fromTools(
+			this.#connectionForLease(connection),
+			serverTools,
+			reconnect,
+			this.#exactToolOptions(name, config.sharing === "shared"),
+		);
+	}
+
+	async #preparedCatalogCommit(
+		name: string,
+		status: "resumed" | "reconnected",
+		serverTools: CustomTool<TSchema, MCPToolDetails>[],
+		candidate:
+			| {
+					connection: MCPServerConnection;
+					lease: MCPPoolLease;
+					canCommit(): boolean;
+					publish(): void;
+					abort(): Promise<void>;
+			  }
+			| undefined,
+		expectedConnection: MCPServerConnection | undefined,
+	): Promise<PreparedExactMcpServerControl> {
+		const tools = [
+			...this.#tools.filter(
+				tool =>
+					tool.mcpServerName !== name && (!tool.mcpServerName || !this.#suppressedServers.has(tool.mcpServerName)),
+			),
+			...serverTools,
+		];
+		sortMCPToolsByName(tools);
+		if (this.#toolsOnly && new Set(tools.map(tool => tool.name)).size !== tools.length) {
+			let abortError: unknown;
+			try {
+				await candidate?.abort();
+			} catch (error) {
+				abortError = error;
+			}
+			this.#pendingExactControlServers.delete(name);
+			this.#drainDeferredSharedRebinds();
+			if (abortError !== undefined) throw abortError;
+			return this.#settledExactControl({ name, status: "unavailable", toolCount: 0 });
+		}
+		let settled = false;
+		const precommit = (): void => {
+			if (settled) return;
+			if (
+				candidate
+					? !candidate.canCommit()
+					: expectedConnection &&
+						(this.#connections.get(name) !== expectedConnection || !expectedConnection.transport.connected)
+			) {
+				throw new Error(`MCP exact control predecessor changed before commit: ${name}`);
+			}
+		};
+		const publish = (): void => {
+			if (settled) return;
+			candidate?.publish();
+			settled = true;
+			if (candidate) {
+				this.#leaseByConnection.set(candidate.connection, candidate.lease);
+				this.#connections.set(name, candidate.connection);
+				this.#registerLease(name, candidate.connection);
+			}
+			for (const tool of this.#tools) {
+				if (tool.mcpServerName === name) (tool as MCPTool | DeferredMCPTool).invalidateForSessionControl();
+			}
+			const publishedTools = [
+				...this.#tools.filter(
+					tool =>
+						tool.mcpServerName !== name &&
+						(!tool.mcpServerName || !this.#suppressedServers.has(tool.mcpServerName)),
+				),
+				...serverTools,
+			];
+			sortMCPToolsByName(publishedTools);
+			this.#publishToolCatalog(publishedTools);
+			this.#suppressedServers.delete(name);
+			this.#pendingExactControlServers.delete(name);
+			this.#drainDeferredSharedRebinds();
+		};
+		return {
+			result: { name, status, toolCount: serverTools.length },
+			tools,
+			canCommit: () =>
+				candidate
+					? candidate.canCommit()
+					: !expectedConnection ||
+						(this.#connections.get(name) === expectedConnection && expectedConnection.transport.connected),
+			precommit,
+			publish,
+			commit: async () => {
+				if (settled) return;
+				try {
+					precommit();
+					publish();
+				} catch (error) {
+					let abortError: unknown;
+					try {
+						await candidate?.abort();
+					} catch (cleanupError) {
+						abortError = cleanupError;
+					}
+					this.#pendingExactControlServers.delete(name);
+					this.#drainDeferredSharedRebinds();
+					if (abortError !== undefined) {
+						throw new AggregateError([error, abortError], `MCP exact control commit and cleanup failed: ${name}`);
+					}
+					throw error;
+				}
+			},
+			abort: async () => {
+				if (settled) return;
+				let abortError: unknown;
+				try {
+					await candidate?.abort();
+				} catch (cleanupError) {
+					abortError = cleanupError;
+				}
+				settled = true;
+				this.#pendingExactControlServers.delete(name);
+				this.#drainDeferredSharedRebinds();
+				if (abortError !== undefined) throw abortError;
+			},
+		};
+	}
+
+	async #prepareExactReplacement(name: string): Promise<{
+		connection: MCPServerConnection;
+		lease: MCPPoolLease;
+		tools: CustomTool<TSchema, MCPToolDetails>[];
+		canCommit(): boolean;
+		publish(): void;
+		abort(): Promise<void>;
+	}> {
+		const config = this.#serverConfigs.get(name);
+		if (!config) throw new Error(`MCP server unavailable: ${name}`);
+		await this.#closePendingConnectionCleanup(name);
+		const resolved = await this.#resolveAuthConfig(config);
+		const abort = new AbortController();
+		this.#pendingConnectionControllers.set(name, abort);
+		let prepared:
+			| {
+					lease: MCPPoolLease;
+					canCommit(): boolean;
+					publish(): void;
+					abort(): Promise<void>;
+			  }
+			| undefined;
+		const abortPrepared = async (): Promise<void> => {
+			if (!prepared) return;
+			try {
+				await prepared.abort();
+			} catch (error) {
+				const cleanupFailure = this.#retainConnectionCleanupFailure(name, error);
+				if (cleanupFailure) {
+					logger.error("MCP exact replacement abort cleanup failed", {
+						path: `mcp:${name}`,
+						error: cleanupFailure,
+					});
+				}
+				throw error;
+			}
+		};
+		try {
+			prepared = await this.#pool.prepareReplacement(name, resolved, {
+				keyConfig: config,
+				sharingMode:
+					config.sharing === "shared" &&
+					(resolved.type === "http" || resolved.type === "sse" || resolved.type === "stdio")
+						? "shared"
+						: "per-session",
+				sessionId: config.sharing === "shared" ? undefined : this.#sessionId,
+				signal: abort.signal,
+				advertiseRoots: false,
+				effectiveCwd: resolved.type === "stdio" ? (resolved.cwd ?? this.cwd) : this.cwd,
+				capabilityProfile: "tools-only",
+				effectiveHeaders: resolved.type === "http" || resolved.type === "sse" ? resolved.headers : undefined,
+				onRequest: (method, params) => this.#handleServerRequest(method, params),
+				onCleanupPending: error => this.#retainPendingAcquireCleanup(name, error),
+			});
+			const connection = prepared.lease.connection;
+			connection.config = config;
+			const source = this.#sources.get(name) ?? this.#connections.get(name)?._source;
+			if (source) connection._source = source;
+			const definitions = await listTools(prepared.lease.connectionForLease());
+			const reconnect = () => this.reconnectServer(name);
+			const tools = MCPTool.fromTools(
+				prepared.lease.connectionForLease(),
+				definitions,
+				reconnect,
+				this.#exactToolOptions(name, config.sharing === "shared"),
+			);
+			return {
+				connection,
+				lease: prepared.lease,
+				tools,
+				canCommit: prepared.canCommit,
+				publish: prepared.publish,
+				abort: abortPrepared,
+			};
+		} catch (error) {
+			this.#retainConnectionCleanupFailure(name, error);
+			try {
+				await abortPrepared();
+			} catch (abortError) {
+				throw new AggregateError(
+					[error, abortError],
+					`MCP exact replacement preparation and cleanup failed: ${name}`,
+				);
+			}
+			throw error;
+		} finally {
+			if (this.#pendingConnectionControllers.get(name) === abort) {
+				this.#pendingConnectionControllers.delete(name);
+			}
+		}
 	}
 
 	/**
@@ -1776,7 +2481,10 @@ export class MCPManager {
 		await this.#disconnectServer(name);
 	}
 
-	async #disconnectServer(name: string): Promise<void> {
+	async #disconnectServer(
+		name: string,
+		options: { preserveConfig?: boolean; preserveSource?: boolean; preserveTools?: boolean } = {},
+	): Promise<void> {
 		const nextEpoch = (this.#disconnectEpochs.get(name) ?? 0) + 1;
 		this.#disconnectEpochs.set(name, nextEpoch);
 		this.#pendingConnectionControllers.get(name)?.abort(new Error(`MCP server disconnected: ${name}`));
@@ -1786,8 +2494,8 @@ export class MCPManager {
 		this.#pendingConnections.delete(name);
 		this.#pendingToolLoads.delete(name);
 		this.#pendingReconnections.delete(name);
-		this.#sources.delete(name);
-		this.#serverConfigs.delete(name);
+		if (!options.preserveSource) this.#sources.delete(name);
+		if (!options.preserveConfig) this.#serverConfigs.delete(name);
 		this.#pendingResourceRefresh.delete(name);
 		const connection = this.#connections.get(name);
 
@@ -1816,14 +2524,21 @@ export class MCPManager {
 			if (this.#connections.get(name) === connection) this.#connections.delete(name);
 		}
 
-		// Remove tools from this server and notify consumers
-		const hadTools = this.#tools.some(
-			tool => (tool instanceof MCPTool || tool instanceof DeferredMCPTool) && tool.mcpServerName === name,
-		);
-		this.#tools = this.#tools.filter(
-			tool => !((tool instanceof MCPTool || tool instanceof DeferredMCPTool) && tool.mcpServerName === name),
-		);
-		if (hadTools) this.#onToolsChanged?.(this.#tools);
+		// Keep a published cache fallback available while its expired live connection closes.
+		if (!options.preserveTools) {
+			const hadTools = this.#tools.some(
+				tool => (tool instanceof MCPTool || tool instanceof DeferredMCPTool) && tool.mcpServerName === name,
+			);
+			const remainingTools = this.#tools.filter(
+				tool => !((tool instanceof MCPTool || tool instanceof DeferredMCPTool) && tool.mcpServerName === name),
+			);
+			if (hadTools) {
+				this.#publishToolCatalog(remainingTools);
+				this.#notifyToolsChanged();
+			} else {
+				this.#tools = remainingTools;
+			}
+		}
 
 		// Notify prompt consumers so stale commands are cleared
 		if (connection?.prompts?.length) this.#onPromptsChanged?.(name);
@@ -1926,8 +2641,13 @@ export class MCPManager {
 			this.#pendingResourceRefresh.clear();
 			this.#sources.clear();
 			this.#serverConfigs.clear();
+			this.#suppressedServers.clear();
+			this.#pendingExactSuspensions.clear();
+			this.#pendingExactControlServers.clear();
 			this.#connections.clear();
-			this.#tools = [];
+			const hadTools = this.#tools.length > 0;
+			this.#publishToolCatalog([]);
+			if (hadTools) this.#notifyToolsChanged();
 			this.#subscribedResources.clear();
 			const releaseFailures = [
 				...scopedReleaseFailures,
@@ -1966,6 +2686,8 @@ export class MCPManager {
 	async reconnectServer(name: string): Promise<MCPServerConnection | null> {
 		if (this.#connectionSetSealed) return null;
 		if (this.#scopedLifecycle === "disconnecting") return null;
+		if (this.#pendingExactControlServers.has(name)) return this.#connections.get(name) ?? null;
+		if (this.#suppressedServers.has(name)) return null;
 		const pending = this.#pendingReconnections.get(name);
 		if (pending) return pending;
 
@@ -2163,6 +2885,9 @@ export class MCPManager {
 		// while we were connecting (e.g. /mcp reload called disconnectAll).
 		if (
 			!this.#serverConfigs.has(name) ||
+			this.#suppressedServers.has(name) ||
+			this.#pendingExactSuspensions.has(name) ||
+			this.#pendingExactControlServers.has(name) ||
 			this.#epoch !== globalEpoch ||
 			(this.#disconnectEpochs.get(name) ?? 0) !== disconnectEpoch ||
 			(lifecycleEpoch !== undefined &&
@@ -2193,19 +2918,28 @@ export class MCPManager {
 		}
 		try {
 			const serverTools = await listTools(this.#connectionForLease(connection));
-			if (!this.#isCurrentConnection(name, config, globalEpoch, disconnectEpoch, connection)) {
+			// An exact control can claim this server while tools load; publishing here
+			// would install a catalog the control never validated.
+			if (
+				!this.#isCurrentConnection(name, config, globalEpoch, disconnectEpoch, connection) ||
+				this.#suppressedServers.has(name) ||
+				this.#pendingExactSuspensions.has(name) ||
+				this.#pendingExactControlServers.has(name)
+			) {
 				const disconnectError = new Error(`Server "${name}" was disconnected during tool loading`);
 				await this.#releaseLeasePreservingPrimary(name, connection);
 				throw disconnectError;
 			}
 			const reconnect = () => this.reconnectServer(name);
-			const customTools = MCPTool.fromTools(this.#connectionForLease(connection), serverTools, reconnect, {
-				noReplay: config.sharing === "shared",
-				inputHandler: () => this.#inputRequestHandler ?? undefined,
-			});
-			void this.toolCache?.set(name, config, serverTools);
+			const customTools = MCPTool.fromTools(
+				this.#connectionForLease(connection),
+				serverTools,
+				reconnect,
+				this.#exactToolOptions(name, config.sharing === "shared"),
+			);
+			if (this.#shouldCacheServerTools(name)) void this.toolCache?.set(name, config, serverTools);
 			this.#replaceServerTools(name, customTools);
-			this.#onToolsChanged?.(this.#tools);
+			this.#notifyToolsChanged();
 			void this.#loadServerResourcesAndPrompts(name, connection);
 			return connection;
 		} catch (error) {
@@ -2267,15 +3001,17 @@ export class MCPManager {
 		const serverTools = await listTools(facade);
 		if (!this.#isCurrentConnection(name, connection.config, globalEpoch, disconnectEpoch, connection)) return;
 		const reconnect = () => this.reconnectServer(name);
-		const customTools = MCPTool.fromTools(facade, serverTools, reconnect, {
-			noReplay: connection.config.sharing === "shared",
-			inputHandler: () => this.#inputRequestHandler ?? undefined,
-		});
-		void this.toolCache?.set(name, connection.config, serverTools);
+		const customTools = MCPTool.fromTools(
+			facade,
+			serverTools,
+			reconnect,
+			this.#exactToolOptions(name, connection.config.sharing === "shared"),
+		);
+		if (this.#shouldCacheServerTools(name)) void this.toolCache?.set(name, connection.config, serverTools);
 
 		// Replace tools from this server
 		this.#replaceServerTools(name, customTools);
-		this.#onToolsChanged?.(this.#tools);
+		this.#notifyToolsChanged();
 	}
 
 	/**