Align SEP-2106 $ref handling to the spec

The SEP requires implementations to never auto-dereference network $refs (a
MUST NOT, already satisfied: the SDK has no $ref-fetching code) and to reject a
schema only when validation hits an unresolved external $ref (a conditional
SHOULD). Drop the eager registration-time rejection added earlier - it forbade
legitimate, never-fetched external $refs, going beyond the spec. Keep the
conformance burn-down and add a client test confirming an unexercised network
$ref in an output schema is not dereferenced.

Author: Kludex

docs/migration.md

@@ -240,12 +240,6 @@ 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.

src/mcp/server/mcpserver/tools/base.py

@@ -8,7 +8,7 @@
 
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp.server.mcpserver.utilities.context_injection import find_context_parameter
-from mcp.server.mcpserver.utilities.func_metadata import FuncMetadata, StrictJsonSchema, func_metadata
+from mcp.server.mcpserver.utilities.func_metadata import FuncMetadata, func_metadata
 from mcp.shared._callable_inspection import is_async_callable
 from mcp.shared.exceptions import UrlElicitationRequiredError
 from mcp.shared.tool_name_validation import validate_and_warn_tool_name
@@ -53,12 +53,7 @@ def from_function(
         meta: dict[str, Any] | None = None,
         structured_output: bool | None = None,
     ) -> Tool:
-        """Create a Tool from a function.
-
-        Raises:
-            ExternalSchemaRefError: If the generated input or output schema contains a
-                `$ref` that is not a same-document reference (SEP-2106).
-        """
+        """Create a Tool from a function."""
         func_name = name or fn.__name__
 
         validate_and_warn_tool_name(func_name)
@@ -77,7 +72,7 @@ def from_function(
             skip_names=[context_kwarg] if context_kwarg is not None else [],
             structured_output=structured_output,
         )
