claude-code - 💡(How to fix) Fix [BUG] MCP tool calls with Optional list parameters fail — list serialized as string [2 comments, 2 participants]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

When Claude Code calls an MCP tool that has an optional list parameter (e.g., remove_label_ids: Optional[List[str]]), it passes the value as a JSON string ('["INBOX"]') instead of a proper array. The MCP server then rejects it with a Pydantic validation error: Input should be a valid list [type=list_type, input_value='["INBOX"]', input_type=str].

The MCP server function signature, schema, and implementation are all correct. Calling the function directly from Python works fine. The issue is in how Claude Code serializes list parameters before sending them to the MCP server.

MCP server: taylorwilsdon/google_workspace_mcp (local stdio transport) Tool affected: batch_modify_gmail_message_labels (and likely any MCP tool with Optional[List[str]] parameters) Workaround: Call the MCP server's underlying Python function directly via Bash, bypassing the Claude Code MCP client layer.

What Should Happen?

When I pass a list of label IDs to an MCP tool (e.g., ["INBOX"]), the MCP server should receive it as a proper list. Instead it receives a string ('["INBOX"]') and rejects it with a Pydantic validation error. The tool call should succeed and the labels should be updated.

Error Messages/Logs

1 validation error for call[batch_modify_gmail_message_labels]
remove_label_ids
  Input should be a valid list [type=list_type, input_value='["INBOX"]', input_type=str]
    For further information visit https://errors.pydantic.dev/2.12/v/list_type

Steps to Reproduce

1. Connect a local MCP server via stdio transport (I use taylorwilsdon/google_workspace_mcp)
2. Call any MCP tool that has an Optional[List[str]] parameter
3. Pass a list value (e.g., ["INBOX"]) for that parameter
4. The MCP server receives the value as the string '["INBOX"]' instead of a list, causing a Pydantic validation error
5. Calling the same function directly from Python (bypassing Claude Code) works correctly

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

Unknown — confirmed working on May 12, 2026. Stopped working sometime after that. No changes were made to the MCP server or its dependencies between then and now.

Claude Code Version

2.1.123

Platform

Other

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

No response