Skip to content

Generated output schema uses Pydantic's validation shape while structured output uses its serialization shape #3100

Open
Open
Generated output schema uses Pydantic's validation shape while structured output uses its serialization shape#3100
Labels
P2Moderate issues affecting some users, edge cases, potentially valuable featurebugSomething isn't workingneeds confirmationNeeds confirmation that the PR is actually required or needed.v1Affects the v1.x maintenance linev2Affects the v2 line (2.x on main)

Description

@destire-mio
destire-mio
opened on Jul 16, 2026

Initial Checks

  • I confirm that I'm using the latest version of MCP Python SDK.
  • I confirm that I searched existing issues and pull requests before opening this issue.

Description

For a Pydantic return model whose validation and serialization shapes differ, the generated outputSchema describes the validation shape while structuredContent uses the serialization shape. The SDK therefore publishes an output schema that rejects its own generated structured result.

This is related to, but not a duplicate of, #1073 / #1099. That change aligned ordinary field aliases by serializing structured output with aliases. Split validation_alias / serialization_alias values still expose different validation and serialization shapes, and serialization-only fields such as computed_field reveal the same underlying mismatch.

Example Code

from __future__ import annotations

import asyncio
import json

from jsonschema import Draft202012Validator
from pydantic import BaseModel, ConfigDict, Field, computed_field

try:
    from mcp.server.mcpserver.tools.base import Tool
except ImportError:  # MCP Python SDK 1.x
    from mcp.server.fastmcp.tools.base import Tool


class AliasOutput(BaseModel):
    model_config = ConfigDict(extra="forbid", populate_by_name=True)
    value: int = Field(validation_alias="wireIn", serialization_alias="wireOut")


def alias_output() -> AliasOutput:
    return AliasOutput(value=1)


class ComputedOutput(BaseModel):
    model_config = ConfigDict(extra="forbid")
    value: int

    @computed_field
    @property
    def doubled(self) -> int:
        return self.value * 2


def computed_output() -> ComputedOutput:
    return ComputedOutput(value=1)


async def check(function: object) -> None:
    tool = Tool.from_function(function)
    converted = await tool.run({}, None, convert_result=True)
    structured = converted[1] if isinstance(converted, tuple) else converted.structured_content
    errors = [
        error.message
        for error in Draft202012Validator(tool.output_schema).iter_errors(structured)
    ]
    print(function.__name__)
    print("schema:", json.dumps(tool.output_schema, sort_keys=True))
    print("structured:", json.dumps(structured, sort_keys=True))
    print("schema_errors:", errors)


async def main() -> None:
    await check(alias_output)
    await check(computed_output)


asyncio.run(main())

Observed validator messages:

alias_output
schema: ... "wireIn" ...
structured: {"wireOut": 1}
schema_errors: ["Additional properties are not allowed ('wireOut' was unexpected)", "'wireIn' is a required property"]

computed_output
schema: ... "value" ...
structured: {"doubled": 2, "value": 1}
schema_errors: ["Additional properties are not allowed ('doubled' was unexpected)"]

Expected behavior

The generated outputSchema should describe the serialized structured output. Generating the output model schema in Pydantic serialization mode makes both witnesses conform: the alias schema uses wireOut, and the computed-field schema includes doubled.

Python & MCP Python SDK

  • Python: 3.13.13
  • MCP Python SDK: 1.28.1 (latest stable)
  • Also reproduced on current main: 2713b53b127afc094dc97d6067df9f69b647661c (2.0.0b2)
  • Pydantic: 2.13.4

Activity

  1. Kaif10 commented on Jul 16, 2026

    @Kaif10
    Kaif10
    on Jul 16, 2026

    I'd like to work on this if you'll assign it / mark it ready for work.

    The mismatch is between how the two shapes are produced in src/mcp/server/fastmcp/utilities/func_metadata.py: outputSchema is generated with model.model_json_schema(...) (default mode="validation", so it reflects validation_alias and omits computed_fields), while the structured content is produced with validated.model_dump(mode="json", by_alias=True) (the serialization shape, using serialization_alias and including computed fields). When a model splits validation_alias/serialization_alias, or has a computed_field under extra="forbid", the published outputSchema then rejects the SDK's own structuredContent.

    Proposed fix: generate outputSchema from the serialization shape (model_json_schema(mode="serialization", ...)) so the schema and model_dump(by_alias=True) agree, including computed fields — while making sure this doesn't regress the earlier alias handling (#1073/#1099). I'd extend tests/server/fastmcp/test_func_metadata.py with cases for split validation/serialization aliases and a computed field under extra="forbid".

    This is pure-Python and I can develop/test it CPU-only. Disclosure: I'll use AI assistance in preparing the change; there's a human (me) who understands the fix and will own it through review. Let me know if you'd prefer a different approach before I start.

  2. IgorGanapolsky commented on Jul 16, 2026

    @IgorGanapolsky
    IgorGanapolsky
    on Jul 16, 2026

    This reads as a schema contract mismatch, not a model quality issue.

    When “generate schema” uses Pydantic’s validation shape but structured output uses the serialization shape, the agent/runtime can believe it has a valid schema while the actual tool/output path rejects or mis-parses fields (aliases, defaults, computed fields, exclude, etc.).

    Useful isolation before swapping models/prompts:

    1. Expected vs actual: dump both JSON Schemas side-by-side (generate vs what structured-output actually enforces) for one failing tool/output.
    2. Outside the agent: call the same structured-output path with a fixed payload — does the tool/API succeed without the agent loop?
    3. Artifact: one redacted failing run (request schema + error + response body). That usually pins “contract” vs “transport/retry/state.”

    If you can share that artifact (even redacted), the failure branch is usually obvious in one pass.

  3. maxisbey
    added
    bugSomething isn't working
    P2Moderate issues affecting some users, edge cases, potentially valuable feature
    needs confirmationNeeds confirmation that the PR is actually required or needed.
    v1Affects the v1.x maintenance line
    v2Affects the v2 line (2.x on main)
    on Aug 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Moderate issues affecting some users, edge cases, potentially valuable featurebugSomething isn't workingneeds confirmationNeeds confirmation that the PR is actually required or needed.v1Affects the v1.x maintenance linev2Affects the v2 line (2.x on main)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions