feat(router): typed custom scalars in MCP tool schemas with scalar_mappings overrides

router-tests/go.mod

@@ -31,7 +31,7 @@ require (
 	github.com/wundergraph/cosmo/router v0.0.0-20260710155145-803a4bc06d92
 	github.com/wundergraph/cosmo/router-plugin v0.0.0-20250808194725-de123ba1c65e
 	github.com/wundergraph/cosmo/speedtrap v0.0.0-00010101000000-000000000000
-	github.com/wundergraph/graphql-go-tools/v2 v2.14.1
+	github.com/wundergraph/graphql-go-tools/v2 v2.14.3-0.20260807102141-88073b801ad2
 	go.opentelemetry.io/otel v1.44.0
 	go.opentelemetry.io/otel/sdk v1.44.0
 	go.opentelemetry.io/otel/sdk/metric v1.44.0

router-tests/go.sum

@@ -386,8 +386,8 @@ github.com/wundergraph/astjson v1.1.0 h1:xORDosrZ87zQFJwNGe/HIHXqzpdHOFmqWgykCLV
 github.com/wundergraph/astjson v1.1.0/go.mod h1:h12D/dxxnedtLzsKyBLK7/Oe4TAoGpRVC9nDpDrZSWw=
 github.com/wundergraph/go-arena v1.3.0 h1:n0ng5a1vbd8YGq1u3rMr0vPU5f6AZ1BXIiUhL1UIok8=
 github.com/wundergraph/go-arena v1.3.0/go.mod h1:ROOysEHWJjLQ8FSfNxZCziagb7Qw2nXY3/vgKRh7eWw=
-github.com/wundergraph/graphql-go-tools/v2 v2.14.1 h1:TecnvTyhskoeiqo6W+1xh7HqAPL/RG5vfbFhezu7RLs=
-github.com/wundergraph/graphql-go-tools/v2 v2.14.1/go.mod h1:zREIKLmpjfNcGSubndaW/913r0Y8XbbYOXQeZFkwHdo=
+github.com/wundergraph/graphql-go-tools/v2 v2.14.3-0.20260807102141-88073b801ad2 h1:L7FceLC3ZApDOrGan5x6fh7tTophfE+rYbUSAj/B690=
+github.com/wundergraph/graphql-go-tools/v2 v2.14.3-0.20260807102141-88073b801ad2/go.mod h1:zREIKLmpjfNcGSubndaW/913r0Y8XbbYOXQeZFkwHdo=
 github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342 h1:FnBeRrxr7OU4VvAzt5X7s6266i6cSVkkFPS0TuXWbIg=
 github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342/go.mod h1:Ohn+xnUBiLI6FVj/9LpzZWtj1/D6lUovWYBkxHVV3aM=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=

router-tests/protocol/mcp_test.go

@@ -242,6 +242,72 @@ func TestMCP(t *testing.T) {
 				})
 			})
 
