ResponseLimitingMiddleware truncation breaks tools with outputSchema

[kterui9019]

What happened?

When ResponseLimitingMiddleware truncates a response from a tool that has an outputSchema (either explicitly set or auto-generated from a return type annotation), the truncated ToolResult has no structured_content. This causes the MCP SDK's output validation to fail with:
Output validation error: outputSchema defined but no structured output returned

Normal-sized responses work fine. The error only occurs when the response exceedsmax_sizeand gets truncated.

I noticed that the original PR (#3072) had a raise_on_structured option that was removed during review as unnecessary complexity. However, the current behavior silently produces an MCP protocol violation for any tool with outputSchema — which includes any tool with a return type annotation. It seems like some form of explicit handling for outputSchema-bearing tools is needed, whether that's raising, preserving structured_content, or something else.

Example Code

import asyncio
from fastmcp import Client, FastMCP
from fastmcp.server.middleware.response_limiting import ResponseLimitingMiddleware
from pydantic import BaseModel

class Answer(BaseModel):
    text: str

mcp = FastMCP()
mcp.add_middleware(ResponseLimitingMiddleware(max_size=1_000))

@mcp.tool()
def big_answer() -> Answer:
    return Answer(text="x" * 2_000)
async def demo():
    async with Client(mcp) as client:
        result = await client.call_tool("big_answer")
        print(f"OK: {result}")
asyncio.run(demo())

WARNING  Tool 'big_answer' response exceeds size limit: 4131 bytes > 1000 bytes, truncating
fastmcp.exceptions.ToolError: Output validation error: outputSchema defined but no structured output returned

Version Information

FastMCP version:  3.1.1
MCP version:      1.26.0
Python version:   3.13.11
Platform:         macOS-26.3-arm64-arm-64bit-Mach-O

[alt-efi]

We ran into this in production and shipped a monkey-patch workaround while waiting for an upstream fix. Sharing in case it helps others.

Root cause (from tracing through the code): ResponseLimitingMiddleware overrides on_call_tool and calls _truncate_to_result(text) when the response is too large. That method creates a new ToolResult with only text content — structured_content and meta are both None. The MCP SDK then sees outputSchema defined but structured_content=None and rejects with the validation error.

The reason this only surfaced with 3.2.0 is that meta was also being dropped. FastMCP 3.2.0 started setting meta={"fastmcp": {"wrap_result": True}} on ToolResults from typed tools. The SDK checks for that meta key to decide whether to skip validation — so dropping meta alongside structured_content changed the code path from "skip validation" to "validate and fail".

Workaround (monkey-patch to preserve structured_content and meta after truncation):

from fastmcp.server.middleware.response_limiting import ResponseLimitingMiddleware
from mcp.types import TextContent as MCP_TextContent
import pydantic_core

_original_truncate = ResponseLimitingMiddleware._truncate_to_result


async def _patched_on_call_tool(self, context, call_next):
    result = await call_next(context)
    if self.tools is not None and context.message.name not in self.tools:
        return result
    serialized = pydantic_core.to_json(result, fallback=str)
    if len(serialized) <= self.max_size:
        return result
    texts = [b.text for b in result.content if isinstance(b, MCP_TextContent)]
    text = "\n\n".join(texts) if texts else serialized.decode("utf-8", errors="replace")
    truncated = _original_truncate(self, text)
    # Preserve structured_content and meta so outputSchema validation passes
    truncated.structured_content = result.structured_content
    truncated.meta = result.meta
    return truncated


ResponseLimitingMiddleware.on_call_tool = _patched_on_call_tool

We put this at the top of our MCP server module (after all imports), before ResponseLimitingMiddleware is instantiated. Verified it fixes the error and that truncation still works correctly.

The minimal fix on the FastMCP side would be to carry structured_content and meta through in _truncate_to_result, or to handle the case in on_call_tool directly. Happy to submit a PR if that would be useful.