Burn down json-schema-ref-no-deref conformance scenario

Add a driver handler for the scenario (the missing handler was why it failed,
not actual dereferencing) and remove it from both expected-failures baselines.
Document the server-side external-$ref rejection in the migration guide.

Author: Kludex

.github/actions/conformance/client.py

@@ -185,6 +185,16 @@ async def run_tools_call(server_url: str) -> None:
             logger.debug(f"add_numbers result: {result}")
 
 
+@register("json-schema-ref-no-deref")
+async def run_json_schema_ref_no_deref(server_url: str) -> None:
+    """List tools whose schemas contain a network `$ref`; must not dereference it (SEP-2106)."""
+    async with streamable_http_client(url=server_url) as (read_stream, write_stream):
+        async with ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+            tools_result = await session.list_tools()
+            logger.debug(f"Listed tools without dereferencing network $refs: {[t.name for t in tools_result.tools]}")
+
+
 @register("sse-retry")
 async def run_sse_retry(server_url: str) -> None:
     """Connect, initialize, list tools, call test_reconnection, close."""

.github/actions/conformance/expected-failures.2026-07-28.yml

@@ -63,8 +63,6 @@ client:
   # SEP-2243 (HTTP standardization): no fixture handler / client header support yet.
   - http-custom-headers
   - http-invalid-tool-headers
-  # SEP-2106 (JSON Schema $ref handling): client still dereferences network $refs.
-  - json-schema-ref-no-deref
   # SEP-2468 (authorization response iss parameter): not implemented in the client.
   - auth/iss-supported
   - auth/iss-not-advertised

.github/actions/conformance/expected-failures.yml

@@ -22,8 +22,6 @@ client:
   # SEP-2243 (HTTP standardization): no fixture handler / client header support yet.
   - http-custom-headers
   - http-invalid-tool-headers
-  # SEP-2106 (JSON Schema $ref handling): client still dereferences network $refs.
-  - json-schema-ref-no-deref
   # SEP-2468 (authorization response iss parameter): not implemented in the client.
   - auth/iss-supported
   - auth/iss-not-advertised

docs/migration.md

@@ -240,6 +240,12 @@ Results returned from server handlers are now validated against the negotiated p
 
 `ClientSession` now validates server requests, notifications, and results against the negotiated protocol version's schema before parsing them into `mcp.types` models. Spec-invalid server output that the previous monolith parse tolerated may now raise `pydantic.ValidationError` from `list_tools()`, `call_tool()`, and similar calls. `_meta` remains the sanctioned place for result extras (and `experimental` for capability extras).
 
+### External JSON Schema `$ref`s are rejected in tool schemas (SEP-2106)
+
+SEP-2106 permits the full JSON Schema 2020-12 vocabulary in tool schemas, including `$ref`. A `$ref` that resolves to a network URI is an SSRF / fetch-DoS vector, so per the spec implementations must never automatically dereference any `$ref` that is not a same-document reference (a JSON Pointer such as `#/$defs/Foo` or an `$anchor` such as `#Foo`).
+
+Registering a tool whose generated input or output schema contains an external `$ref` now raises `ExternalSchemaRefError` (from `mcp.server.mcpserver.utilities.func_metadata`). Schemas pydantic generates from your type hints only ever use same-document refs, so this affects you only if you inject an external `$ref` into a schema, e.g. via `Field(json_schema_extra=...)`. To migrate, inline the referenced schema or point the `$ref` at a same-document `$defs` entry.
+
 ### `args` parameter removed from `ClientSessionGroup.call_tool()`
 
 The deprecated `args` parameter has been removed from `ClientSessionGroup.call_tool()`. Use `arguments` instead.