Validate an explicit null structuredContent against the output schema

The client treated a `structuredContent` of JSON null the same as an
absent field and raised "has an output schema but did not return
structured content". Since 2026-07-28 null is a legal structured result,
so only an absent field is reported as missing now; an explicit null is
validated against the tool's output schema like any other value.

Fixes #3345

Author: maxisbey

src/mcp/client/session.py

@@ -1136,7 +1136,7 @@ async def validate_tool_result(self, name: str, result: types.CallToolResult) ->
             from jsonschema import exceptions as jsonschema_exceptions
             from referencing.exceptions import Unresolvable
 
-            if result.structured_content is None:
+            if result.structured_content is None and "structured_content" not in result.model_fields_set:
                 raise RuntimeError(f"Tool {name} has an output schema but did not return structured content")
             validator = self._output_schema_validator(name, output_schema)
             # `best_match` picks the same error the previous `jsonschema.validate()` call raised,

tests/client/test_session.py

@@ -9,6 +9,7 @@
 import anyio.streams.memory
 import mcp_types as types
 import pytest
+from inline_snapshot import snapshot
 from mcp_types import (
     CONNECTION_CLOSED,
     INTERNAL_ERROR,
@@ -1828,6 +1829,70 @@ async def test_a_2026_result_type_tag_from_a_legacy_server_never_reaches_the_res
     assert result.result_type == "complete"
 
 
+# --- null structuredContent ---
+# The results are scripted: a server built on this SDK leaves a null `structuredContent` off the wire.
+
+
+def _listing_with_output_schema(output_schema: dict[str, Any]) -> dict[str, Any]:
+    tool = {"name": "t", "inputSchema": {"type": "object"}, "outputSchema": output_schema}
+    return {"resultType": "complete", "tools": [tool], "ttlMs": 0, "cacheScope": "private"}
+
+
+@pytest.mark.anyio
+async def test_call_tool_accepts_a_null_structured_content_the_output_schema_permits() -> None:
+    """Spec (2026-07-28): `structuredContent` may be any JSON value, null included, so a null
+    the output schema permits is a valid result rather than missing structured content."""
+    dispatcher = _ScriptedDispatcher(
+        _discover_result_dict(),
+        _listing_with_output_schema({"type": ["object", "null"]}),
+        {"resultType": "complete", "content": [], "structuredContent": None},
+    )
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.discover()
+            await session.list_tools()
+            result = await session.call_tool("t", {})
+    assert isinstance(result, CallToolResult)
+    assert result.structured_content is None
+
+
+@pytest.mark.anyio
+async def test_call_tool_rejects_a_null_structured_content_the_output_schema_forbids() -> None:
+    """A null `structuredContent` is validated like any other value: against a schema that does
+    not permit null it fails as a schema mismatch, not as missing structured content."""
+    dispatcher = _ScriptedDispatcher(
+        _discover_result_dict(),
+        _listing_with_output_schema({"type": "object"}),
+        {"resultType": "complete", "content": [], "structuredContent": None},
+    )
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.discover()
+            await session.list_tools()
+            with pytest.raises(RuntimeError) as exc_info:
+                await session.call_tool("t", {})
+            # Stable SDK prefix only: the message tail is jsonschema text that shifts with the dependency.
+            assert str(exc_info.value).startswith("Invalid structured content returned by tool t")
+
+
+@pytest.mark.anyio
+async def test_call_tool_reports_an_absent_structured_content_as_missing_even_when_null_is_permitted() -> None:
+    """SDK-defined: only a result with no `structuredContent` field at all is reported as
+    missing structured content, and it is so even when the output schema would accept null."""
+    dispatcher = _ScriptedDispatcher(
+        _discover_result_dict(),
+        _listing_with_output_schema({"type": ["object", "null"]}),
+        {"resultType": "complete", "content": []},
+    )
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.discover()
+            await session.list_tools()
+            with pytest.raises(RuntimeError) as exc_info:
+                await session.call_tool("t", {})
+            assert str(exc_info.value) == snapshot("Tool t has an output schema but did not return structured content")
+
+
 @pytest.mark.anyio
 async def test_session_call_tool_returns_input_required_result_when_opted_in() -> None:
     """`ClientSession.call_tool(..., allow_input_required=True)` surfaces the