Propagate x-fastmcp-wrap-result in tool result _meta by jlowin · Pull Request #3490 · PrefectHQ/fastmcp

jlowin · 2026-03-14T13:05:29Z

When FastMCP wraps non-object tool results in a {"result": ...} envelope for structuredContent, consumers like the Prefab renderer need to know whether to unwrap it. Currently this is only discoverable via the tool's outputSchema, which requires a listTools call and isn't available in all contexts (e.g., tool calls initiated from within a UI). This change propagates the x-fastmcp-wrap-result flag directly on each tool result's _meta, making it self-describing. The client-side parser now checks _meta first before falling back to the schema lookup.

@server.tool
def get_items() -> list[dict]:
    return [{"id": 1}, {"id": 2}]

result = await server.call_tool("get_items", {})
result.meta  # {"x-fastmcp-wrap-result": True}
result.structured_content  # {"result": [{"id": 1}, {"id": 2}]}

🤖 Generated with Claude Code Co-authored-by: Claude <[email protected]>

…allToolResult import, extract fastmcp_meta 🤖 Generated with Claude Code Co-authored-by: Claude <[email protected]>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 71f3b7567f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-14T13:17:56Z

+            if wrap_from_meta:
+                # The result is self-describing — unwrap directly without
+                # a listTools round-trip or schema lookup.
+                data = result.structuredContent.get("result")


Preserve schema-based decoding for wrapped tool results

When _meta.fastmcp.wrap_result is true (now emitted for wrapped FastMCP tool outputs), this branch returns result.structuredContent["result"] directly and bypasses the existing schema/type-adapter validation path. That changes result.data from validated Python types to raw JSON shapes for wrapped schemas (for example, set[int] now comes back as list[int], and AnyUrl as str), which is a behavioral regression for client.call_tool() consumers that rely on typed decoding.

Useful? React with 👍 / 👎.

🤖 Generated with Claude Code

marvin-context-protocol · 2026-03-14T13:26:22Z

Test Failure Analysis

(Updated — analysis confirmed by latest run 23088861015)

Summary: 2 tests in tests/server/tasks/test_task_return_types.py fail because the new wrap_from_meta fast-path in _parse_call_tool_result skips the schema-based type coercion that pydantic was previously performing.

Root Cause: In src/fastmcp/client/mixins/tools.py, the new code takes a fast path when meta.fastmcp.wrap_result is True:

if wrap_from_meta:
    data = result.structuredContent.get("result")  # raw JSON value, no coercion
else:
    # ... schema lookup + pydantic validate_python(structured_content)

This skips the listTools round-trip (intentional), but also inadvertently skips type_adapter.validate_python(...). For types that don't round-trip cleanly through JSON, this means:

datetime → serialized as ISO string "2025-11-05T12:30:45", never coerced back to datetime
set[int] → serialized as JSON array [1, 2, 3], never coerced back to set

Suggested Solution: In src/fastmcp/client/mixins/tools.py, decouple the two behaviors the fast-path was trying to combine: skip listTools and parse using schema. The schema lookup should still run (and its result used for coercion) even when wrap_from_meta is True. Only the listTools call should be skipped:

# Skip listTools only if meta already tells us it's wrapped
if not wrap_from_meta and name not in tool_output_schemas:
    await list_tools_fn()

if name in tool_output_schemas:
    output_schema = tool_output_schemas.get(name)
    if output_schema:
        if output_schema.get("x-fastmcp-wrap-result") or wrap_from_meta:
            output_schema = output_schema.get("properties", {}).get("result")
            structured_content = result.structuredContent.get("result")
        else:
            structured_content = result.structuredContent
        output_type = json_schema_to_type(output_schema)
        type_adapter = get_cached_typeadapter(output_type)
        data = type_adapter.validate_python(structured_content)
    else:
        data = result.structuredContent
elif wrap_from_meta:
    # Schema unavailable but we know it's wrapped — unwrap without coercion
    data = result.structuredContent.get("result")

This preserves the optimization (no listTools call when wrap_result is in meta) while keeping type coercion via pydantic for types like datetime and set.

Detailed Analysis

Failing tests:

tests/server/tasks/test_task_return_types.py::test_task_binary_types[return_datetime-datetime-<lambda>]
tests/server/tasks/test_task_return_types.py::test_task_collection_types[return_set-set-expected_value1]

Failure 1 — datetime:

E  assert False
E   +  where False = isinstance('2025-11-05T12:30:45', <class 'datetime.datetime'>)
E   +    where '2025-11-05T12:30:45' = ...CallToolResult(..., meta={'fastmcp': {'wrap_result': True}}, data='2025-11-05T12:30:45', ...).data

datetime is serialized to an ISO string in JSON. Without type_adapter.validate_python(...), it stays a string instead of being parsed back to a datetime.

Failure 2 — set:

E  AssertionError: assert False
E   +  where False = isinstance([1, 2, 3], <class 'set'>)
E   +    where [1, 2, 3] = ...CallToolResult(..., meta={'fastmcp': {'wrap_result': True}}, data=[1, 2, 3], ...).data

