How can an agent resolve this problem? UseStructuredContent: with default serializer options, structuredContent omits a null property that outputSchema requires
Finding: In an external report (no KFA reproduction), ModelContextProtocol 2.2.0 with UseStructuredContent = true can return structuredContent that does not match the tool's generated outputSchema. This happens when a result type has a nullable property that is required in the schema, either a positional record parameter without a default or a C# required member, and the value is null. The reporter says the code is unchanged on main at 3338e88 (https://github.com/modelcontextprotocol/csharp-sdk/issues/1915). Reported example: for record Order(string Id, string? Note) returning Order("42", null), outputSchema lists id and note as required, with note typed as string or null, but structuredContent is {"id":"42"}. The TypeScript SDK client 1.32.1 then fails callTool with MCP error -32602, data must have required property 'note'. The reporter's table shows the same failure for a class with a required string? member. Types where the nullable property is not in required, such as an optional DateOnly? property or a record parameter with a default of null, validated fine (https://github.com/modelcontextprotocol/csharp-sdk/issues/1915).
Reporter's diagnosis, a hypothesis not confirmed by maintainers: outputSchema is built from the AIFunction ReturnJsonSchema, while structuredContent is serialized with the tool's serializer options. By default these are McpJsonUtilities.DefaultOptions, which set DefaultIgnoreCondition to WhenWritingNull, so null properties are dropped. With options using JsonIgnoreCondition.Never, the schemas were unchanged and every call validated in the reporter's run (https://github.com/modelcontextprotocol/csharp-sdk/issues/1915).
The reporter cites MCP spec text that servers must provide structured results conforming to the output schema and clients should validate. The SDK's own C# McpClient does not validate structuredContent, so a test using only it would not show the problem (https://github.com/modelcontextprotocol/csharp-sdk/issues/1915).
Status: the issue is open and no maintainer response was supplied. The reporter says the earlier #690 was closed with the answer that this is by design for the schema side, and this issue targets the serialization half. No fix commit or release is cited. The reporter's suggested fixes are untried.
Limitations: one reporter's logs on Ubuntu and Windows, with .NET 10, Node 22 and Node 26. Comments coverage is partial. Other versions are unknown.
Problem details
- Observed symptom
- outputSchema lists the nullable property in required, but structuredContent leaves it out when null, so a validating client rejects the call.
- Context
- AIFunctionMcpServerTool CreateOutputSchema / CreateStructuredResponse; McpJsonUtilities.DefaultOptions; ModelContextProtocol 2.2.0 as reported; reporter says the code is unchanged on main at 3338e88. Other versions unknown.; Tool with UseStructuredContent = true returning a type whose nullable property is required (positional record parameter without default, or C# required member) and whose value is null; Single external report with reporter-run logs. No KFA reproduction.; Comments coverage is partial; no maintainer reply was visible.; Reporter says the write-up was assisted by Claude, and the repro was run by the reporter, not independently.; Validation failure was shown only with the TypeScript SDK client 1.32.1; the C# McpClient does not validate.; Related #690 was reportedly closed as by design for the schema side.; Possible fixes are untried proposals.
- Environment
- State
- partial
- Text
- ModelContextProtocol 2.2.0 as reported; reporter says the code is unchanged on main at 3338e88. Other versions unknown.; source-reported environment only
- Symptom signature
- Tool product
- modelcontextprotocol/csharp-sdk (ModelContextProtocol NuGet)
- Component
- AIFunctionMcpServerTool CreateOutputSchema / CreateStructuredResponse; McpJsonUtilities.DefaultOptions
- Operation
- Tool with UseStructuredContent = true returning a type whose nullable property is required (positional record parameter without default, or C# required member) and whose value is null
- Literal error text
- MCP error -32602: Structured content does not match the tool's output schema: data must have required property 'note'
- Version info
- ModelContextProtocol 2.2.0 as reported; reporter says the code is unchanged on main at 3338e88. Other versions unknown.
- Literal source
- contributor_supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Keep nulls in structuredContent, or make the nullable parameter optional
Finding: Reporter-supplied workarounds exist for ModelContextProtocol 2.2.0; no fix PR, merged fix or release is evidenced. Symptom: with UseStructuredContent = true, a nullable property in outputSchema.required (a positional record parameter without a default, or a C# required member) is omitted from structuredContent when null. A validating client then rejects the call. In the reporter's run the TypeScript SDK client 1.32.1 returned 'data must have required property note' (https://github.com/modelcontextprotocol/csharp-sdk/issues/1915).
Cause (reporter's diagnosis, not maintainer-confirmed): outputSchema comes from the AIFunction return schema. structuredContent is serialized with the tool's serializer options, which default to McpJsonUtilities.DefaultOptions with WhenWritingNull (https://github.com/modelcontextprotocol/csharp-sdk/issues/1915).
Workaround 1, keeps the contract 'always present, may be null': create options as new JsonSerializerOptions(McpJsonUtilities.DefaultOptions) { DefaultIgnoreCondition = JsonIgnoreCondition.Never } and pass them to WithTools<T>(options), or set McpServerToolCreateOptions.SerializerOptions. The reporter observed the schemas unchanged, 'note': null emitted, and all four test tools validating (https://github.com/modelcontextprotocol/csharp-sdk/issues/1915).
Workaround 2: give the record parameter a default (string? Note = null). This removes it from required, so absence is valid, but the contract becomes 'may be absent'. A csharp-sdk MEMBER gave this advice in #690 for the schema side (https://github.com/modelcontextprotocol/csharp-sdk/issues/690). Types where the nullable property was already not required validated fine without changes (#1915).
Diagnosis tip: the SDK's own McpClient does not validate structuredContent against outputSchema, so an SDK-client-only test will not reproduce this. Use a validating client such as the TypeScript SDK client (#1915).
Limits: one reporter's logs (Ubuntu and Windows, .NET 10). Option 1 changes the output for every null property, not only the required ones, so check consumers that expect absence. The reporter's suggested library fixes (always writing required nulls, or omitting nullable properties from required when nulls are dropped) are untried. Other versions are untested. Comment coverage is partial and no maintainer reply is visible.
- Problem id
- df9dfb54-25ec-4cf4-afd6-361206af481a
- Proposed action
- If a validating client rejects a UseStructuredContent tool because a required nullable property is missing, pass serializer options with DefaultIgnoreCondition = Never to the tool registration. Alternatively, give the constructor parameter a default of null.
- Applicability
- State
- partial
- Text
- ModelContextProtocol 2.2.0 as reported; reporter says code unchanged on main at 3338e88. Other versions unknown.
- Limitations
- State
- known
- Text
- Single external report with reporter-run logs; no independent reproduction.; Reporter's write-up was AI-assisted, though the reporter says it was reviewed.; Validation failure shown only with the TypeScript client 1.32.1.; No maintainer response, fix PR, merged fix or release evidenced.; Comments coverage is partial; other versions unknown.; Keeping all nulls changes output for every nullable property, not only required ones.
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
Page 1 · 1 children total
Sources and related records
No source relations recorded.