Add ValidationOptions for lenient output schema validation by lorenss-m · Pull Request #1260 · modelcontextprotocol/python-sdk

lorenss-m · 2025-08-10T21:22:01Z

Motivation and Context

Currently, MCP clients raise RuntimeError when tools don't return structured content matching their outputSchema. This breaks integrations with servers that have schema/implementation mismatches.

This PR adds optional lenient validation that converts these errors to warnings, allowing clients to continue operating with imperfect servers.

How Has This Been Tested?

Added test suite in tests/client/test_validation_options.py
All existing tests pass
Tested with real MCP servers exhibiting validation issues

Breaking Changes

None. Default behavior unchanged. Lenient validation is opt-in:

from mcp.client.session import ValidationOptions

# Opt-in to lenient validation
options = ValidationOptions(strict_output_validation=False)
session = ClientSession(read, write, validation_options=options)

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

Added ValidationOptions class following existing patterns (e.g., TransportSecuritySettings)
Modified ClientSession.call_tool() to check options before raising validation errors
Fixed workspace config issue with structured_output_lowlevel.py by creating proper package structure

ochafik

Hi @lorenss-m, thanks for sending this!

Seems reasonable to add this option given the spec only says clients "should" validate structured results against the output schema.

I'm curious tho, which examples of non-conforming outputs did you find / how bad were they?

cc/ @bhosmer-ant since authored initial support in #993

ochafik · 2025-08-19T15:07:00Z

src/mcp/client/session.py

What error would None produce here, do we need the two branches?

src/mcp/client/session.py

Kludex · 2025-08-20T07:45:48Z

src/mcp/client/session.py

Let's not introduce parameters that are BaseModel's please. The best experience is usually to have flat parameters.

…boolean parameter

lorenss-m · 2025-08-26T09:10:45Z

Added the validate_structured_outputs suggestion!

dsp-ant · 2025-09-01T13:05:28Z

We should make sure that this matches how other SDKs behave before we merge this. @modelcontextprotocol/sdk-maintainers .

jba · 2025-09-01T13:19:56Z

In the Go SDK, currently all schema validation is done on the server side.

mikekistler · 2025-09-01T15:00:30Z

The C# SDK delegates the validation of the structured content to the MCP Host. This is mainly because there is no standard, built-in JSON Schema validator in .NET, so doing this in the client would require pulling in an external package, one of potentially several, which adds bulk to the SDK and usurps the MCP Host's choce of validation package.

lorenss-m · 2025-09-19T08:06:55Z

Anything else we should change here? Would love to get this rolled out, our library is forced to depend on our fork otherwise!

felixweinberger

Looks like there isn't necessarily a single approach across SDKs. Go does server-side validation, C# delegates it to the host, with neither currently doing any validation within the client.

This PR allows optionally disabling client side validation specifically in Python, which thus seems like it would enable behaviors like in Go & C# at least (no client side validation).

Also matches the spec as pointed out by @ochafik above, so this seems OK to me to merge.

However, left some comments - especially the change to auth seems unintentional.

felixweinberger · 2025-09-23T13:12:58Z

src/mcp/server/auth/provider.py

 def construct_redirect_uri(redirect_uri_base: str, **params: str | None) -> str:
    parsed_uri = urlparse(redirect_uri_base)
-    query_params = [(k, v) for k, vs in parse_qs(parsed_uri.query) for v in vs]
+    query_params = [(k, v) for k, vs in parse_qs(parsed_uri.query).items() for v in vs]


intentional? seems unrelated

felixweinberger · 2025-09-23T13:29:00Z

src/mcp/client/session.py

+                            f"Invalid structured content returned by tool {name}: {e}. Continuing without validation."
+                        )
+                except SchemaError as e:
+                    # Schema errors are always raised - they indicate a problem with the schema itself


nit: remove redundant comment

felixweinberger · 2025-09-23T13:32:53Z

src/mcp/client/session.py

        if output_schema is not None:
            if result.structuredContent is None:
-                raise RuntimeError(f"Tool {name} has an output schema but did not return structured content")
-            try:
-                validate(result.structuredContent, output_schema)
-            except ValidationError as e:
-                raise RuntimeError(f"Invalid structured content returned by tool {name}: {e}")
-            except SchemaError as e:
-                raise RuntimeError(f"Invalid schema for tool {name}: {e}")
+                if self._validate_structured_outputs:


nit: getting quite heavily nested here, could at least partially simplify with

if output_schema is None: return if result.structuredContent is None: # raise / log depending # handle the base case of try / except with raise / log depending

felixweinberger · 2025-10-13T15:30:16Z

Hi @lorenss-m are you planning to come back to this one?

felixweinberger · 2025-10-23T22:54:27Z

Closing this for now due to inactivity.

lorenss-m requested review from a team and dsp-ant August 10, 2025 21:22

lorenss-m force-pushed the pr/validation-options branch 5 times, most recently from 26c6806 to 7722e38 Compare August 10, 2025 22:05

ochafik reviewed Aug 19, 2025

View reviewed changes

Kludex reviewed Aug 20, 2025

View reviewed changes

lorenss-m closed this Aug 26, 2025

lorenss-m force-pushed the pr/validation-options branch from 82db20c to 9a8592e Compare August 26, 2025 08:50

refactor: replace ValidationOptions with validate_structured_outputs …

c7c37d8

…boolean parameter

lorenss-m reopened this Aug 26, 2025

fix: apply ruff formatting

889c94e

lorenss-m requested review from a team and pcarleton August 26, 2025 08:57

fix: add type annotations for pyright

9740a7c

dsp-ant requested review from Kludex and ochafik September 1, 2025 12:34

felixweinberger requested changes Sep 23, 2025

View reviewed changes

felixweinberger added needs more work Not ready to be merged yet, needs additional follow-up from the author(s). improves spec compliance When a change improves ability of SDK users to comply with spec definition needs more eyes labels Sep 23, 2025

felixweinberger closed this Oct 23, 2025

Conversation

lorenss-m commented Aug 10, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

ochafik Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Kludex Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

lorenss-m commented Aug 26, 2025

Uh oh!

dsp-ant commented Sep 1, 2025

Uh oh!

jba commented Sep 1, 2025

Uh oh!

mikekistler commented Sep 1, 2025

Uh oh!

lorenss-m commented Sep 19, 2025

Uh oh!

felixweinberger left a comment

Choose a reason for hiding this comment

Uh oh!

felixweinberger Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

felixweinberger Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

felixweinberger Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

felixweinberger commented Oct 13, 2025

Uh oh!

felixweinberger commented Oct 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants