[BUG] Claude Code MCP Parameter Serialization Bug

Claude Code MCP Parameter Serialization Bug

Summary

Claude Code is sending empty parameter dictionaries {} to MCP servers, breaking all tools that require parameters.

Environment

• Claude Code version: Latest (July 2025) - check with claude --version
• OS: macOS Darwin 24.3.0
• Node.js: v23.11.0
• MCP SDK: @modelcontextprotocol/sdk (latest)
• Server type: Both stdio and HTTP MCP servers affected

Expected Behavior

When calling MCP tools with parameters like:
mcp__server-name__tool_name
Parameters: {"param1": "value1", "param2": "value2"}
The MCP server should receive the parameters correctly in request.params.

Actual Behavior

MCP servers receive empty parameter dictionaries {} regardless of what parameters are specified in Claude Code.

Evidence

Production Server Logs

Server logs consistently show:
"Raw params_dict: {}"
"Type of params_dict: <class 'dict'>"

Comprehensive Testing Results

• ✅ Direct MCP Protocol: Works perfectly - parameters properly received
• ✅ Claude Desktop: Works perfectly with identical servers
• ❌ Claude Code: Sends empty objects instead of parameters
• ✅ 48-tool production system: Works flawlessly in Claude Desktop, fails in Claude Code

Reproduction Steps

Quick Reproduction

1. Set up any MCP server with tools requiring parameters
2. Configure Claude Code to use the server: claude mcp add server-name "node" "/path/to/server.js"
3. Call any tool with parameters
4. Check server logs - parameters are empty {}

Detailed Reproduction (Attached Files)

The attached claude-code-mcp-bug-repro folder contains a complete reproduction case:

1. Install: npm install
2. Verify server works: ./test-mcp-direct.sh (shows parameters received correctly)
3. Configure Claude Code: claude mcp add test-server "node" "/path/to/test-server.js"
4. Test in Claude Code: Call mcp__test-server__test_tool with test_param: "hello"
5. Observe bug: Server logs show empty parameters despite tool call

Root Cause

Parameter serialization bug in Claude Code's MCP implementation. The issue is NOT in:

• ❌ MCP server implementations (work perfectly with direct protocol)
• ❌ Parameter schemas (correctly defined)
• ❌ MCP SDK (works with Claude Desktop)

The bug IS in:

• ✅ Claude Code's parameter passing to MCP servers

Impact

• All parameterized MCP tools are broken in Claude Code
• Same tools work perfectly in Claude Desktop
• Affects entire MCP ecosystem compatibility
• Forces users to switch to Claude Desktop for MCP workflows
• Breaks production systems (our 48-tool email management platform)

Comparison: Working vs Broken

| Environment | Parameter Reception | Status |
|---------------------|---------------------------------------------------|----------|
| Direct MCP Protocol | {"name": "tool", "arguments": {"param": "value"}} | ✅ Works |
| Claude Desktop | Parameters received correctly | ✅ Works |
| Claude Code | {} (empty object) | ❌ Broken |

Workaround

Use Claude Desktop instead of Claude Code for MCP tools requiring parameters.

Additional Context

• Simple tools with no parameters work correctly in Claude Code
• Issue affects both custom and official MCP servers
• Parameter schemas are correctly defined per MCP specification
• Direct API calls to servers work with proper parameters
• Multiple server architectures tested (stdio, HTTP, different languages)

Attached Files

Complete reproduction package in claude-code-mcp-bug-repro/:

• test-server.js - Minimal MCP server with detailed parameter logging
• test-mcp-direct.sh - Proof that direct MCP protocol works
• REPRODUCTION_STEPS.md - Step-by-step reproduction guide
• BUG_EVIDENCE.md - Comprehensive evidence documentation
• package.json - Required dependencies

---
Priority: High - This breaks fundamental MCP compatibility for Claude Code users and significantly impacts the MCP ecosystem
adoption.

BUG_EVIDENCE.md
REPRODUCTION_STEPS.md
package-lock.json
package.json