-        parameters = func_arg_metadata.arg_model.model_json_schema(by_alias=True, schema_generator=StrictJsonSchema)
+        parameters = func_arg_metadata.arg_model.model_json_schema(by_alias=True)
 
         return cls(
             fn=fn,

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -11,8 +11,7 @@
 import pydantic_core
 from pydantic import BaseModel, ConfigDict, Field, PydanticUserError, WithJsonSchema, create_model
 from pydantic.fields import FieldInfo
-from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue, JsonSchemaWarningKind
-from pydantic_core import CoreSchema
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaWarningKind
 from typing_extensions import is_typeddict
 from typing_inspection.introspection import (
     UNKNOWN,
@@ -30,55 +29,16 @@
 logger = get_logger(__name__)
 
 
-class ExternalSchemaRefError(Exception):
-    """A tool schema contains a `$ref` that is not a same-document reference.
-
-    Deliberately not a `ValueError`: schema generation treats a `ValueError` as
-    an unserializable type and degrades gracefully, but an external `$ref` is a
-    hard error that must surface at tool registration.
-    """
-
-
 class StrictJsonSchema(GenerateJsonSchema):
-    """Render tool schemas, raising on pydantic warnings and external `$ref`s.
+    """A JSON schema generator that raises exceptions instead of emitting warnings.
 
-    Warnings (e.g. a non-serializable type) become errors so they surface at tool
-    registration instead of silently producing a degenerate schema. External
-    `$ref`s, which pydantic never emits itself but a user can inject via
-    `Field(json_schema_extra=...)`, are an SSRF / fetch-DoS vector and are
-    rejected for the same reason (SEP-2106).
-
-    See: https://modelcontextprotocol.io/seps/2106-json-schema-2020-12#security-implications
+    This is used to detect non-serializable types during schema generation.
     """
 
     def emit_warning(self, kind: JsonSchemaWarningKind, detail: str) -> None:
+        # Raise an exception instead of emitting a warning
         raise ValueError(f"JSON schema warning: {kind} - {detail}")
 
-    def generate(self, schema: CoreSchema, mode: Any = "validation") -> JsonSchemaValue:
-        json_schema = super().generate(schema, mode)
-        external = sorted(_find_external_refs(json_schema))
-        if external:
-            raise ExternalSchemaRefError(
-                f"Tool schema contains external $ref(s) that MUST NOT be dereferenced (SEP-2106): "
-                f"{', '.join(external)}. Only same-document references (e.g. '#/$defs/Foo') are allowed."
-            )
-        return json_schema
-
-
-def _find_external_refs(node: Any) -> set[str]:
-    external: set[str] = set()
-    if isinstance(node, dict):
-        mapping = cast("dict[str, Any]", node)
-        ref = mapping.get("$ref")
-        if isinstance(ref, str) and not ref.startswith("#"):
-            external.add(ref)
-        for value in mapping.values():
-            external |= _find_external_refs(value)
-    elif isinstance(node, list):
-        for item in cast("list[Any]", node):
-            external |= _find_external_refs(item)
-    return external
-
 
 class ArgModelBase(BaseModel):
     """A model representing the arguments to a function."""

tests/client/test_output_schema_validation.py

@@ -163,3 +163,38 @@ async def on_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams)
         assert result.is_error is False
 
         assert "Tool mystery_tool not listed" in caplog.text
+
+
+@pytest.mark.anyio
+async def test_client_does_not_dereference_network_ref():
+    """SEP-2106: validating a result must not fetch a network `$ref` in the output schema.
+
+    The output schema references a network URI under a property the structured content
+    never sets, so a compliant client validates without resolving (and therefore without
+    fetching) the ref.
+    """
+    output_schema = {
+        "type": "object",
+        "properties": {
+            "ok": {"type": "boolean"},
+            "profile": {"$ref": "https://canary.invalid/profile-schema.json"},
+        },
+        "required": ["ok"],
+    }
+
+    server = _make_server(
+        tools=[
+            Tool(
+                name="lookup",
+                description="Look something up",
+                input_schema={"type": "object"},
+                output_schema=output_schema,
+            )
+        ],
+        structured_content={"ok": True},
+    )
+
+    async with Client(server) as client:
+        result = await client.call_tool("lookup", {})
+        assert result.is_error is False
+        assert result.structured_content == {"ok": True}

tests/server/mcpserver/test_func_metadata.py

@@ -13,7 +13,7 @@
 from pydantic import BaseModel, Field
 
 from mcp.server.mcpserver.exceptions import InvalidSignature
-from mcp.server.mcpserver.utilities.func_metadata import ExternalSchemaRefError, StrictJsonSchema, func_metadata
+from mcp.server.mcpserver.utilities.func_metadata import func_metadata
 from mcp.types import CallToolResult
 
 
@@ -1191,34 +1191,3 @@ def func_with_metadata() -> Annotated[int, Field(gt=1)]: ...  # pragma: no branc
 
     assert meta.output_schema is not None
     assert meta.output_schema["properties"]["result"] == {"exclusiveMinimum": 1, "title": "Result", "type": "integer"}
-
-
-def test_strict_json_schema_allows_same_document_refs():
-    class Inner(BaseModel):
-        x: int
-
-    class Model(BaseModel):
-        inner: Inner
-
-    schema = Model.model_json_schema(schema_generator=StrictJsonSchema)
-    assert "$defs" in schema
-    assert schema["properties"]["inner"]["$ref"] == "#/$defs/Inner"
-
-
-def test_strict_json_schema_rejects_external_ref_in_property():
-    class Model(BaseModel):
-        profile: Annotated[dict[str, Any], Field(json_schema_extra={"$ref": "https://evil.example/s.json"})]
-
-    with pytest.raises(ExternalSchemaRefError, match="https://evil.example/s.json"):
-        Model.model_json_schema(schema_generator=StrictJsonSchema)
-
-
-def test_strict_json_schema_rejects_external_ref_nested_in_list():
-    class Model(BaseModel):
-        items: Annotated[
-            list[str],
-            Field(json_schema_extra={"prefixItems": [{"$ref": "https://evil.example/a.json"}]}),
-        ]
-
-    with pytest.raises(ExternalSchemaRefError, match="https://evil.example/a.json"):
-        Model.model_json_schema(schema_generator=StrictJsonSchema)

tests/server/mcpserver/test_tool_manager.py

@@ -1,16 +1,16 @@
 import json
 import logging
 from dataclasses import dataclass
-from typing import Annotated, Any, TypedDict
+from typing import Any, TypedDict
 
 import pytest
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 
 from mcp.server.context import LifespanContextT, RequestT
 from mcp.server.mcpserver import Context, MCPServer
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp.server.mcpserver.tools import Tool, ToolManager
-from mcp.server.mcpserver.utilities.func_metadata import ArgModelBase, ExternalSchemaRefError, FuncMetadata
+from mcp.server.mcpserver.utilities.func_metadata import ArgModelBase, FuncMetadata
 from mcp.types import CallToolResult, TextContent, ToolAnnotations
 
 
@@ -904,46 +904,3 @@ def test_func() -> str:  # pragma: no cover
         # Remove with correct case
         manager.remove_tool("test_func")
         assert manager.get_tool("test_func") is None
-
-
-def test_add_tool_rejects_external_input_ref():
-    """SEP-2106: a tool whose input schema carries an external $ref is rejected at registration."""
-
-    def lookup(
-        profile: Annotated[dict[str, Any], Field(json_schema_extra={"$ref": "https://evil.example/s.json"})],
-    ) -> None:  # pragma: no cover
-        ...
-
-    manager = ToolManager()
-    with pytest.raises(ExternalSchemaRefError, match="https://evil.example/s.json"):
-        manager.add_tool(lookup)
-    assert manager.get_tool("lookup") is None
-
-
-def test_add_tool_rejects_external_output_ref():
-    """SEP-2106: a tool whose output schema carries an external $ref is rejected at registration."""
-
-    class Out(BaseModel):
-        value: Annotated[str, Field(json_schema_extra={"$ref": "https://evil.example/out.json"})]
-
-    def lookup() -> Out:  # pragma: no cover
-        ...
-
-    manager = ToolManager()
-    with pytest.raises(ExternalSchemaRefError, match="https://evil.example/out.json"):
-        manager.add_tool(lookup)
-    assert manager.get_tool("lookup") is None
-
-
-def test_add_tool_allows_same_document_refs():
-    """Pydantic-generated `#/$defs/...` refs from nested models must pass registration."""
-
-    class Inner(BaseModel):
-        x: int
-
-    def good(inner: Inner) -> Inner:  # pragma: no cover
-        ...
-
-    manager = ToolManager()
-    tool = manager.add_tool(good)
-    assert "$defs" in tool.parameters