Proper handle extra data in MCP objects (#1937)

Author: Kludex

docs/migration.md

@@ -321,6 +321,30 @@ await client.read_resource(str(my_any_url))
 
 <!-- Add deprecations below -->
 
+## Bug Fixes
+
+### Extra fields no longer allowed on top-level MCP types
+
+MCP protocol types no longer accept arbitrary extra fields at the top level. This matches the MCP specification which only allows extra fields within `_meta` objects, not on the types themselves.
+
+```python
+# This will now raise a validation error
+from mcp.types import CallToolRequestParams
+
+params = CallToolRequestParams(
+    name="my_tool",
+    arguments={},
+    unknown_field="value",  # ValidationError: extra fields not permitted
+)
+
+# Extra fields are still allowed in _meta
+params = CallToolRequestParams(
+    name="my_tool",
+    arguments={},
+    _meta={"progressToken": "tok", "customField": "value"},  # OK
+)
+```
+
 ## New Features
 
 ### `streamable_http_app()` available on lowlevel Server

pyproject.toml

@@ -26,8 +26,7 @@ dependencies = [
     "anyio>=4.5",
     "httpx>=0.27.1",
     "httpx-sse>=0.4",
-    "pydantic>=2.12.0; python_version >= '3.14'",
-    "pydantic>=2.11.0; python_version < '3.14'",
+    "pydantic>=2.12.0",
     "starlette>=0.48.0; python_version >= '3.14'",
     "starlette>=0.27; python_version < '3.14'",
     "python-multipart>=0.0.9",

src/mcp/types/_types.py

@@ -30,10 +30,9 @@
 
 
 class MCPModel(BaseModel):
-    """Base class for all MCP protocol types. Allows extra fields for forward compatibility."""
+    """Base class for all MCP protocol types."""
 
-    # TODO(Marcelo): The extra="allow" should be only on specific types e.g. `Meta`, not on the base class.
-    model_config = ConfigDict(extra="allow", alias_generator=to_camel, populate_by_name=True)
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
 
 
 Meta: TypeAlias = dict[str, Any]
@@ -472,10 +471,13 @@ class GetTaskPayloadRequest(Request[GetTaskPayloadRequestParams, Literal["tasks/
 
 class GetTaskPayloadResult(Result):
     """The response to a tasks/result request.
+
     The structure matches the result type of the original request.
     For example, a tools/call task would return the CallToolResult structure.
     """
 
+    model_config = ConfigDict(extra="allow", alias_generator=to_camel, populate_by_name=True)
+
 
 class CancelTaskRequestParams(RequestParams):
     task_id: str