test: add server-initiated request and notification interaction tests

Covers the server-to-client half of the interaction model: sampling,
form-mode elicitation, roots, progress in both directions, list_changed
notifications, and request cancellation, all against the low-level Server
through the public Client API. Records a further divergence: the server
answers cancelled requests with an error response where the spec says no
response should be sent.

Removes five more 'pragma: no cover' comments on paths these tests now
cover (server list_changed senders, the client roots send path, and the
default elicitation callback).

Author: maxisbey

src/mcp/client/client.py

@@ -305,4 +305,4 @@ async def list_tools(self, *, cursor: str | None = None, meta: RequestParamsMeta
     async def send_roots_list_changed(self) -> None:
         """Send a notification that the roots list has changed."""
         # TODO(Marcelo): Currently, there is no way for the server to handle this. We should add support.
-        await self.session.send_roots_list_changed()  # pragma: no cover
+        await self.session.send_roots_list_changed()

src/mcp/client/session.py

@@ -74,7 +74,7 @@ async def _default_elicitation_callback(
     context: RequestContext[ClientSession],
     params: types.ElicitRequestParams,
 ) -> types.ElicitResult | types.ErrorData:
-    return types.ErrorData(  # pragma: no cover
+    return types.ErrorData(
         code=types.INVALID_REQUEST,
         message="Elicitation not supported",
     )
@@ -408,7 +408,7 @@ async def list_tools(self, *, params: types.PaginatedRequestParams | None = None
 
         return result
 
-    async def send_roots_list_changed(self) -> None:  # pragma: no cover
+    async def send_roots_list_changed(self) -> None:
         """Send a roots/list_changed notification."""
         await self.send_notification(types.RootsListChangedNotification())
 

src/mcp/server/session.py

@@ -479,11 +479,11 @@ async def send_resource_list_changed(self) -> None:
         """Send a resource list changed notification."""
         await self.send_notification(types.ResourceListChangedNotification())
 
-    async def send_tool_list_changed(self) -> None:  # pragma: no cover
+    async def send_tool_list_changed(self) -> None:
         """Send a tool list changed notification."""
         await self.send_notification(types.ToolListChangedNotification())
 
-    async def send_prompt_list_changed(self) -> None:  # pragma: no cover
+    async def send_prompt_list_changed(self) -> None:
         """Send a prompt list changed notification."""
         await self.send_notification(types.PromptListChangedNotification())
 

tests/interaction/_requirements.py

@@ -96,6 +96,61 @@ class Requirement:
         ),
     ),
     # ═══════════════════════════════════════════════════════════════════════════
+    # Cancellation
+    # ═══════════════════════════════════════════════════════════════════════════
+    "cancellation:in-flight": Requirement(
+        source=f"{SPEC_BASE_URL}/basic/utilities/cancellation#behavior-requirements",
+        behavior=(
+            "A cancellation notification for an in-flight request stops the server-side handler, and the "
+            "caller's pending request fails with an error response."
+        ),
+        divergence=Divergence(
+            note=(
+                "The spec says receivers of a cancellation SHOULD NOT send a response for the cancelled "
+                "request; the server sends an error response (code 0, 'Request cancelled'), which is what "
+                "unblocks the SDK client's pending call."
+            ),
+        ),
+    ),
+    "cancellation:server-survives": Requirement(
+        source=f"{SPEC_BASE_URL}/basic/utilities/cancellation#behavior-requirements",
+        behavior="The session continues to serve new requests after an earlier request was cancelled.",
+    ),
+    "cancellation:unknown-request": Requirement(
+        source=f"{SPEC_BASE_URL}/basic/utilities/cancellation#behavior-requirements",
+        behavior=(
+            "A cancellation notification referencing an unknown or already-completed request is ignored without error."
+        ),
+    ),
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Progress
+    # ═══════════════════════════════════════════════════════════════════════════
+    "progress:server-to-client": Requirement(
+        source=f"{SPEC_BASE_URL}/basic/utilities/progress#progress-flow",
+        behavior=(
+            "Progress notifications emitted by a handler during a request are delivered to the caller's "
+            "progress callback, in order, with their progress, total, and message."
+        ),
+    ),
+    "progress:token-propagation": Requirement(
+        source=f"{SPEC_BASE_URL}/basic/utilities/progress#progress-flow",
+        behavior=(
+            "Supplying a progress callback attaches a progress token to the outgoing request, which the "
+            "server-side handler can observe in its request metadata."
+        ),
+    ),
+    "progress:no-token": Requirement(
+        source=f"{SPEC_BASE_URL}/basic/utilities/progress#progress-flow",
+        behavior=(
+            "Without a progress callback no token is attached, and a handler that reports progress anyway "
+            "sends nothing."
+        ),
+    ),
+    "progress:client-to-server": Requirement(
+        source=f"{SPEC_BASE_URL}/basic/utilities/progress#progress-flow",
+        behavior="A progress notification sent by the client is delivered to the server's progress handler.",
+    ),
+    # ═══════════════════════════════════════════════════════════════════════════
     # Ping
     # ═══════════════════════════════════════════════════════════════════════════
     "ping:client-to-server": Requirement(
@@ -229,6 +284,21 @@ class Requirement:
         behavior="resources/read for an unknown URI returns a JSON-RPC error; the spec reserves -32002 for it.",
     ),
     # ═══════════════════════════════════════════════════════════════════════════
+    # Notifications: list_changed (server → client)
+    # ═══════════════════════════════════════════════════════════════════════════
+    "notifications:tools:list-changed": Requirement(
+        source=f"{SPEC_BASE_URL}/server/tools#list-changed-notification",
+        behavior="A tools/list_changed notification sent by the server reaches the client's message handler.",
+    ),
+    "notifications:resources:list-changed": Requirement(
+        source=f"{SPEC_BASE_URL}/server/resources#list-changed-notification",
+        behavior="A resources/list_changed notification sent by the server reaches the client's message handler.",
+    ),
+    "notifications:prompts:list-changed": Requirement(
+        source=f"{SPEC_BASE_URL}/server/prompts#list-changed-notification",
+        behavior="A prompts/list_changed notification sent by the server reaches the client's message handler.",
+    ),
+    # ═══════════════════════════════════════════════════════════════════════════
     # Prompts
     # ═══════════════════════════════════════════════════════════════════════════
     "prompts:list:basic": Requirement(
@@ -248,6 +318,88 @@ class Requirement:
         behavior="prompts/get for an unknown prompt name returns a JSON-RPC error.",
     ),
     # ═══════════════════════════════════════════════════════════════════════════
+    # Sampling (server → client)
+    # ═══════════════════════════════════════════════════════════════════════════
+    "sampling:create-message:round-trip": Requirement(
+        source=f"{SPEC_BASE_URL}/client/sampling#creating-messages",
+        behavior=(
+            "A sampling/createMessage request from a server handler is answered by the client's sampling "
+            "callback, and the callback's result (role, content, model, stopReason) is returned to the handler."
+        ),
+    ),
+    "sampling:create-message:params": Requirement(
+        source=f"{SPEC_BASE_URL}/client/sampling#creating-messages",
+        behavior=(
+            "The sampling parameters supplied by the server (messages, maxTokens, systemPrompt, "
+            "modelPreferences, temperature, stopSequences) reach the client callback intact."
+        ),
+    ),
+    "sampling:create-message:image-content": Requirement(
+        source=f"{SPEC_BASE_URL}/client/sampling#message-content",
+        behavior="Sampling messages can carry image content: base64 data with a mimeType.",
+    ),
+    "sampling:create-message:client-error": Requirement(
+        source=f"{SPEC_BASE_URL}/client/sampling#error-handling",
+        behavior="A sampling callback that returns an error is surfaced to the requesting handler as an MCPError.",
+    ),
+    "sampling:create-message:not-supported": Requirement(
+        source=f"{SPEC_BASE_URL}/client/sampling#capabilities",
+        behavior=(
+            "A sampling request to a client that did not declare the sampling capability fails with an "
+            "error rather than hanging or being silently dropped."
+        ),
+    ),
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Elicitation (server → client)
+    # ═══════════════════════════════════════════════════════════════════════════
+    "elicitation:form:accept": Requirement(
+        source=f"{SPEC_BASE_URL}/client/elicitation#form-mode-elicitation",
+        behavior=(
+            "A form-mode elicitation answered with action 'accept' returns the user's content to the "
+            "requesting handler, validated against the requested schema."
+        ),
+    ),
+    "elicitation:form:decline": Requirement(
+        source=f"{SPEC_BASE_URL}/client/elicitation#response-actions",
+        behavior="A form-mode elicitation answered with action 'decline' returns no content to the handler.",
+    ),
+    "elicitation:form:cancel": Requirement(
+        source=f"{SPEC_BASE_URL}/client/elicitation#response-actions",
+        behavior="A form-mode elicitation answered with action 'cancel' returns no content to the handler.",
+    ),
+    "elicitation:form:not-supported": Requirement(
+        source=f"{SPEC_BASE_URL}/client/elicitation#capabilities",
+        behavior=(
+            "An elicitation request to a client that did not declare the elicitation capability fails with "
+            "an error rather than hanging or being silently dropped."
+        ),
+    ),
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Roots (server → client)
+    # ═══════════════════════════════════════════════════════════════════════════
+    "roots:list:round-trip": Requirement(
+        source=f"{SPEC_BASE_URL}/client/roots#listing-roots",
+        behavior=(
+            "A roots/list request from a server handler is answered by the client's roots callback, and "
+            "the returned roots (uri, name) reach the handler."
+        ),
+    ),
+    "roots:list:empty": Requirement(
+        source=f"{SPEC_BASE_URL}/client/roots#listing-roots",
+        behavior="An empty roots list is a valid response and reaches the handler as such.",
+    ),
+    "roots:list:not-supported": Requirement(
+        source=f"{SPEC_BASE_URL}/client/roots#capabilities",
+        behavior=(
+            "A roots/list request to a client that did not declare the roots capability fails with an "
+            "error rather than hanging or being silently dropped."
+        ),
+    ),
+    "roots:list-changed": Requirement(
+        source=f"{SPEC_BASE_URL}/client/roots#root-list-changes",
+        behavior="A roots/list_changed notification sent by the client is delivered to the server's handler.",
+    ),
+    # ═══════════════════════════════════════════════════════════════════════════
     # MCPServer behavioural guarantees (not spec-mandated)
     # ═══════════════════════════════════════════════════════════════════════════
     "mcpserver:tools:output-schema:model": Requirement(

tests/interaction/lowlevel/test_cancellation.py

@@ -0,0 +1,138 @@
+"""Cancellation interactions against the low-level Server, driven through the public Client API.
+
+There is no client-side cancellation API: cancelling means sending a CancelledNotification
+carrying the request id, which only the server-side handler can observe (`ctx.request_id`), so
+these tests capture the id from inside the blocked handler before cancelling. The handler blocks
+on an Event rather than a sleep, and every wait is bounded by `anyio.fail_after`.
+"""
+
+import anyio
+import pytest
+from inline_snapshot import snapshot
+
+from mcp import MCPError, types
+from mcp.client.client import Client
+from mcp.server import Server, ServerRequestContext
+from mcp.types import CallToolResult, ErrorData, TextContent
+from tests.interaction._requirements import requirement
+
+pytestmark = pytest.mark.anyio
+
+
+@requirement("cancellation:in-flight")
+async def test_cancellation_stops_in_flight_handler() -> None:
+    """Cancelling an in-flight request interrupts its handler and fails the pending call.
+
+    The server answers the cancelled request with an error response (the spec says it should
+    not respond at all; see the divergence note on the requirement), so the caller's pending
+    request raises rather than hanging.
+    """
+    started = anyio.Event()
+    handler_cancelled = anyio.Event()
+    request_ids: list[types.RequestId] = []
+    errors: list[ErrorData] = []
+
+    async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:
+        assert params.name == "block"
+        assert ctx.request_id is not None
+        request_ids.append(ctx.request_id)
+        started.set()
+        try:
+            await anyio.Event().wait()  # blocks until cancelled; nothing ever sets this event
+        except anyio.get_cancelled_exc_class():
+            handler_cancelled.set()
+            raise
+        raise NotImplementedError  # unreachable: the wait above never completes normally
+
+    server = Server("blocker", on_call_tool=call_tool)
+
+    async with Client(server) as client:
+        with anyio.fail_after(5):
+            async with anyio.create_task_group() as task_group:
+
+                async def call_and_capture_error() -> None:
+                    with pytest.raises(MCPError) as exc_info:
+                        await client.call_tool("block", {})
+                    errors.append(exc_info.value.error)
+
+                task_group.start_soon(call_and_capture_error)
+                await started.wait()
+                await client.session.send_notification(
+                    types.CancelledNotification(
+                        params=types.CancelledNotificationParams(request_id=request_ids[0], reason="user aborted")
+                    )
+                )
+
+            await handler_cancelled.wait()
+
+    assert errors == snapshot([ErrorData(code=0, message="Request cancelled")])
+
+
+@requirement("cancellation:server-survives")
+async def test_session_serves_requests_after_cancellation() -> None:
+    """A request cancelled mid-flight does not poison the session: the next request succeeds."""
+    started = anyio.Event()
+    request_ids: list[types.RequestId] = []
+
+    async def list_tools(
+        ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        return types.ListToolsResult(
+            tools=[
+                types.Tool(name="block", input_schema={"type": "object"}),
+                types.Tool(name="echo", input_schema={"type": "object"}),
+            ]
+        )
+
+    async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:
+        if params.name == "echo":
+            return CallToolResult(content=[TextContent(text="still alive")])
+        assert ctx.request_id is not None
+        request_ids.append(ctx.request_id)
+        started.set()
+        await anyio.Event().wait()  # blocks until cancelled
+        raise NotImplementedError  # unreachable
+
+    server = Server("blocker", on_list_tools=list_tools, on_call_tool=call_tool)
+
+    async with Client(server) as client:
+        with anyio.fail_after(5):
+            async with anyio.create_task_group() as task_group:
+
+                async def call_and_swallow_cancellation_error() -> None:
+                    with pytest.raises(MCPError):
+                        await client.call_tool("block", {})
+
+                task_group.start_soon(call_and_swallow_cancellation_error)
+                await started.wait()
+                await client.session.send_notification(
+                    types.CancelledNotification(params=types.CancelledNotificationParams(request_id=request_ids[0]))
+                )
+
+            result = await client.call_tool("echo", {})
+
+    assert result == snapshot(CallToolResult(content=[TextContent(text="still alive")]))
+
+
+@requirement("cancellation:unknown-request")
+async def test_cancellation_for_unknown_request_is_ignored() -> None:
+    """A cancellation referencing a request id that is not in flight is ignored without error."""
+
+    async def list_tools(
+        ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=[types.Tool(name="echo", input_schema={"type": "object"})])
+
+    async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:
+        assert params.name == "echo"
+        return CallToolResult(content=[TextContent(text="unbothered")])
+
+    server = Server("calm", on_list_tools=list_tools, on_call_tool=call_tool)
+
+    async with Client(server) as client:
+        await client.session.send_notification(
+            types.CancelledNotification(params=types.CancelledNotificationParams(request_id=9999))
+        )
+        result = await client.call_tool("echo", {})
+
+    assert result == snapshot(CallToolResult(content=[TextContent(text="unbothered")]))