mcp: propertly validate against JSON, independent of Go values

Our validation logic was avoiding double-unmarshalling as much as
possible, by parsing before validation and validating the Go type.

This only works if the Go type has the same structure as its JSON
representation, which may not be the case in the presence of types with
custom MarshalJSON or UnmarshalJSON methods (such as time.Time).

But even if the Go type doesn't use any custom marshalling, validation
is broken, because we can't differentiate zero values from missing
values.

Bite the bullet and use double-unmarshalling for both input and output
schemas. Coincidentally, this fixes three bugs:
- We were accepting case-insensitive JSON keys, since we parsed first,
  even though they should have been rejected. A number of tests were
  wrong.
- Defaults were overriding present-yet-zero values, as noted in an
  incorrect test case.
- When "arguments" was missing, validation wasn't performed, no defaults
  were applied, and unmarshalling failed even if all properties were
  optional.

First unmarshalling to map[string]any allows us to fix all these bugs.
Unfortunately, it means a 3x increase in the number of reflection
operations (we need to unmarshal, apply defaults and validate,
re-marshal with the defaults, and then unmarshal into the Go type).
However, this is not likely to be a significant overhead, and we can
always optimize in the future.

Update github.com/google/jsonschema-go to pick up necessary improvements
supporting this change.

Additionally, fix the error codes for invalid tool parameters, to be
consistent with other SDKs (Invalid Params: -32602).

Fixes #447
Fixes #449
Updates #450

Author: findleyr

go.mod

@@ -4,7 +4,7 @@ go 1.23.0
 
 require (
 	github.com/google/go-cmp v0.7.0
-	github.com/google/jsonschema-go v0.2.2
+	github.com/google/jsonschema-go v0.2.3-0.20250911201137-bbdc431016d2
 	github.com/yosida95/uritemplate/v3 v3.0.2
 	golang.org/x/tools v0.34.0
 )

go.sum

@@ -1,7 +1,7 @@
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
-github.com/google/jsonschema-go v0.2.2 h1:qb9KM/pATIqIPuE9gEDwPsco8HHCTlA88IGFYHDl03A=
-github.com/google/jsonschema-go v0.2.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/google/jsonschema-go v0.2.3-0.20250911201137-bbdc431016d2 h1:IIj7X4SH1HKy0WfPR4nNEj4dhIJWGdXM5YoBAbfpdoo=
+github.com/google/jsonschema-go v0.2.3-0.20250911201137-bbdc431016d2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo=

mcp/conformance_test.go

@@ -20,9 +20,11 @@ import (
 	"strings"
 	"testing"
 	"testing/synctest"
+	"time"
 
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
+	"github.com/google/jsonschema-go/jsonschema"
 	"github.com/modelcontextprotocol/go-sdk/internal/jsonrpc2"
 	"github.com/modelcontextprotocol/go-sdk/jsonrpc"
 	"golang.org/x/tools/txtar"
@@ -97,16 +99,40 @@ func TestServerConformance(t *testing.T) {
 	}
 }
 
