fix: prevent duplicate MCP connections during initialization

- Add isInitializing flag to prevent file watchers from creating duplicate connections
- Refactor constructor to use async initialization method
- Skip config change handling during initialization phase
- Add test to verify no duplicate connections are created
- Fixes issue where Docker (MCP) processes were duplicated on startup

Author: hannesrudolph

src/services/mcp/McpHub.ts

@@ -134,14 +134,27 @@ export class McpHub {
 	isConnecting: boolean = false
 	private configChangeDebounceTimers: Map<string, NodeJS.Timeout> = new Map()
 	private toggleOperations: Map<string, Promise<void>> = new Map() // Track ongoing toggle operations
+	private isInitializing: boolean = true // Flag to prevent duplicate connections during initialization
 
 	constructor(provider: ClineProvider) {
 		this.providerRef = new WeakRef(provider)
-		this.watchMcpSettingsFile()
-		this.watchProjectMcpFile().catch(console.error)
+		this.initializeHub().catch(console.error)
+	}
+
+	private async initializeHub(): Promise<void> {
+		// Set up watchers first but mark as initializing to prevent them from creating connections
+		this.isInitializing = true
+
+		await this.watchMcpSettingsFile()
+		await this.watchProjectMcpFile()
 		this.setupWorkspaceFoldersWatcher()
-		this.initializeGlobalMcpServers()
-		this.initializeProjectMcpServers()
+
+		// Now initialize servers - watchers won't trigger duplicate connections
+		await this.initializeGlobalMcpServers()
+		await this.initializeProjectMcpServers()
+
+		// Clear the initialization flag after servers are set up
+		this.isInitializing = false
 	}
 	/**
 	 * Registers a client (e.g., ClineProvider) using this hub.
@@ -255,6 +268,12 @@ export class McpHub {
 	 * Debounced wrapper for handling config file changes
 	 */
 	private debounceConfigChange(filePath: string, source: "global" | "project"): void {
+		// Skip file change handling during initialization to prevent duplicate connections
+		if (this.isInitializing) {
+			console.log(`Skipping config change for ${source} during initialization`)
+			return
+		}
+
 		const key = `${source}-${filePath}`
 
 		// Clear existing timer if any

src/services/mcp/__tests__/McpHub.spec.ts

@@ -1017,6 +1017,68 @@ describe("McpHub", () => {
 			// Still should not connect
 			expect(StdioClientTransport).not.toHaveBeenCalled()
 		})
+
+		it("should not create duplicate connections during initialization", async () => {
+			// Mock the config file read
+			const mockConfig = {
+				mcpServers: {
+					"test-server": {
+						type: "stdio" as const,
+						command: "node",
+						args: ["test.js"],
+						disabled: false,
+						timeout: 60,
+						cwd: process.cwd(),
+						alwaysAllow: [],
+						disabledTools: [],
+					},
+				},
+			}
+			vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(mockConfig))
+
+			// Mock StdioClientTransport
+			const mockTransport = {
+				start: vi.fn().mockResolvedValue(undefined),
+				close: vi.fn().mockResolvedValue(undefined),
+				stderr: {
+					on: vi.fn(),
+				},
+				onerror: null,
+				onclose: null,
+			}
+
+			const StdioClientTransport = (await import("@modelcontextprotocol/sdk/client/stdio.js"))
+				.StdioClientTransport as ReturnType<typeof vi.fn>
+			StdioClientTransport.mockClear()
+			StdioClientTransport.mockImplementation(() => mockTransport)
+
+			// Mock Client
+			const mockClient = {
+				connect: vi.fn().mockResolvedValue(undefined),
+				close: vi.fn().mockResolvedValue(undefined),
+				getInstructions: vi.fn().mockReturnValue("test instructions"),
+				request: vi.fn().mockResolvedValue({ tools: [], resources: [], resourceTemplates: [] }),
+			}
+			const Client = (await import("@modelcontextprotocol/sdk/client/index.js")).Client as ReturnType<
+				typeof vi.fn
+			>
+			Client.mockClear()
+			Client.mockImplementation(() => mockClient)
+
+			// Create a new McpHub instance
+			const newMcpHub = new McpHub(mockProvider as ClineProvider)
+
+			// Wait for initialization to complete
+			await new Promise((resolve) => setTimeout(resolve, 200))
+
+			// Verify that only one connection was created (not duplicated)
+			expect(StdioClientTransport).toHaveBeenCalledTimes(1)
+			expect(mockClient.connect).toHaveBeenCalledTimes(1)
+
+			// Verify the hub has exactly one connection
+			expect(newMcpHub.connections.length).toBe(1)
+			expect(newMcpHub.connections[0].server.name).toBe("test-server")
+		})
 	})
 
 	describe("callTool", () => {