add output_schema override to support ChatGPT App SDK

Author: mat-octave

src/mcp/server/fastmcp/server.py

@@ -385,6 +385,7 @@ def add_tool(
         annotations: ToolAnnotations | None = None,
         icons: list[Icon] | None = None,
         meta: dict[str, Any] | None = None,
+        output_schema: dict[str, Any] | None = None,
         structured_output: bool | None = None,
     ) -> None:
         """Add a tool to the server.
@@ -398,6 +399,8 @@ def add_tool(
             title: Optional human-readable title for the tool
             description: Optional description of what the tool does
             annotations: Optional ToolAnnotations providing additional tool information
+            meta: Optional metadata dictionary
+            output_schema: Optional Pydantic model defining the output schema separate from the tool's return type
             structured_output: Controls whether the tool's output is structured or unstructured
                 - If None, auto-detects based on the function's return type annotation
                 - If True, creates a structured tool (return type annotation permitting)
@@ -411,6 +414,7 @@ def add_tool(
             annotations=annotations,
             icons=icons,
             meta=meta,
+            output_schema=output_schema,
             structured_output=structured_output,
         )
 
@@ -433,6 +437,7 @@ def tool(
         annotations: ToolAnnotations | None = None,
         icons: list[Icon] | None = None,
         meta: dict[str, Any] | None = None,
+        output_schema: dict[str, Any] | None = None,
         structured_output: bool | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a tool.
@@ -446,6 +451,8 @@ def tool(
             title: Optional human-readable title for the tool
             description: Optional description of what the tool does
             annotations: Optional ToolAnnotations providing additional tool information
+            meta: Optional metadata dictionary
+            output_schema: Optional Pydantic model defining the output schema separate from the tool's return type
             structured_output: Controls whether the tool's output is structured or unstructured
                 - If None, auto-detects based on the function's return type annotation
                 - If True, creates a structured tool (return type annotation permitting)
@@ -481,6 +488,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                 annotations=annotations,
                 icons=icons,
                 meta=meta,
+                output_schema=output_schema,
                 structured_output=structured_output,
             )
             return fn

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

@@ -35,9 +35,15 @@ class Tool(BaseModel):
     annotations: ToolAnnotations | None = Field(None, description="Optional annotations for the tool")
     icons: list[Icon] | None = Field(default=None, description="Optional list of icons for this tool")
     meta: dict[str, Any] | None = Field(default=None, description="Optional metadata for this tool")
+    output_schema_override: dict[str, Any] | None = Field(
+        default=None,
+        description="Optional Pydantic model defining the output schema separate from the tool's return type",
+    )
 
     @cached_property
     def output_schema(self) -> dict[str, Any] | None:
+        if self.output_schema_override is not None:
+            return self.output_schema_override
         return self.fn_metadata.output_schema
 
     @classmethod
@@ -51,6 +57,7 @@ def from_function(
         annotations: ToolAnnotations | None = None,
         icons: list[Icon] | None = None,
         meta: dict[str, Any] | None = None,
+        output_schema: dict[str, Any] | None = None,
         structured_output: bool | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
@@ -84,6 +91,7 @@ def from_function(
             annotations=annotations,
             icons=icons,
             meta=meta,
+            output_schema_override=output_schema,
         )
 
     async def run(
@@ -98,7 +106,7 @@ async def run(
                 self.fn,
                 self.is_async,
                 arguments,
-                {self.context_kwarg: context} if self.context_kwarg is not None else None,
+                ({self.context_kwarg: context} if self.context_kwarg is not None else None),
             )
 
             if convert_result:

src/mcp/server/fastmcp/tools/tool_manager.py

@@ -51,6 +51,7 @@ def add_tool(
         annotations: ToolAnnotations | None = None,
         icons: list[Icon] | None = None,
         meta: dict[str, Any] | None = None,
+        output_schema: dict[str, Any] | None = None,
         structured_output: bool | None = None,
     ) -> Tool:
         """Add a tool to the server."""
@@ -62,6 +63,7 @@ def add_tool(
             annotations=annotations,
             icons=icons,
             meta=meta,
+            output_schema=output_schema,
             structured_output=structured_output,
         )
         existing = self._tools.get(tool.name)

tests/server/fastmcp/test_tool_manager.py

@@ -4,7 +4,7 @@
 from typing import Any, TypedDict
 
 import pytest
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.server.fastmcp.exceptions import ToolError
@@ -577,13 +577,97 @@ def get_user() -> UserOutput:
 
         # Test that output_schema is populated
         expected_schema = {
-            "properties": {"name": {"type": "string", "title": "Name"}, "age": {"type": "integer", "title": "Age"}},
+            "properties": {
+                "name": {"type": "string", "title": "Name"},
+                "age": {"type": "integer", "title": "Age"},
+            },
             "required": ["name", "age"],
             "title": "UserOutput",
             "type": "object",
         }
         assert tool.output_schema == expected_schema
 
+    def test_add_output_schema_override(self):
+        """Test registering a tool with an explicit output schema."""
+
+        # For the ChatGPT App SDK, the tool output should be structured like:
+        # {
+        #   "structuredOutput": { ... },
+        #   "content": [ { "type": "text", "text": "..." }, ... ],
+        #   "_meta": { ... }
+        # }
+        # and the tool output schema should reflect the structure of "structuredOutput"
+        class UserOutput(BaseModel):
+            name: str
+            age: int
+
+        # Output structure expected by ChatGPT App SDK
+        class ToolOutput(BaseModel):
+            structuredOutput: UserOutput
+            content: list[dict[str, str]]
+            meta: dict[str, Any] = Field(alias="_meta")
+
+        def get_user(user_id: int) -> ToolOutput:
+            """Get user by ID."""
+            return ToolOutput(
+                structuredOutput=UserOutput(name="John", age=30),
+                content=[{"type": "text", "text": "User found"}],
+                _meta={"request_id": "12345"},
+            )
+
+        manager = ToolManager()
+        tool = manager.add_tool(get_user, output_schema=UserOutput.model_json_schema())
+
+        expected_schema = {
+            "properties": {
+                "name": {"type": "string", "title": "Name"},
+                "age": {"type": "integer", "title": "Age"},
+            },
+            "required": ["name", "age"],
+            "title": "UserOutput",
+            "type": "object",
+        }
+        assert tool.output_schema == expected_schema
+        assert tool.fn_metadata.output_model == ToolOutput
+
+    @pytest.mark.anyio
+    async def test_call_tool_with_output_schema_override(self):
+        # For the ChatGPT App SDK, the tool output should be structured like:
+        # {
+        #   "structuredOutput": { ... },
+        #   "content": [ { "type": "text", "text": "..." }, ... ],
+        #   "_meta": { ... }
+        # }
+        # and the tool output schema should reflect the structure of "structuredOutput"
+        class UserOutput(BaseModel):
+            name: str
+            age: int
+
+        # Output structure expected by ChatGPT App SDK
+        class ToolOutput(BaseModel):
+            structuredOutput: UserOutput
+            content: list[dict[str, str]]
+            meta: dict[str, Any] = Field(alias="_meta")
+
+        def get_user(user_id: int) -> ToolOutput:
+            """Get user by ID."""
+            return ToolOutput(
+                structuredOutput=UserOutput(name="John", age=30),
+                content=[{"type": "some more information about the output data"}],
+                _meta={"request_id": "12345"},
+            )
+
+        manager = ToolManager()
+        manager.add_tool(get_user, output_schema=UserOutput.model_json_schema())
+        result = await manager.call_tool("get_user", {"user_id": 1}, convert_result=True)
+
+        expected_result = {
+            "structuredOutput": {"name": "John", "age": 30},
+            "content": [{"type": "some more information about the output data"}],
+            "_meta": {"request_id": "12345"},
+        }
+        assert len(result) == 2 and result[1] == expected_result
+
     @pytest.mark.anyio
     async def test_tool_with_dict_str_any_output(self):
         """Test tool with dict[str, Any] return type."""