Resolve tool output-schema references within the schema document only

The client validated `structuredContent` with a jsonschema validator built
on the library's default registry, which retrieves any `$ref` it cannot
resolve locally over the network or filesystem, synchronously, on every
call. The 2026-07-28 spec requires that non-local `$ref`s are not
dereferenced by default and that a schema failing on an unresolved
external reference is rejected rather than treated as permissive.

Build the validator with an empty `referencing.Registry` so references
resolve inside the tool's schema (and the bundled metaschemas) and
nowhere else, and surface an unresolvable reference from `call_tool` as
the documented `RuntimeError` instead of a `referencing` exception.

Author: maxisbey

docs/advanced/low-level-server.md

@@ -121,6 +121,7 @@ The server never compares the two fields. This SDK's `Client` does: return `stru
 
 * The root of `input_schema` must be `"type": "object"`. Beside it, `oneOf`, `additionalProperties`, `anyOf`, `if`/`then`/`else`, `prefixItems`, `$defs` with local `$ref`s and the rest of the 2020-12 keywords reach the client exactly as written.
 * No `$schema` key is needed. Add one only to opt into an older draft: this SDK's `Client`, which validates `structured_content` against a tool's `output_schema`, picks its validator from `$schema` and uses 2020-12 when there is none.
+* Keep `$ref`s inside the schema (`#/$defs/...`, `$anchor`, an embedded `$id`). The `Client` never fetches a reference to another document, URL or file: a result whose validation reaches one fails with a `RuntimeError` that starts with `Invalid schema for tool <name>`.
 
 ## `_meta`: for the application, not the model
 

src/mcp/client/session.py

@@ -1126,7 +1126,8 @@ async def validate_tool_result(self, name: str, result: types.CallToolResult) ->
         """Revalidate a `CallToolResult` against the tool's declared output schema.
 
         Raises:
-            RuntimeError: Structured content is missing or does not conform to the schema.
+            RuntimeError: Structured content is missing or does not conform to the schema, or the
+                schema is invalid or has a `$ref` that does not resolve within the schema document.
         """
         if name not in self._tool_output_schemas:
             # refresh output schema cache
@@ -1140,17 +1141,22 @@ async def validate_tool_result(self, name: str, result: types.CallToolResult) ->
 
         if output_schema is not None:
             from jsonschema import exceptions as jsonschema_exceptions
+            from referencing.exceptions import Unresolvable
 
             if result.structured_content is None:
                 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,
             # so the message a caller sees is unchanged. It is untyped upstream.
             errors = validator.iter_errors(result.structured_content)
-            error = cast(
-                "Exception | None",
-                jsonschema_exceptions.best_match(errors),  # pyright: ignore[reportUnknownMemberType]
-            )
+            try:
+                error = cast(
+                    "Exception | None",
+                    jsonschema_exceptions.best_match(errors),  # pyright: ignore[reportUnknownMemberType]
+                )
+            except Unresolvable as e:
+                # A `$ref` did not resolve within the schema document; nothing outside it is retrieved.
+                raise RuntimeError(f"Invalid schema for tool {name}: {e}") from e
             if error is not None:
                 raise RuntimeError(f"Invalid structured content returned by tool {name}: {error}") from error
 
@@ -1168,6 +1174,7 @@ def _output_schema_validator(self, name: str, output_schema: dict[str, Any]) ->
         """
         from jsonschema import SchemaError
         from jsonschema.validators import validator_for
+        from referencing import Registry
 
         if (validator := self._tool_output_validators.get(name)) is not None:
             return validator
@@ -1177,9 +1184,9 @@ def _output_schema_validator(self, name: str, output_schema: dict[str, Any]) ->
             validator_cls.check_schema(output_schema)
         except SchemaError as e:
             raise RuntimeError(f"Invalid schema for tool {name}: {e}")
-        # jsonschema ships no `py.typed`, so pyright reads typeshed's stub, which declares
-        # `registry` as required (concrete validators default it); cast to a schema-only ctor.
-        validator = cast("Callable[[dict[str, Any]], Validator]", validator_cls)(output_schema)
+        # An empty registry resolves `$ref`s within the schema document only; jsonschema's
+        # default one retrieves any other URI over the network or filesystem.
+        validator = validator_cls(output_schema, registry=Registry())
         self._tool_output_validators[name] = validator
         return validator
 

tests/client/test_output_schema_validation.py

@@ -1,4 +1,5 @@
 import logging
+from pathlib import Path
 from typing import Any
 
 import pytest
@@ -10,6 +11,7 @@
     TextContent,
     Tool,
 )
+from referencing.exceptions import Unresolvable
 
 from mcp import Client
 from mcp.server import Server, ServerRequestContext
@@ -163,3 +165,28 @@ async def on_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams)
         assert result.is_error is False
 
         assert "Tool mystery_tool not listed" in caplog.text
+
+
+# jsonschema's default registry warns only after it has fetched a reference; keep that a plain
+# warning here so a client that did fetch the (permissive) file would go on to accept the result.
+@pytest.mark.filterwarnings("default:Automatically retrieving remote references:DeprecationWarning")
+@pytest.mark.anyio
+async def test_output_schema_ref_outside_the_document_is_rejected_without_being_retrieved(tmp_path: Path):
+    """A `$ref` to a URI outside the output schema is never fetched, and a result whose validation
+    reaches one fails as an invalid schema (spec `$ref` resolution: non-local dereferencing is off by
+    default and an unresolved external `$ref` SHOULD be rejected; treating `file:` like a network
+    URI is SDK-defined)."""
+    # Permissive target: had the client read it, `{"v": 1}` would have validated.
+    permissive = tmp_path / "permissive.json"
+    permissive.write_text("{}", encoding="utf-8")
+    server = _make_server(
+        tools=[Tool(name="probe", input_schema={"type": "object"}, output_schema={"$ref": permissive.as_uri()})],
+        structured_content={"v": 1},
+    )
+
+    async with Client(server) as client:
+        with pytest.raises(RuntimeError) as exc_info:
+            await client.call_tool("probe", {})
+    # SDK-authored prefix only; the tail is `referencing`'s text plus a tmp path.
+    assert str(exc_info.value).startswith("Invalid schema for tool probe: ")
+    assert isinstance(exc_info.value.__cause__, Unresolvable)