set serializes to a JSON array. Without schema-guided coercion, [1, 2, 3] stays a list instead of being converted to a set.

Both failures are in the task code path (client.call_tool(tool_name, task=True)), where results flow through _parse_call_tool_result after task completion. The task result meta includes {'fastmcp': {'wrap_result': True}}, which triggers the new fast-path.

Related Files

src/fastmcp/client/mixins/tools.py — _parse_call_tool_result function, the new wrap_from_meta fast-path is the source of the regression
tests/server/tasks/test_task_return_types.py:281 — test_task_binary_types (datetime case)
tests/server/tasks/test_task_return_types.py:332 — test_task_collection_types (set case)

🤖 Generated with Claude Code (edited — reflects latest run analysis)

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 969aafbd3c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-14T13:31:09Z

+            fastmcp_meta = (result.meta or {}).get("fastmcp") or {}
+            wrap_from_meta = fastmcp_meta.get("wrap_result", False)


Guard fastmcp meta parsing against non-dict values

_meta is free-form, but this path assumes result.meta["fastmcp"] is always a dict and immediately calls .get() on it. If a server (or a tool returning ToolResult(meta=...)) sends "fastmcp" as a non-object value, this raises, gets swallowed by the broad except, and leaves result.data unset even when schema-based decoding would have succeeded. This makes client parsing fragile for mixed/third-party MCP servers and malformed-but-recoverable metadata.

Useful? React with 👍 / 👎.

🤖 Generated with Claude Code

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 22b7bbe791

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-14T14:48:21Z

+            fastmcp_meta = (
+                raw_fastmcp_meta if isinstance(raw_fastmcp_meta, dict) else {}
+            )
+            wrap_from_meta = fastmcp_meta.get("wrap_result", False)


Require boolean wrap_result before unwrapping content

wrap_from_meta = fastmcp_meta.get("wrap_result", False) treats any truthy value (for example the string "false" or integer 1) as a signal to unwrap structuredContent["result"]. In that case the client will incorrectly unwrap valid object payloads and can fall into the exception path, leaving result.data unset even when schema-based decoding would otherwise succeed. This is a regression in mixed/third-party environments because _meta is free-form and not type-enforced for nested values.

Useful? React with 👍 / 👎.

Propagate x-fastmcp-wrap-result flag in tool result _meta

bc87aeb

🤖 Generated with Claude Code Co-authored-by: Claude <[email protected]>

marvin-context-protocol Bot added enhancement Improvement to existing functionality. For issues and smaller PR improvements. server Related to FastMCP server implementation or server-side functionality. client Related to the FastMCP client SDK or client-side functionality. labels Mar 14, 2026

jlowin and others added 2 commits March 14, 2026 09:08

Skip listTools round-trip when _meta has x-fastmcp-wrap-result

3f859be

🤖 Generated with Claude Code Co-authored-by: Claude <[email protected]>

Use namespaced meta key: {"fastmcp": {"wrap_result": true}}

f26ff73

🤖 Generated with Claude Code Co-authored-by: Claude <[email protected]>

This comment was marked as resolved.

Sign in to view

Clean up _parse_call_tool_result: hoist cast import, document local C…

71f3b75

…allToolResult import, extract fastmcp_meta 🤖 Generated with Claude Code Co-authored-by: Claude <[email protected]>

chatgpt-codex-connector Bot reviewed Mar 14, 2026

View reviewed changes

jlowin added 2 commits March 14, 2026 09:21

Merge _meta in tasks result handler instead of overwriting

078f05f

🤖 Generated with Claude Code

Preserve type validation in meta-based unwrap path

969aafb

🤖 Generated with Claude Code

chatgpt-codex-connector Bot reviewed Mar 14, 2026

View reviewed changes

Fix type validation for wrapped task results, guard non-dict meta

22b7bbe

🤖 Generated with Claude Code

chatgpt-codex-connector Bot reviewed Mar 14, 2026

View reviewed changes

jlowin merged commit 139d2d8 into main Mar 14, 2026
6 of 9 checks passed

jlowin deleted the fix/wrap-result-meta branch March 14, 2026 15:09

jlowin mentioned this pull request Mar 14, 2026

Unwrap FastMCP result envelope via _meta PrefectHQ/prefab#263

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Propagate x-fastmcp-wrap-result in tool result _meta#3490

Propagate x-fastmcp-wrap-result in tool result _meta#3490
jlowin merged 7 commits intomainfrom
fix/wrap-result-meta

jlowin commented Mar 14, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Mar 14, 2026

Uh oh!

marvin-context-protocol Bot commented Mar 14, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Mar 14, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Mar 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		fastmcp_meta = (result.meta or {}).get("fastmcp") or {}
		wrap_from_meta = fastmcp_meta.get("wrap_result", False)

Conversation

jlowin commented Mar 14, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

marvin-context-protocol Bot commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Failure Analysis

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

marvin-context-protocol Bot commented Mar 14, 2026 •

edited

Loading