feat: add structured output support for MCP tools #357

tzolov · 2025-06-30T12:18:43Z

Add JsonSchemaValidator interface and DefaultJsonSchemaValidator implementation
Extend Tool schema to support outputSchema field for defining expected output structure
Add structuredContent field to CallToolResult for validated structured responses
Implement automatic validation of tool outputs against their defined schemas
Add comprehensive test coverage for structured output validation scenarios
Add json-schema-validator and json-unit-assertj dependencies for validation and testing
Update McpServer builders to accept custom JsonSchemaValidator instances
Ensure backward compatibility with existing tools without output schemas

Part of #285

This PR implements compulsory server-side validation for MCP tools with output schemas, adding support for JSON schema validation of tool outputs according to the MCP specification. Tools can now define output schemas that are automatically validated on the server side, ensuring structured responses conform to expected formats before being sent to clients.
Spec Reference: https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content

Motivation and Context

The MCP specification requires that servers with tools that have output schemas must provide structured results that conform to those schemas. This change implements that mandatory server-side validation requirement by:

Enabling tools to define expected output structure via JSON schemas
Automatically validating tool responses against their defined schemas on the server side
Providing clear error messages when validation fails
Ensuring backward compatibility with existing tools

How Has This Been Tested?

Test coverage has been added across all server transport implementations:

WebFluxSseIntegrationTests.java - Added 4 new test methods for structured output validation
WebMvcSseIntegrationTests.java - Added 4 new test methods for structured output validation
HttpServletSseServerTransportProviderIntegrationTests.java - Added 4 new test methods for structured output validation
McpSchemaTests.java - Added 5 new test methods for Tool schema serialization/deserialization with output schemas

Breaking Changes

No breaking changes. This is a backward-compatible addition:

Existing tools without output schemas continue to work unchanged
New outputSchema and structuredContent fields are optional
Default JsonSchemaValidator is provided automatically for server-side validation
All existing APIs maintain their current behavior

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Implementation Details:

Added JsonSchemaValidator interface with DefaultJsonSchemaValidator implementation using json-schema-validator library
Extended Tool record with optional outputSchema field
Extended CallToolResult record with optional structuredContent field
Implemented StructuredOutputCallToolHandler wrapper that validates outputs automatically on the server side
Added comprehensive test utilities using json-unit-assertj for JSON assertions

Design Decisions:

Server-side validation is performed automatically when tools have output schemas defined
Invalid outputs are converted to error responses with descriptive messages before being sent to clients
Structured content is also serialized to text content for backward compatibility
Custom JsonSchemaValidator implementations can be provided via builder methods
Validation only occurs for tools that explicitly define output schemas
This implements the compulsory server-side validation requirement from the MCP specification

Dependencies Added:

json-schema-validator (1.5.7) for JSON schema validation on the server
json-unit-assertj for enhanced JSON testing capabilities

Scope:
This PR focuses exclusively on server-side validation as required by the MCP specification. Client-side validation is not included in this implementation.

- Add JsonSchemaValidator interface and DefaultJsonSchemaValidator implementation - Extend Tool schema to support outputSchema field for defining expected output structure - Add structuredContent field to CallToolResult for validated structured responses - Implement automatic validation of tool outputs against their defined schemas - Add comprehensive test coverage for structured output validation scenarios - Add json-schema-validator and json-unit-assertj dependencies for validation and testing - Update McpServer builders to accept custom JsonSchemaValidator instances - Ensure backward compatibility with existing tools without output schemas This implements the MCP specification requirement that tools with output schemas must provide structured results conforming to those schemas, with automatic validation and error handling for non-conforming outputs. https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content Signed-off-by: Christian Tzolov <[email protected]>

pantanurag555 · 2025-07-01T00:03:00Z

...cp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java

