From 3679445c768fe9d730b5fdafc499fcfaff3a777d Mon Sep 17 00:00:00 2001
From: Max Isbey <224885523+maxisbey@users.noreply.github.com>
Date: Fri, 2 Oct 2026 11:00:36 +0000
Subject: [PATCH] Document when a caller-supplied request id can be minted
 again

The `request_id` key of `CallOptions` said only that a supplied id must not
collide with an in-flight one. Spell out the rest of the contract: integer
ids and numeric strings share the dispatcher's own counter, the dispatcher
skips an id that is still in flight but may mint the same value again once
that request has finished, and an id that must stay unique for the whole
session should be a string that doesn't parse as an integer.

No behaviour change.

Fixes #3126
---
 src/mcp/shared/dispatcher.py | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/mcp/shared/dispatcher.py b/src/mcp/shared/dispatcher.py
index f2ff96e7d5..c09d7a9863 100644
--- a/src/mcp/shared/dispatcher.py
+++ b/src/mcp/shared/dispatcher.py
@@ -86,9 +86,15 @@ class CallOptions(TypedDict, total=False):
     with one of the sender's own in-flight request ids raises `ValueError`.
     Callers that need to know a request's id before its result arrives (a
     `subscriptions/listen` stream is demultiplexed by it) mint their own ids
-    here; string ids that don't parse as integers can never collide with the
-    dispatcher's minted sequence. Per the class contract, dispatchers that
-    predate this key ignore it and mint as usual.
+    here.
+
+    Integer ids, and strings that parse as integers, share the dispatcher's own
+    counter. The dispatcher skips an id that is still in flight, but may mint
+    the same value again once that request has finished. When an id must stay
+    unique for the whole session, use a string that doesn't parse as an
+    integer, as the `subscriptions/listen` driver does (`listen-1`,
+    `listen-2`, ...). Per the class contract, dispatchers that predate this key
+    ignore it and mint as usual.
     """
 
     timeout: float