+			t.Run("Custom scalar variables carry a JSON Schema type in tool input schemas", func(t *testing.T) {
+				testenv.Run(t, &testenv.Config{
+					MCPOperationsPath: "testdata/mcp_operations_custom_scalar",
+					MCP: config.MCPConfiguration{
+						Enabled: true,
+					},
+				}, func(t *testing.T, xEnv *testenv.Environment) {
+
+					toolsRequest := mcp.ListToolsRequest{}
+					resp, err := xEnv.MCPClient.ListTools(xEnv.Context, toolsRequest)
+					require.NoError(t, err)
+					require.NotNil(t, resp)
+
+					var tool *mcp.Tool
+					for i := range resp.Tools {
+						if resp.Tools[i].Name == "execute_operation_upload_file" {
+							tool = &resp.Tools[i]
+							break
+						}
+					}
+					require.NotNil(t, tool, "expected the UploadFile operation to be registered as a tool")
+
+					fileSchema, ok := tool.InputSchema.Properties["file"].(map[string]any)
+					require.True(t, ok, "expected a schema object for the 'file' variable, got: %#v", tool.InputSchema.Properties)
+
+					actual, err := json.Marshal(fileSchema)
+					require.NoError(t, err)
+
+					// Custom scalars are opaque to JSON Schema, but MCP tool consumers
+					// (Anthropic directory validation, OpenAI strict mode) reject input
+					// schema properties that declare no "type". Opaque scalars must carry
+					// a best-effort primitive type: string.
+					require.Contains(t, fileSchema, "type", "custom scalar variable 'file' must declare a JSON Schema type, got: %s", actual)
+					assert.Equal(t, "string", fileSchema["type"], "custom scalar variable 'file' should be typed as a string, got: %s", actual)
+				})
+			})
+
+			t.Run("Scalar mapping overrides the string default for a mapped custom scalar", func(t *testing.T) {
+				testenv.Run(t, &testenv.Config{
+					MCPOperationsPath: "testdata/mcp_operations_custom_scalar",
+					MCP: config.MCPConfiguration{
+						Enabled:        true,
+						ScalarMappings: map[string]string{"Upload": "object"},
+					},
+				}, func(t *testing.T, xEnv *testenv.Environment) {
+					toolsRequest := mcp.ListToolsRequest{}
+					resp, err := xEnv.MCPClient.ListTools(xEnv.Context, toolsRequest)
+					require.NoError(t, err)
+
+					var tool *mcp.Tool
+					for i := range resp.Tools {
+						if resp.Tools[i].Name == "execute_operation_upload_file" {
+							tool = &resp.Tools[i]
+							break
+						}
+					}
+					require.NotNil(t, tool, "expected the UploadFile operation to be registered as a tool")
+
+					fileSchema, ok := tool.InputSchema.Properties["file"].(map[string]any)
+					require.True(t, ok, "expected a schema object for the 'file' variable")
+
+					// The mapping replaces the string default; Upload! is non-null so no null union.
+					require.Equal(t, "object", fileSchema["type"], "mapped custom scalar should carry the configured type")
+				})
+			})
+
 			t.Run("List user Operations / Static operations of type mutation aren't exposed when excludeMutations is set", func(t *testing.T) {
 				testenv.Run(t, &testenv.Config{
 					MCP: config.MCPConfiguration{

router-tests/protocol/testdata/mcp_operations_custom_scalar/UploadFile.graphql

@@ -0,0 +1,4 @@
+# This mutation uploads a single file.
+mutation UploadFile($file: Upload!) {
+  singleUpload(file: $file)
+}

router/core/router.go

@@ -1200,6 +1200,7 @@ func (r *Router) startMCPServer(ctx context.Context) error {
 		mcpserver.WithEnableArbitraryOperations(r.mcp.EnableArbitraryOperations),
 		mcpserver.WithExposeSchema(r.mcp.ExposeSchema),
 		mcpserver.WithOmitToolNamePrefix(r.mcp.OmitToolNamePrefix),
+		mcpserver.WithScalarMappings(r.mcp.ScalarMappings),
 		mcpserver.WithStateless(r.mcp.Session.Stateless),
 	}
 

router/go.mod

@@ -31,7 +31,7 @@ require (
 	github.com/tidwall/gjson v1.18.0
 	github.com/tidwall/sjson v1.2.5
 	github.com/twmb/franz-go v1.16.1
-	github.com/wundergraph/graphql-go-tools/v2 v2.14.1
+	github.com/wundergraph/graphql-go-tools/v2 v2.14.3-0.20260807102141-88073b801ad2
 	// Do not upgrade, it renames attributes we rely on
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0
 	go.opentelemetry.io/contrib/propagators/b3 v1.44.0

router/go.sum

@@ -334,8 +334,8 @@ github.com/wundergraph/astjson v1.1.0 h1:xORDosrZ87zQFJwNGe/HIHXqzpdHOFmqWgykCLV
 github.com/wundergraph/astjson v1.1.0/go.mod h1:h12D/dxxnedtLzsKyBLK7/Oe4TAoGpRVC9nDpDrZSWw=
 github.com/wundergraph/go-arena v1.3.0 h1:n0ng5a1vbd8YGq1u3rMr0vPU5f6AZ1BXIiUhL1UIok8=
 github.com/wundergraph/go-arena v1.3.0/go.mod h1:ROOysEHWJjLQ8FSfNxZCziagb7Qw2nXY3/vgKRh7eWw=
-github.com/wundergraph/graphql-go-tools/v2 v2.14.1 h1:TecnvTyhskoeiqo6W+1xh7HqAPL/RG5vfbFhezu7RLs=
-github.com/wundergraph/graphql-go-tools/v2 v2.14.1/go.mod h1:zREIKLmpjfNcGSubndaW/913r0Y8XbbYOXQeZFkwHdo=
+github.com/wundergraph/graphql-go-tools/v2 v2.14.3-0.20260807102141-88073b801ad2 h1:L7FceLC3ZApDOrGan5x6fh7tTophfE+rYbUSAj/B690=
+github.com/wundergraph/graphql-go-tools/v2 v2.14.3-0.20260807102141-88073b801ad2/go.mod h1:zREIKLmpjfNcGSubndaW/913r0Y8XbbYOXQeZFkwHdo=
 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=
 github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M=

router/pkg/config/config.go

@@ -1348,8 +1348,13 @@ type MCPConfiguration struct {
 	RouterURL                 string           `yaml:"router_url,omitempty" env:"MCP_ROUTER_URL"`
 	// OmitToolNamePrefix removes the "execute_operation_" prefix from MCP tool names.
 	// When enabled, GetUser becomes get_user. When disabled (default), GetUser becomes execute_operation_get_user.
-	OmitToolNamePrefix bool                  `yaml:"omit_tool_name_prefix" envDefault:"false" env:"MCP_OMIT_TOOL_NAME_PREFIX"`
-	OAuth              MCPOAuthConfiguration `yaml:"oauth,omitempty" envPrefix:"MCP_OAUTH_"`
+	OmitToolNamePrefix bool `yaml:"omit_tool_name_prefix" envDefault:"false" env:"MCP_OMIT_TOOL_NAME_PREFIX"`
+	// ScalarMappings overrides the JSON Schema type advertised for custom scalar
+	// variables in MCP tool input schemas, keyed by scalar type name. Unmapped
+	// custom scalars default to "string". Allowed values: string, integer,
+	// number, boolean, object, array.
+	ScalarMappings map[string]string     `yaml:"scalar_mappings,omitempty" env:"MCP_SCALAR_MAPPINGS"`
+	OAuth          MCPOAuthConfiguration `yaml:"oauth,omitempty" envPrefix:"MCP_OAUTH_"`
 	// ResourceDocumentation is a URL to a human-readable page describing this MCP resource,
 	// its access policies, and how to get started. Included in RFC 9728 Protected Resource Metadata if set.
 	ResourceDocumentation string `yaml:"resource_documentation,omitempty" env:"MCP_RESOURCE_DOCUMENTATION"`

router/pkg/config/config.schema.json

@@ -2733,6 +2733,14 @@
           "default": false,
           "description": "When enabled, MCP tool names generated from GraphQL operations omit the 'execute_operation_' prefix. For example, the GraphQL operation 'GetUser' results in a tool named 'get_user' instead of 'execute_operation_get_user'."
         },
+        "scalar_mappings": {
+          "type": "object",
+          "description": "Overrides the JSON Schema type advertised for custom scalar variables in MCP tool input schemas, keyed by scalar type name (e.g. JSON: object). Unmapped custom scalars default to string.",
+          "additionalProperties": {
+            "type": "string",
+            "enum": ["string", "integer", "number", "boolean", "object", "array"]
+          }
+        },
         "resource_documentation": {
           "type": "string",
           "description": "A URL to a human-readable page describing this MCP resource, its access policies, and how to get started. Included in the RFC 9728 Protected Resource Metadata response if set.",

router/pkg/config/fixtures/full.yaml

@@ -106,6 +106,9 @@ mcp:
   enable_arbitrary_operations: false
   exclude_mutations: false
   omit_tool_name_prefix: false
+  scalar_mappings:
+    JSON: object
+    BigInt: integer
   graph_name: cosmo
   router_url: https://cosmo-router.wundergraph.com
   server:

router/pkg/config/testdata/config_defaults.json

@@ -205,6 +205,7 @@
     "ExposeSchema": false,
     "RouterURL": "",
     "OmitToolNamePrefix": false,
+    "ScalarMappings": null,
     "OAuth": {
       "Enabled": false,
       "JWKS": null,

router/pkg/config/testdata/config_full.json

@@ -274,6 +274,10 @@
     "ExposeSchema": false,
     "RouterURL": "https://cosmo-router.wundergraph.com",
     "OmitToolNamePrefix": false,
+    "ScalarMappings": {
+      "BigInt": "integer",
+      "JSON": "object"
+    },
     "OAuth": {
       "Enabled": false,
       "JWKS": null,

router/pkg/mcpserver/operation_manager.go

@@ -9,6 +9,7 @@ import (
 	"github.com/wundergraph/cosmo/router/pkg/schemaloader"
 
 	"github.com/wundergraph/graphql-go-tools/v2/pkg/ast"
+	"github.com/wundergraph/graphql-go-tools/v2/pkg/engine/jsonschema"
 )
 
 // OperationsManager handles the loading and preparation of GraphQL operations
@@ -17,10 +18,13 @@ type OperationsManager struct {
 	operations       []schemaloader.Operation
 	logger           *zap.Logger
 	excludeMutations bool
+	// scalarSchemas overrides the JSON schema emitted for custom scalar types
+	// in generated tool input schemas, keyed by scalar type name.
+	scalarSchemas map[string]*jsonschema.JsonSchema
 }
 
 // NewOperationsManager creates a new operations manager
-func NewOperationsManager(schemaDoc *ast.Document, logger *zap.Logger, excludeMutations bool) *OperationsManager {
+func NewOperationsManager(schemaDoc *ast.Document, logger *zap.Logger, excludeMutations bool, scalarSchemas map[string]*jsonschema.JsonSchema) *OperationsManager {
 	if logger == nil {
 		logger = zap.NewNop()
 	}
@@ -29,6 +33,7 @@ func NewOperationsManager(schemaDoc *ast.Document, logger *zap.Logger, excludeMu
 		schemaDoc:        schemaDoc,
 		logger:           logger,
 		excludeMutations: excludeMutations,
+		scalarSchemas:    scalarSchemas,
 	}
 }
 
@@ -42,12 +47,17 @@ func (om *OperationsManager) LoadOperationsFromDirectory(operationsDir string) e
 	}
 
 	// Build schemas for operations
-	builder := schemaloader.NewSchemaBuilder(om.schemaDoc)
+	builder := schemaloader.NewSchemaBuilder(om.schemaDoc, schemaloader.WithScalarSchemas(om.scalarSchemas))
 	err = builder.BuildSchemasForOperations(operations)
 	if err != nil {
 		return fmt.Errorf("failed to build schemas: %w", err)
 	}
 
+	if defaulted := builder.DefaultedScalars(); len(defaulted) > 0 {
+		om.logger.Warn("custom scalars defaulted to type \"string\" in MCP tool input schemas; non-string arguments for these scalars will be rejected by input validation — add mcp.scalar_mappings entries to override",
+			zap.Strings("scalars", defaulted))
+	}
+
 	om.operations = operations
 
 	return nil

router/pkg/mcpserver/scalar_mappings.go

@@ -0,0 +1,38 @@
+package mcpserver
+
+import (
+	"fmt"
+
+	"github.com/wundergraph/graphql-go-tools/v2/pkg/engine/jsonschema"
+)
+
+// allowedScalarMappingTypes are the JSON schema type names an mcp.scalar_mappings
+// entry may map a custom scalar to.
+var allowedScalarMappingTypes = map[string]jsonschema.SchemaType{
+	"string":  jsonschema.TypeString,
+	"integer": jsonschema.TypeInteger,
+	"number":  jsonschema.TypeNumber,
+	"boolean": jsonschema.TypeBoolean,
+	"object":  jsonschema.TypeObject,
+	"array":   jsonschema.TypeArray,
+}
+
+// scalarSchemasFromMappings translates config scalar mappings (scalar name ->
+// JSON schema type name) into schema overrides.
+// YAML config is enum-checked by the config JSON schema, but env-sourced
+// config (MCP_SCALAR_MAPPINGS) bypasses schema validation entirely — this
+// runtime check is the only guard on that path.
+func scalarSchemasFromMappings(mappings map[string]string) (map[string]*jsonschema.JsonSchema, error) {
+	if len(mappings) == 0 {
+		return nil, nil
+	}
+	schemas := make(map[string]*jsonschema.JsonSchema, len(mappings))
+	for scalar, typeName := range mappings {
+		schemaType, ok := allowedScalarMappingTypes[typeName]
+		if !ok {
+			return nil, fmt.Errorf("invalid scalar mapping for scalar %q: %q is not a JSON schema type (allowed: string, integer, number, boolean, object, array)", scalar, typeName)
+		}
+		schemas[scalar] = &jsonschema.JsonSchema{Type: schemaType}
+	}
+	return schemas, nil
+}

router/pkg/mcpserver/scalar_mappings_test.go

@@ -0,0 +1,58 @@
+package mcpserver
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/wundergraph/graphql-go-tools/v2/pkg/engine/jsonschema"
+)
+
+func TestScalarMappingsTranslateToSchemas(t *testing.T) {
+	t.Run("valid mappings translate to typed schemas", func(t *testing.T) {
+		schemas, err := scalarSchemasFromMappings(map[string]string{
+			"JSON":   "object",
+			"BigInt": "integer",
+		})
+		require.NoError(t, err)
+		assert.Equal(t, map[string]*jsonschema.JsonSchema{
+			"JSON":   {Type: jsonschema.TypeObject},
+			"BigInt": {Type: jsonschema.TypeInteger},
+		}, schemas)
+	})
+
+	t.Run("unknown JSON schema type returns an error naming the scalar and the value", func(t *testing.T) {
+		schemas, err := scalarSchemasFromMappings(map[string]string{
+			"JSON": "blob",
+		})
+		require.Error(t, err)
+		assert.Nil(t, schemas)
+		assert.ErrorContains(t, err, `scalar "JSON"`)
+		assert.ErrorContains(t, err, `"blob"`)
+	})
+
+	t.Run("empty and nil mappings translate to nil", func(t *testing.T) {
+		schemas, err := scalarSchemasFromMappings(nil)
+		require.NoError(t, err)
+		assert.Nil(t, schemas)
+
+		schemas, err = scalarSchemasFromMappings(map[string]string{})
+		require.NoError(t, err)
+		assert.Nil(t, schemas)
+	})
+}
+
+func TestScalarMappingsAbortServerConstruction(t *testing.T) {
+	t.Run("invalid scalar mapping aborts server construction", func(t *testing.T) {
+		srv, err := NewGraphQLSchemaServer(
+			t.Context(),
+			"http://localhost:4000/graphql",
+			WithScalarMappings(map[string]string{"JSON": "blob"}),
+		)
+		require.Error(t, err)
+		require.Nil(t, srv)
+		require.Contains(t, err.Error(), `scalar "JSON"`)
+		require.Contains(t, err.Error(), `"blob"`)
+	})
+}