+					.containsEntry("operation", "2 + 3")
+					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
+			}
+			else {


Question: Didn't quite understand why this is necessary since we are hardcoding the structured content in the above result.

pantanurag555 · 2025-07-01T00:05:04Z

mcp/pom.xml

@@ -83,6 +83,15 @@
 			<artifactId>reactor-core</artifactId>
 		</dependency>

+		<!-- Json validator dependency.  


Comment doesn't seem right since this will always be a dependency for the default implementation.

yes, this comment is incorrect.
I'm conscious of adding new dependencies to the MCP core. Initially I thought we could make it optional, but that would require moving the DefaultJsonSchemaValidator to a separate module or using reflection magic. This feels like overkill for now - we can always refactor later if needed.

pantanurag555 · 2025-07-01T00:22:36Z

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

+					// }
+					// }
+					return new CallToolResult(
+							"Tool call with non-empty outputSchema must have a result with structured content", true);


Suggestion: Error message could be reworded for the client. Something like "Response missing structured content which is expected when calling tool with non-empty outputSchema"

pantanurag555 · 2025-07-01T00:24:50Z

mcp/src/main/java/io/modelcontextprotocol/server/DefaultJsonSchemaValidator.java

+
+			// Check if validation passed
+			if (!validationResult.isEmpty()) {
+				logger.warn("Validation failed: structuredContent does not match tool outputSchema. "


Suggestion: Since we already have validation failed in the error StructuredOutputCallToolHandler, maybe we can omit it in this message.

LucaButBoring · 2025-07-01T20:28:38Z

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

+					// Map<String, Object> structuredOutput = new
+					// ObjectMapper().readValue(


If we do implicitly convert here, we should reuse the ObjectMapper between operations, since ObjectMapper instances have internal caches and are fairly expensive memory-wise.

LucaButBoring · 2025-07-01T20:29:13Z

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

+					// if (!Utils.isEmpty(result.content())) {
+					// // TODO If the tesult.content() contains json text we can try to
+					// // convert it into a structured content (Experimental)
+					// var tc = result.content().stream().filter(c -> c instanceof
+					// McpSchema.TextContent).findFirst();


Ambivalent on this, I think it's surprising behavior with nontrivial overhead - IMO we should just pass through the raw result and allow consumers to migrate on their own.

I assume this is a mirror of converting structuredOutput into a TextContent block, but I think it's too expensive to justify.

agree. Thats why I commented it out but forgot to remove it.

LucaButBoring · 2025-07-01T20:33:42Z

mcp/src/main/java/io/modelcontextprotocol/server/DefaultJsonSchemaValidator.java

+				schemaNode.put("additionalProperties", false);
+			}
+
+			JsonSchema jsonSchema = JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012)


Worth peeking inside to see what this is doing, in case it's worth caching this as a field.

The topic of schema caching is important.
I will add some basic support.

LucaButBoring · 2025-07-01T20:34:47Z

mcp/src/main/java/io/modelcontextprotocol/server/DefaultJsonSchemaValidator.java

+
+	private static final Logger logger = LoggerFactory.getLogger(DefaultJsonSchemaValidator.class);
+
+	private ObjectMapper objectMapper = new ObjectMapper();


nit: assigned value here appears redundant with default constructor

…ependencies - Add schema caching to DefaultJsonSchemaValidator for better performance - Make validator fields final and improve constructor design Signed-off-by: Christian Tzolov <[email protected]>

tzolov · 2025-07-02T07:49:19Z

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

+				}
+
+				// Validate the result against the output schema
+				var validation = this.jsonSchemaValidator.validate(outputSchema, result.structuredContent());


I wonder if we need to make the sever json schema validation optional?
Would validation enabled by default have some regression impact on existing MCP server implementations?

There shouldn't be any regression since none of the existing servers will have tools with output schemas.

I can see a niche use case for making it optional, for example if you're writing an MCP server proxy and want to force the upstream server to handle validation instead.

Also think it's fine to enable by default.

tzolov · 2025-07-02T07:50:49Z

mcp/src/main/java/io/modelcontextprotocol/server/DefaultJsonSchemaValidator.java

+	}
+
+	@Override
+	public ValidationResponse validate(Map<String, Object> schema, Map<String, Object> structuredContent) {


Maybe we should extend the signature to include an unique schemaName. Then we can expose a method purgeCache(schemaName) or similar

tzolov · 2025-07-02T07:51:42Z

mcp/src/main/java/io/modelcontextprotocol/server/DefaultJsonSchemaValidator.java

+	private final JsonSchemaFactory schemaFactory;
+
+	// TODO: Implement a strategy to purge the cache (TTL, size limit, etc.)
+	private final ConcurrentHashMap<String, JsonSchema> schemaCache;


Maybe some simple, interval based purge all strategy would be good enough.

Signed-off-by: Christian Tzolov <[email protected]>

tzolov · 2025-07-02T09:11:02Z

I moved the JsonSchemaValidator classes from server to spec package. So we can reuse them for other validation cases.

LucaButBoring · 2025-07-02T18:06:02Z

mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java

+		 * @throws IllegalArgumentException if jsonSchemaValidator is null
+		 */
+		public AsyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
+			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");


nit: might be nice to add @Nullable and then use the JetBrains @Contract annotation in the Assert class to have control flow-aware null warnings in the IDE. Not urgent or required though.

tzolov added this to the 0.11.0 milestone Jun 30, 2025

tzolov mentioned this pull request Jun 30, 2025

Add OutputSchema to Tool and CallToolResult.structuredContent #285

Open

pantanurag555 reviewed Jul 1, 2025

View reviewed changes

LucaButBoring reviewed Jul 1, 2025

View reviewed changes

refactor: improve JSON schema validator with caching and reorganize d…

5458422

…ependencies - Add schema caching to DefaultJsonSchemaValidator for better performance - Make validator fields final and improve constructor design Signed-off-by: Christian Tzolov <[email protected]>

tzolov commented Jul 2, 2025

View reviewed changes

refactor: move JsonSchemaValidator classes from server to spec package

6a19900

Signed-off-by: Christian Tzolov <[email protected]>

LucaButBoring reviewed Jul 2, 2025

View reviewed changes

		// Map<String, Object> structuredOutput = new
		// ObjectMapper().readValue(


		private static final Logger logger = LoggerFactory.getLogger(DefaultJsonSchemaValidator.class);

		private ObjectMapper objectMapper = new ObjectMapper();

feat: add structured output support for MCP tools #357

Are you sure you want to change the base?

feat: add structured output support for MCP tools #357

Conversation

tzolov commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pantanurag555 Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tzolov commented Jul 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tzolov commented Jun 30, 2025 •

edited

Loading

pantanurag555 Jul 2, 2025 •

edited

Loading