[BUG] Claude Code MCP Parameter Serialization Bug

Hi @ivan-rivera-projects - thanks for reporting this

Would you also be able to provide the test-server.js? I can't seem to reproduce this myself

Hi, I installed Claude for Windows (Claude 0.12.28 (5f9bc7)) a few days back and built an MCP server using stdio. When logging out the tool call context, we can see the params are never set.

This should be pretty easy to recreate?

I've also hit this with 0.12.28 (5f9bc7), starting today. It even happens with the filesystem MCP client. From the logs:

2025-07-23T03:45:55.174Z [filesystem] [info] Message from client: {"method":"tools/call","params":{"name":"read_file"},"jsonrpc":"2.0","id":8} { metadata: undefined }

The first call after restarting the app works, subsequent ones have no arguments field in the params.

✅ Root Cause Identified + Minimal Reproduction Case

Through systematic testing, claude has identified the exact schema pattern that triggers this MCP parameter bug:

🎯 Specific Bug Trigger:

Schema pattern: {"type": ["string", "null"], "default": null} combined with required fields

Working schemas:

• ✅ All required: {"type": "string"} + "required": ["field"]
• ✅ All optional: {"type": "string", "default": "value"} + "required": []

Failing schema:

• ❌ Mixed with union type: {"type": ["string", "null"], "default": null} + required fields

🧪 Minimal Reproduction Case:

I've created a complete reproduction script: Claude Code MCP Parameter Bug Reproduction

The gist includes:

• ✅ Ready-to-run MCP server script
• ✅ Step-by-step setup instructions
• ✅ Three test cases showing working vs broken patterns
• ✅ Technical analysis of the exact trigger condition

🔍 Evidence:

MCP Protocol Logs show Claude Code sending:

// Broken case (union type + null default)
"arguments": Some({})  // Empty despite user providing parameters!

// Working case (all required)  
"arguments": Some({"field1": "value1", "field2": "value2"})

📋 Quick Reproduction:

1. Download the gist script
2. Add to .mcp.json
3. Try calling test_mixed_params(content: "hello", parent: "test")
4. Bug occurs: Gets "missing field 'content'" despite providing it

This union type + null default pattern is commonly used by MCP servers for optional parameters, making this bug affect many real-world tools.

Tested on Claude Code 1.0.69
by: Claude Code 1.0.69

@ollie-anthropic It's quite unfortunate I have to add separate MCP tool for every parameter variation currently. (can't use optional parameters)
I also can't use other MCP tools that have this kind of optional parameters.

Please investigate this 🙏

I attempted to reproduce this bug locally and it appears to be fixed in recent versions.

Reproduction Setup

With the debug MCP server from the gist, and Claude Code version 2.0.37, I tested by having Claude call the test_mixed_params tool through the MCP server. The server logs to a file showing exactly what arguments it receives.

Test 1: With both required and optional parameters

Request: Call test_mixed_params with content='test log' and parent='parent123'

Server logs:

[13:48:35] Received: tools/call
[13:48:35] Tool: test_mixed_params
[13:48:35] Arguments received: {"content": "test log", "parent": "parent123"}
[13:48:35] Arguments empty: False

Result: ✅ Success - Both parameters received correctly

Test 2: With only the required parameter

Request: Call test_mixed_params with only content='only required test'

Server logs:

[13:49:14] Received: tools/call
[13:49:14] Tool: test_mixed_params
[13:49:14] Arguments received: {"content": "only required test"}
[13:49:14] Arguments empty: False

Result: ✅ Success - Required parameter received correctly

Conclusion

The bug reported in version 1.0.69 where parameters weren't passed when using the {"type": ["string", "null"], "default": null} pattern appears to be fixed in version 2.0.37.

@tennox Can you update to the latest version and confirm if this is still an issue for you?

Confirmed! Just tested on my end with v2.0.37 and can verify the fix is working.

Caveat

this issue is marked as macos-specific - I'm on linux.

Details of my test

I created a dedicated test MCP server with the exact problematic schema pattern and tested all edge cases:

Test tool schema (the pattern that was broken):

{
  "type": ["string", "null"],
  "default": null,
  "required": ["message"]
}

Test results:

• ✅ String value: {"message":"hello world"} - received correctly
• ✅ Null value: {"message":null} - received correctly
• ✅ Default (no param): {"message":null} - received correctly

All tested via:

claude --permission-mode bypassPermissions -p 'Call mcp__test-repro__test_tool_union_type with message="hello world"'

Server logs confirmed parameters are being passed properly - no empty {} objects. The union type + null default + required field combination now works as expected.

Thanks for fixing this! 🎉

Great! I'm going to close this issue, but do please open a new issue if you do notice any bad MCP behavior in future. Thanks again for reporting this and glad it's fixed.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.