-type input struct {
+type structuredInput struct {
 	In string `jsonschema:"the input"`
 }
 
-type output struct {
+type structuredOutput struct {
 	Out string `jsonschema:"the output"`
 }
 
-func structuredTool(ctx context.Context, req *CallToolRequest, args *input) (*CallToolResult, *output, error) {
-	return nil, &output{"Ack " + args.In}, nil
+func structuredTool(ctx context.Context, req *CallToolRequest, args *structuredInput) (*CallToolResult, *structuredOutput, error) {
+	return nil, &structuredOutput{"Ack " + args.In}, nil
+}
+
+type tomorrowInput struct {
+	Now time.Time
+}
+
+type tomorrowOutput struct {
+	Tomorrow time.Time
+}
+
+func tomorrowTool(ctx context.Context, req *CallToolRequest, args tomorrowInput) (*CallToolResult, tomorrowOutput, error) {
+	return nil, tomorrowOutput{args.Now.Add(24 * time.Hour)}, nil
+}
+
+type incInput struct {
+	X int `json:"x,omitempty"`
+}
+
+type incOutput struct {
+	Y int `json:"y"`
+}
+
+func incTool(_ context.Context, _ *CallToolRequest, args incInput) (*CallToolResult, incOutput, error) {
+	return nil, incOutput{args.X + 1}, nil
 }
 
 // runServerTest runs the server conformance test.
@@ -124,6 +150,15 @@ func runServerTest(t *testing.T, test *conformanceTest) {
 			}, sayHi)
 		case "structured":
 			AddTool(s, &Tool{Name: "structured"}, structuredTool)
+		case "tomorrow":
+			AddTool(s, &Tool{Name: "tomorrow"}, tomorrowTool)
+		case "inc":
+			inSchema, err := jsonschema.For[incInput](nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+			inSchema.Properties["x"].Default = json.RawMessage(`6`)
+			AddTool(s, &Tool{Name: "inc", InputSchema: inSchema}, incTool)
 		default:
 			t.Fatalf("unknown tool %q", tn)
 		}

mcp/mcp_test.go

@@ -224,7 +224,7 @@ func TestEndToEnd(t *testing.T) {
 		// ListTools is tested in client_list_test.go.
 		gotHi, err := cs.CallTool(ctx, &CallToolParams{
 			Name:      "greet",
-			Arguments: map[string]any{"name": "user"},
+			Arguments: map[string]any{"Name": "user"},
 		})
 		if err != nil {
 			t.Fatal(err)
@@ -648,7 +648,7 @@ func TestServerClosing(t *testing.T) {
 	}()
 	if _, err := cs.CallTool(ctx, &CallToolParams{
 		Name:      "greet",
-		Arguments: map[string]any{"name": "user"},
+		Arguments: map[string]any{"Name": "user"},
 	}); err != nil {
 		t.Fatalf("after connecting: %v", err)
 	}
@@ -1646,7 +1646,7 @@ var testImpl = &Implementation{Name: "test", Version: "v1.0.0"}
 // If anyone asks, we can add an option that controls how pointers are treated.
 func TestPointerArgEquivalence(t *testing.T) {
 	type input struct {
-		In string
+		In string `json:",omitempty"`
 	}
 	type output struct {
 		Out string

mcp/protocol.go

@@ -105,6 +105,13 @@ type CallToolResult struct {
 	IsError bool `json:"isError,omitempty"`
 }
 
+// TODO(#64): consider exposing setError (and getError), by adding an error
+// field on CallToolResult.
+func (r *CallToolResult) setError(err error) {
+	r.Content = []Content{&TextContent{Text: err.Error()}}
+	r.IsError = true
+}
+
 func (*CallToolResult) isResult() {}
 
 // UnmarshalJSON handles the unmarshalling of content into the Content

mcp/server.go

@@ -221,11 +221,23 @@ func toolForErr[In, Out any](t *Tool, h ToolHandlerFor[In, Out]) (*Tool, ToolHan
 	}
 
 	th := func(ctx context.Context, req *CallToolRequest) (*CallToolResult, error) {
+		var input json.RawMessage
+		if req.Params.Arguments != nil {
+			input = req.Params.Arguments
+		}
+		// Validate input and apply defaults.
+		var err error
+		input, err = applySchema(input, inputResolved)
+		if err != nil {
+			// TODO(#450): should this be considered a tool error? (and similar below)
+			return nil, fmt.Errorf("%w: validating \"arguments\": %v", jsonrpc2.ErrInvalidParams, err)
+		}
+
 		// Unmarshal and validate args.
 		var in In
-		if req.Params.Arguments != nil {
-			if err := unmarshalSchema(req.Params.Arguments, inputResolved, &in); err != nil {
-				return nil, err
+		if input != nil {
+			if err := json.Unmarshal(input, &in); err != nil {
+				return nil, fmt.Errorf("%w: %v", jsonrpc2.ErrInvalidParams, err)
 			}
 		}
 
@@ -241,22 +253,15 @@ func toolForErr[In, Out any](t *Tool, h ToolHandlerFor[In, Out]) (*Tool, ToolHan
 				return nil, wireErr
 			}
 			// For regular errors, embed them in the tool result as per MCP spec
-			return &CallToolResult{
-				Content: []Content{&TextContent{Text: err.Error()}},
-				IsError: true,
-			}, nil
-		}
-
-		// Validate output schema, if any.
-		// Skip if out is nil: we've removed "null" from the output schema, so nil won't validate.
-		if v := reflect.ValueOf(out); v.Kind() == reflect.Pointer && v.IsNil() {
-		} else if err := validateSchema(outputResolved, &out); err != nil {
-			return nil, fmt.Errorf("tool output: %w", err)
+			var errRes CallToolResult
+			errRes.setError(err)
+			return &errRes, nil
 		}
 
 		if res == nil {
 			res = &CallToolResult{}
 		}
+
 		// Marshal the output and put the RawMessage in the StructuredContent field.
 		var outval any = out
 		if elemZero != nil {
@@ -272,7 +277,16 @@ func toolForErr[In, Out any](t *Tool, h ToolHandlerFor[In, Out]) (*Tool, ToolHan
 			if err != nil {
 				return nil, fmt.Errorf("marshaling output: %w", err)
 			}
-			res.StructuredContent = json.RawMessage(outbytes) // avoid a second marshal over the wire
+			outJSON := json.RawMessage(outbytes)
+			// Validate the output JSON, and apply defaults.
+			//
+			// We validate against the JSON, rather than the output value, as
+			// some types may have custom JSON marshalling (issue #447).
+			outJSON, err = applySchema(outJSON, outputResolved)
+			if err != nil {
+				return nil, fmt.Errorf("validating tool output: %w", err)
+			}
+			res.StructuredContent = outJSON // avoid a second marshal over the wire
 
 			// If the Content field isn't being used, return the serialized JSON in a
 			// TextContent block, as the spec suggests:

mcp/server_test.go

@@ -514,7 +514,7 @@ func testToolForSchema[In, Out any](t *testing.T, tool *Tool, in string, out Out
 	_, err = goth(context.Background(), ctr)
 
 	if gotErr := err != nil; gotErr != wantErr {
-		t.Errorf("got error: %t, want error: %t", gotErr, wantErr)
+		t.Errorf("got error %v, want error: %t", err, wantErr)
 	}
 }
 

mcp/sse_example_test.go

@@ -15,7 +15,8 @@ import (
 )
 
 type AddParams struct {
-	X, Y int
+	X int `json:"x"`
+	Y int `json:"y"`
 }
 
 func Add(ctx context.Context, req *mcp.CallToolRequest, args AddParams) (*mcp.CallToolResult, any, error) {

mcp/streamable_test.go

@@ -144,7 +144,7 @@ func TestStreamableTransports(t *testing.T) {
 			// The "greet" tool should just work.
 			params := &CallToolParams{
 				Name:      "greet",
-				Arguments: map[string]any{"name": "foo"},
+				Arguments: map[string]any{"Name": "foo"},
 			}
 			got, err := session.CallTool(ctx, params)
 			if err != nil {
@@ -239,10 +239,11 @@ func TestStreamableServerShutdown(t *testing.T) {
 			if err != nil {
 				t.Fatal(err)
 			}
+			defer clientSession.Close()
 
 			params := &CallToolParams{
 				Name:      "greet",
-				Arguments: map[string]any{"name": "foo"},
+				Arguments: map[string]any{"Name": "foo"},
 			}
 			// Verify that we can call a tool.
 			if _, err := clientSession.CallTool(ctx, params); err != nil {