Repository navigation
Missing @JsonIgnoreProperties(ignoreUnknown = true) on capability sub-records #766
Description
Bug description
The top-level ClientCapabilities and ServerCapabilities records have @JsonIgnoreProperties(ignoreUnknown = true), but their nested sub-records do not. Since the ObjectMapper is constructed with default settings (FAIL_ON_UNKNOWN_PROPERTIES = true), any unknown field on a capability sub-object causes a deserialization failure.
This already caused a real breakage when the elicitation capability gained form and url fields (#724, fixed in #731), but the systemic issue remains — the next spec addition to any capability sub-object will break older SDK versions again.
Affected records
In McpSchema.java:
| Record | Line | Has annotation? |
|---|---|---|
ClientCapabilities |
383 | Yes |
RootCapabilities |
397 | Yes |
Sampling |
410 | No |
Elicitation |
437 | No |
Elicitation.Form |
443 | No |
Elicitation.Url |
450 | No |
ServerCapabilities |
535 | Yes |
CompletionCapabilities |
548 | No |
LoggingCapabilities |
555 | No |
PromptCapabilities |
565 | No |
ResourceCapabilities |
576 | No |
ToolCapabilities |
587 | No |
Spec reference
The spec schema explicitly states capabilities are not a closed set:
"Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities."
ClientCapabilities in schema.json — additionalProperties: false is never set on any capability object or sub-object. Several sub-capabilities (sampling, elicitation, completions, logging) explicitly set additionalProperties: true.
Expected behavior
Unknown fields on capability sub-objects should be silently ignored, matching the behavior of the top-level ClientCapabilities and ServerCapabilities records.
Related
- ToolCapabilities needs to be marked with @JsonIgnoreProperties(ignoreUnknown = true) to avoid errors. #734 — reports the same issue for
ToolCapabilitiesspecifically InitializeRequestdoesn't accept non-empty Elicitation, violating 2025-11-25 spec #724 / fix: Support form and url fields in Elicitation capability per 2025-11-25 spec #731 — the elicitation breakage that was fixed by adding fields, not by adding the annotation
Activity
DevasiaThomas commentedon Jan 29, 2026
Thank you @maxisbey for raising this. My team and I are the ones's that experienced the real breakage 🙂. Appreciate the group's attention to this. Thanks!
We got folks using all kinds of clients that are on the latest protocol spec, but some Java based MCP servers ( a few owned by us) are on older versions.
lux999 commentedon Mar 4, 2026
Thank you @maxisbey for raising this!
My team hit this exact issue after upgrading to fastmcp 2.14.5 —
ClientCapabilities.Samplingis a real blocker for us. Would love to see this land soon!Add @JsonIgnoreProperties(ignoreUnknown = true) to capability sub-rec…
Soumyadeep009 commentedon Mar 6, 2026
@maxisbey I am thinking of making the ObjectMapper not fail on unknown properties. So this would apply globally. Is this okay @chemicL @tzolov ? @rameshreddy-adutla 's fix applies annotation on each field that is affected, but is prone to failure to future fields with missed annotations.
maxisbey commentedon Mar 9, 2026
That's what we do in the Python SDK (and is also done in the Typescript SDK), we just mark all extra fields as ignored so it won't error
Disable FAIL_ON_UNKNOWN_PROPERTIES on the MCP protocol ObjectMapper
Restore DI-based MCP protocol ObjectMapper with FAIL_ON_UNKNOWN_PROPE…
Fix MCP server 500 error on unknown client capability fields (#26008)
Add a stateless server for MCP 2026-07-28