fix: make MCP list-change scheduling deterministic

Author: lloydrichards

.changeset/tidy-clocks-notify.md

@@ -0,0 +1,5 @@
+---
+"effect": patch
+---
+
+MCP servers now coalesce registration list-change notifications deterministically so delayed setup events do not leak into later subscriptions.

packages/effect/src/unstable/ai/McpServer.ts

@@ -303,33 +303,32 @@ export class McpServer extends Context.Service<McpServer, {
       readonly annotations: Context.Context<never>
     }> = []
     const notificationsQueue = yield* Queue.make<QueuedServerNotification>()
-    const listChangedHandles = new Map<string, any>()
+    const pendingListChanged = new Set<string>()
     const notifications = yield* RpcClient.makeNoSerialization(BroadcastServerNotificationRpcs, {
       spanPrefix: "McpServer/Notifications",
-      onFromClient: (options) =>
-        Effect.suspend((): Effect.Effect<void> => {
+      onFromClient: (options): Effect.Effect<void> =>
+        Effect.gen(function*() {
           const message = options.message
           if (message._tag !== "Request") {
-            return Effect.void
+            return
           }
           const notification = toInternalServerNotification(message)
           if (notification === undefined) {
-            return Effect.void
+            return
           }
           if (message.tag.includes("list_changed")) {
-            if (!listChangedHandles.has(message.tag)) {
-              listChangedHandles.set(
-                message.tag,
-                setTimeout(() => {
-                  Queue.offerUnsafe(notificationsQueue, { notification })
-                  listChangedHandles.delete(message.tag)
-                }, 0)
+            if (!pendingListChanged.has(message.tag)) {
+              pendingListChanged.add(message.tag)
+              yield* Effect.sleep(0).pipe(
+                Effect.andThen(Queue.offer(notificationsQueue, { notification })),
+                Effect.ensuring(Effect.sync(() => pendingListChanged.delete(message.tag))),
+                Effect.forkDetach
               )
             }
           } else {
-            Queue.offerUnsafe(notificationsQueue, { notification })
+            yield* Queue.offer(notificationsQueue, { notification })
           }
-          return notifications.write({
+          yield* notifications.write({
             clientId: 0,
             requestId: message.id,
             _tag: "Exit",

packages/effect/test/unstable/ai/McpServer/McpServer.test.ts

@@ -26,6 +26,7 @@ import type * as RpcMessage from "effect/unstable/rpc/RpcMessage"
 import * as RpcServer from "effect/unstable/rpc/RpcServer"
 import { makeHttpHarness } from "./TestUtils/McpHttpHarness.ts"
 import { makeServerLayer } from "./TestUtils/McpServerLayer.ts"
+import { makeMcpStdioHarness } from "./TestUtils/McpStdioHarness.ts"
 
 const OptionalStringTool = Tool.make("OptionalStringTool", {
   parameters: Schema.Struct({ signature: Schema.optional(Schema.String) }),
@@ -583,6 +584,47 @@ describe("McpServer", () => {
       }))
   })
 
+  describe("list-change notification scheduling", () => {
+    it.effect("should coalesce notifications when one registration kind changes repeatedly in a scheduling window", () =>
+      Effect.gen(function*() {
+        const fixture = yield* makeMcpStdioHarness(McpProtocol.v2026_07_28)
+        const makeTool = (name: string) => ({
+          tool: new McpSchema.Tool({ name, inputSchema: { type: "object", properties: {} } }),
+          annotations: Context.empty(),
+          handle: () => Effect.succeed(new McpSchema.CallToolResult({ content: [] }))
+        })
+        const makePrompt = (name: string) => ({
+          prompt: new McpSchema.Prompt({ name }),
+          annotations: Context.empty(),
+          completions: {},
+          handle: () =>
+            Effect.succeed(
+              new McpSchema.GetPromptResult({
+                messages: [{ role: "user", content: { type: "text", text: name } }]
+              })
+            )
+        })
+
+        yield* fixture.server.addTool(makeTool("baseline-tool"))
+        yield* fixture.server.addPrompt(makePrompt("baseline-prompt"))
+        yield* fixture.flushListChanged
+        yield* fixture.initialize()
+        const subscription = yield* fixture.startRequest("subscriptions/listen", {
+          notifications: { toolsListChanged: true, promptsListChanged: true }
+        }, "coalesced-list-change")
+        assert.strictEqual((yield* fixture.takeMessage).method, "notifications/subscriptions/acknowledged")
+
+        yield* fixture.server.addTool(makeTool("coalesced-tool-first"))
+        yield* fixture.server.addTool(makeTool("coalesced-tool-second"))
+        yield* fixture.server.addPrompt(makePrompt("coalescing-sentinel"))
+        yield* fixture.flushListChanged
+
+        assert.strictEqual((yield* fixture.takeMessage).method, "notifications/tools/list_changed")
+        assert.strictEqual((yield* fixture.takeMessage).method, "notifications/prompts/list_changed")
+        yield* subscription.cancel()
+      }))
+  })
+
   describe("resource subscriptions", () => {
     it.effect("should isolate resource subscriptions and clear disconnected sessions", () =>
       Effect.gen(function*() {