Reject external JSON Schema $ref in tool schemas (SEP-2106)

SEP-2106 permits the full JSON Schema 2020-12 vocabulary in tool schemas,
including $ref. A $ref resolving to a network URI is an SSRF / fetch-DoS
vector, so per the spec implementations MUST NOT auto-dereference any $ref
that is not a same-document reference.

Add a shared ref-walker that rejects external $refs with ExternalSchemaRefError.
The server now rejects them at tool registration; the client rejects them before
validating a tool result instead of attempting to resolve them. Burn down the
json-schema-ref-no-deref conformance scenario in both expected-failures files
and add a driver handler for it.

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,17 @@ 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 (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 NOT automatically dereference any `$ref` that is not a same-document reference (a JSON Pointer such as `#/$defs/Foo` or an `$anchor` such as `#Foo`).
+
+The SDK never dereferences such refs and now rejects them outright with `ExternalSchemaRefError` (a `ValueError` subclass, importable from `mcp.shared.json_schema_ref`):
+
+- **Server:** registering a tool whose generated input or output schema contains an external `$ref` raises at registration time. Schemas Pydantic generates from your type hints only ever use same-document refs, so this affects you only if you smuggle an external `$ref` into a schema (e.g. via `Field(json_schema_extra=...)`).
+- **Client:** validating a tool result whose output schema contains an external `$ref` raises instead of attempting to resolve it.
+
+To migrate, inline the referenced schema or replace the external `$ref` with a same-document reference into `$defs`.
+
 ### `args` parameter removed from `ClientSessionGroup.call_tool()`
 
 The deprecated `args` parameter has been removed from `ClientSessionGroup.call_tool()`. Use `arguments` instead.

src/mcp/client/session.py

@@ -17,6 +17,7 @@
 from mcp.shared._compat import resync_tracer
 from mcp.shared.dispatcher import CallOptions, DispatchContext, Dispatcher, ProgressFnT
 from mcp.shared.exceptions import MCPError
+from mcp.shared.json_schema_ref import reject_external_refs
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.shared.session import RequestResponder
@@ -449,7 +450,14 @@ async def call_tool(
         *,
         meta: RequestParamsMeta | None = None,
     ) -> types.CallToolResult:
-        """Send a tools/call request with optional progress callback support."""
+        """Send a tools/call request with optional progress callback support.
+
+        Raises:
+            RuntimeError: If the tool declares an output schema but the result's structured
+                content is missing or fails validation against it.
+            ExternalSchemaRefError: If the tool's output schema contains a `$ref` that is not
+                a same-document reference; such refs are never dereferenced (SEP-2106).
+        """
 
         result = await self.send_request(
             types.CallToolRequest(
@@ -482,6 +490,7 @@ async def _validate_tool_result(self, name: str, result: types.CallToolResult) -
 
             if result.structured_content is None:
                 raise RuntimeError(f"Tool {name} has an output schema but did not return structured content")
+            reject_external_refs(output_schema, context=f"Output schema for tool {name!r}")
             try:
                 validate(result.structured_content, output_schema)
             except ValidationError as e:

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

@@ -11,6 +11,7 @@
 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.json_schema_ref import reject_external_refs
 from mcp.shared.tool_name_validation import validate_and_warn_tool_name
 from mcp.types import Icon, ToolAnnotations
 
@@ -53,7 +54,12 @@ def from_function(
         meta: dict[str, Any] | None = None,
         structured_output: bool | None = None,
     ) -> Tool:
-        """Create a Tool from a function."""
+        """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).
+        """
         func_name = name or fn.__name__
 
         validate_and_warn_tool_name(func_name)
@@ -74,6 +80,10 @@ def from_function(
         )
         parameters = func_arg_metadata.arg_model.model_json_schema(by_alias=True)
 
+        reject_external_refs(parameters, context=f"Input schema for tool {func_name!r}")
+        if func_arg_metadata.output_schema is not None:
+            reject_external_refs(func_arg_metadata.output_schema, context=f"Output schema for tool {func_name!r}")
+
         return cls(
             fn=fn,
             name=func_name,

src/mcp/shared/json_schema_ref.py

@@ -0,0 +1,61 @@
+"""External `$ref` detection for JSON Schemas (SEP-2106).
+
+SEP-2106 permits the full JSON Schema 2020-12 vocabulary in tool schemas,
+including `$ref`. A `$ref` resolving to a network URI is an SSRF / fetch-DoS
+vector: implementations MUST NOT automatically dereference `$ref` values that
+are not same-document references (a JSON Pointer such as `#/$defs/Foo` or an
+`$anchor` such as `#Foo`).
+
+See: https://modelcontextprotocol.io/seps/2106-json-schema-2020-12#security-implications
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+
+class ExternalSchemaRefError(ValueError):
+    """A JSON Schema contains a `$ref` that is not a same-document reference."""
+
+
+def is_same_document_ref(ref: str) -> bool:
+    """Whether `ref` is a same-document reference (`#`, `#/...` pointer, or `#anchor`)."""
+    return ref.startswith("#")
+
+
+def find_external_refs(schema: Any) -> list[str]:
+    """Collect every `$ref` in `schema` that is not a same-document reference."""
+    external: list[str] = []
+    _walk(schema, external)
+    return external
+
+
+def reject_external_refs(schema: Any, *, context: str) -> None:
+    """Raise `ExternalSchemaRefError` if `schema` contains a non-same-document `$ref`.
+
+    Args:
+        schema: The JSON Schema (or fragment) to inspect.
+        context: Human-readable label for the schema, used in the error message.
+
+    Raises:
+        ExternalSchemaRefError: If any `$ref` is not a same-document reference.
+    """
+    external = find_external_refs(schema)
+    if external:
+        raise ExternalSchemaRefError(
+            f"{context} contains external $ref(s) that MUST NOT be dereferenced (SEP-2106): "
+            f"{', '.join(external)}. Only same-document references (e.g. '#/$defs/Foo') are allowed."
+        )
+
+
+def _walk(node: Any, external: list[str]) -> None:
+    if isinstance(node, dict):
+        mapping = cast("dict[str, Any]", node)
+        ref = mapping.get("$ref")
+        if isinstance(ref, str) and not is_same_document_ref(ref):
+            external.append(ref)
+        for value in mapping.values():
+            _walk(value, external)
+    elif isinstance(node, list):
+        for item in cast("list[Any]", node):
+            _walk(item, external)

tests/client/test_output_schema_validation.py

@@ -5,6 +5,7 @@
 
 from mcp import Client
 from mcp.server import Server, ServerRequestContext
+from mcp.shared.json_schema_ref import ExternalSchemaRefError
 from mcp.types import (
     CallToolRequestParams,
     CallToolResult,
@@ -163,3 +164,41 @@ 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_refs():
+    """SEP-2106: the client MUST NOT auto-dereference network `$ref`s in tool schemas.
+
+    A tool advertises an input and an output schema containing a network-URI `$ref`.
+    Listing the tool leaves the input schema untouched (the network ref is never
+    resolved), and validating its result rejects the external output-schema ref
+    outright instead of fetching it.
+    """
+    canary_ref = "https://canary.invalid/profile-schema.json"
+
+    input_schema = {"type": "object", "properties": {"profile": {"$ref": canary_ref}}}
+    output_schema = {
+        "type": "object",
+        "properties": {"result": {"$ref": canary_ref}, "ok": {"type": "boolean"}},
+        "required": ["ok"],
+    }
+
+    server = _make_server(
+        tools=[
+            Tool(
+                name="lookup",
+                description="Look something up",
+                input_schema=input_schema,
+                output_schema=output_schema,
+            )
+        ],
+        structured_content={"ok": True},
+    )
+
+    async with Client(server) as client:
+        tools = await client.list_tools()
+        assert tools.tools[0].input_schema == input_schema
+
+        with pytest.raises(ExternalSchemaRefError, match="canary.invalid"):
+            await client.call_tool("lookup", {})

tests/server/mcpserver/test_tool_manager.py

@@ -1,16 +1,17 @@
 import json
 import logging
 from dataclasses import dataclass
-from typing import Any, TypedDict
+from typing import Annotated, Any, TypedDict
 
 import pytest
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 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, FuncMetadata
+from mcp.shared.json_schema_ref import ExternalSchemaRefError
 from mcp.types import CallToolResult, TextContent, ToolAnnotations
 
 
@@ -904,3 +905,46 @@ 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="Input schema for tool 'lookup'"):
+        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="Output schema for tool 'lookup'"):
+        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

tests/shared/test_json_schema_ref.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import pytest
+
+from mcp.shared.json_schema_ref import (
+    ExternalSchemaRefError,
+    find_external_refs,
+    is_same_document_ref,
+    reject_external_refs,
+)
+
+
+@pytest.mark.parametrize(
+    "ref",
+    [
+        "#",
+        "#/$defs/Foo",
+        "#/properties/bar",
+        "#Foo",
+    ],
+)
+def test_same_document_refs_allowed(ref: str):
+    assert is_same_document_ref(ref) is True
+    schema = {"type": "object", "properties": {"x": {"$ref": ref}}}
+    assert find_external_refs(schema) == []
+    reject_external_refs(schema, context="schema")
+
+
+@pytest.mark.parametrize(
+    "ref",
+    [
+        "https://example.com/schema.json",
+        "http://localhost:9999/canary.json",
+        "https://example.com/schema.json#/$defs/Foo",
+        "urn:example:schema",
+        "file:///etc/passwd",
+        "schema.json",
+        "./local.json",
+        "//example.com/schema.json",
+    ],
+)
+def test_external_refs_detected(ref: str):
+    assert is_same_document_ref(ref) is False
+    schema = {"type": "object", "properties": {"x": {"$ref": ref}}}
+    assert find_external_refs(schema) == [ref]
+
+
+def test_reject_external_refs_raises_with_context():
+    schema = {"properties": {"x": {"$ref": "https://evil.example/s.json"}}}
+    with pytest.raises(ExternalSchemaRefError) as exc_info:
+        reject_external_refs(schema, context="Output schema for tool 'lookup'")
+    message = str(exc_info.value)
+    assert "Output schema for tool 'lookup'" in message
+    assert "https://evil.example/s.json" in message
+
+
+def test_find_external_refs_nested_in_lists_and_composition():
+    schema = {
+        "type": "object",
+        "allOf": [
+            {"properties": {"a": {"$ref": "#/$defs/A"}}},
+            {"properties": {"b": {"$ref": "https://example.com/b.json"}}},
+        ],
+        "items": [{"$ref": "https://example.com/c.json"}],
+        "$defs": {"A": {"type": "string"}},
+    }
+    assert sorted(find_external_refs(schema)) == [
+        "https://example.com/b.json",
+        "https://example.com/c.json",
+    ]
+
+
+def test_non_string_ref_is_ignored():
+    schema = {"$ref": {"not": "a string"}, "properties": {"x": {"$ref": 123}}}
+    assert find_external_refs(schema) == []
+
+
+def test_scalar_and_empty_inputs():
+    assert find_external_refs(None) == []
+    assert find_external_refs("just a string") == []
+    assert find_external_refs(42) == []
+    assert find_external_refs({}) == []
+    assert find_external_refs([]) == []