Error Invoking MCP Tools with Optional Parameters

Bug Reports
1

Describe the Bug

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

UPDATE: May be a duplicate of https://forum.cursor.com/t/mcp-server-tool-calls-fail-with-invalid-type-for-parameter-in-tool/70831 and https://forum.cursor.com/t/cursor-cannot-handle-mcp-server-params/52657/2, but neither of those showed when I initially searched the forums before posting. Leaving this topic open in case it has additional context.

Steps to Reproduce

  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"
}

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.

Operating System

MacOS

Current Cursor Version (Menu → About Cursor → Copy)

Version: 2.0.75
VSCode Version: 1.99.3
Commit: 9e7a27b76730ca7fe4aecaeafc58bac1e2c82120
Date: 2025-11-12T17:34:21.472Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Darwin arm64 25.0.0

Additional Information

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

GitHub Issue: Error Invoking MCP Tools with Optional Parameters · Issue #3778 · cursor/cursor · GitHub

Does this stop you from using Cursor

No - Cursor works, but with this issue

2

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.

3

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 (see tests the cursor-mcp-test repo outlined in OP)

$  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)
4

Hey, thanks for the report. This is a known issue in the Cursor MCP client when handling union types in parameter schemas.

Good news: we’ll release a fix soon for similar union type validation problems.

Your issue with the array “type”: [“null”, “string”] looks like the same root cause as the anyOf bugs. The fix should cover both cases, since both are valid representations of union types in JSON Schema.

Thanks for the links to related threads and the GitHub issue - your test server repo will help verify the fix!

5

That’s great news; thanks @deanrie

1 Like
6

Thanks @deanrie Can you share when that will be fixed?

7

I too would love to know when this fix may arrive. Thanks all.