Error Invoking MCP Tools with Optional Parameters

[lkingland]

Summary

Cursor Desktop's MCP Client yields an error when attempting to invoke an MCP server tool with optional parameters. Example error message:

Parameter 'optionalStr' must be of type null,string, got string

Reproduction

1. Clone Test MCP Server: git clone https://github.com/lkingland/cursor-mcp-test
2. Build: cd cursor-mcp-test && go build
3. Configure Cursor MCP settings (~/.cursor/mcp.json):

   {
     "mcpServers": {
       "cursor-mcp-test": {
         "command": "/absolute/path/to/cursor-mcp-test"
       }
     }
   }
   

4. Restart Cursor
5. Ask Cursor to invoke "Example Tool" with:

   {
     "requiredParam": "test-value",
     "optionalStr": "optional-value"
   }
   

Analysis

A log of communication with the server is written to /tmp/cursor-mcp-test.log which shows the tool invocation never exits the client. This is therefore happening client-side in the MCP Client and is likely a problem of not supporting union set validation of the tool's schema.

The test server uses the following to define an input:

type MyToolInput struct {
    RequiredParam string  `json:"requiredParam" jsonschema:"required,A required string parameter"`
    OptionalStr   *string `json:"optionalStr,omitempty" jsonschema:"An optional string parameter"`
}

Which generates the tool schema:

{
  "type": "object",
  "required": ["requiredParam"],
  "properties": {
    "requiredParam": {
      "type": "string",
      "description": "A required string parameter"
    },
    "optionalStr": {
      "type": ["null", "string"],
      "description": "An optional string parameter"
    }
  },
  "additionalProperties": false
}

The pattern "type": ["null", "string"] is the standard way to represent optional/nullable fields:

• Go MCP servers: pointer types (*string, *int, *bool) generate union types
• Python MCP servers: Optional[str] generates union types
• TypeScript MCP servers: string | null generates union types

Specification References

According to the MCP specification (2025-06-18):

A Tool's inputSchema is "A JSON Schema object defining the expected parameters for the tool"

The MCP specification requires inputSchema to be a valid JSON Schema object. JSON Schema explicitly supports union types via array notation for the type field (e.g., "type": ["null", "string"]), which is the standard pattern for optional/nullable parameters.

Per JSON Schema specification, a value validates successfully if it matches any of the types in a union array.

Verification

The same parameters work correctly with other MCP clients. Unit tests using the official Go MCP SDK all pass:

$  go test -v ./pkg
=== RUN   TestMyTool
=== RUN   TestMyTool/with_optional_string
=== RUN   TestMyTool/without_optional_string
=== RUN   TestMyTool/with_explicit_null
=== RUN   TestMyTool/missing_required_param
=== RUN   TestMyTool/wrong_type_for_optional
--- PASS: TestMyTool (0.00s)
    --- PASS: TestMyTool/with_optional_string (0.00s)
    --- PASS: TestMyTool/without_optional_string (0.00s)
    --- PASS: TestMyTool/with_explicit_null (0.00s)
    --- PASS: TestMyTool/missing_required_param (0.00s)
    --- PASS: TestMyTool/wrong_type_for_optional (0.00s)
=== RUN   TestListTools
    server_test.go:128: optionalStr type: [null string]
--- PASS: TestListTools (0.00s)
PASS
ok      cursor-mcp-test/pkg     (cached)

References

• MCP Specification 2025-06-18
• JSON Schema Specification - Type
• MCP Go SDK
• Test Case Repository

Environment

• Cursor Version: 2.0.75
• VSCode Version: 1.99.3
• Commit: 9e7a27b76730ca7fe4aecaeafc58bac1e2c82120
• Date: 2025-11-12T17:34:21.472Z
• Platform: Darwin arm64 25.0.0
• MCP SDK: github.com/modelcontextprotocol/go-sdk v1.1.0

Related

Issues

#3614 #3540 #2932

Forum Topics

https://forum.cursor.com/t/error-invoking-mcp-tools-with-optional-parameters/142477

https://forum.cursor.com/t/cursor-cannot-handle-mcp-server-params/52657/2

https://forum.cursor.com/t/mcp-server-tool-calls-fail-with-invalid-type-for-parameter-in-tool/70831