Preserve tool lookup errors during copying and pickling

Author: Kludex

src/mcp/server/mcpserver/exceptions.py

@@ -71,6 +71,9 @@ def __init__(self, name: str) -> None:
         self.name = name
         super().__init__(f"Unknown tool: {name}")
 
+    def __reduce__(self) -> tuple[type["ToolNotFoundError"], tuple[str], dict[str, object]]:
+        return type(self), (self.name,), self.__dict__
+
 
 class UnexpectedToolError(ToolError):
     """A tool call failed with something other than `ToolError`, `ResourceError`, or `MCPError`.

tests/server/mcpserver/test_server.py

@@ -1,7 +1,9 @@
 import base64
 import logging
+import pickle
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from copy import copy, deepcopy
 from dataclasses import dataclass
 from pathlib import Path
 from types import SimpleNamespace
@@ -3340,6 +3342,23 @@ async def test_missing_tool_direct_call_remains_a_tool_error() -> None:
     assert str(exc_info.value) == snapshot("Unknown tool: missing")
 
 
+async def test_missing_tool_error_survives_copying_and_pickling() -> None:
+    """SDK-defined: reconstructing a lookup error preserves its name, message, and exception notes."""
+    server = MCPServer()
+    with pytest.raises(ToolNotFoundError) as exc_info:
+        await server.call_tool("missing", {})
+    original = exc_info.value
+    original.add_note("Requested by a background worker")
+
+    for cloned in (copy(original), deepcopy(original), pickle.loads(pickle.dumps(original))):
+        assert isinstance(cloned, ToolNotFoundError)
+        assert cloned is not original
+        assert cloned.name == original.name
+        assert cloned.args == original.args
+        assert str(cloned) == str(original)
+        assert cloned.__notes__ == original.__notes__
+
+
 @pytest.mark.parametrize("mode", ["legacy", "2026-07-28"])
 async def test_nested_missing_tool_returns_an_execution_error(mode: Literal["legacy", "2026-07-28"]) -> None:
     """A missing tool called while executing an existing tool remains an execution failure."""