MCP SDK Pydantic v2 Compatibility Bug Report

[rijovarghese9]

Initial Checks

• I confirm that I'm using the latest version of MCP Python SDK
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Description

Problem Description

Symptoms

MCP clients consistently fail to connect to MCP servers with the error:

Error executing MCP tool: Not connected

This occurs despite MCP servers being properly configured and running.

Root Cause

The MCP Python SDK uses Pydantic v1-style serialization patterns that are incompatible with Pydantic v2. When the SDK attempts to serialize CallToolResult objects in tool responses, it produces malformed data structures.

Impact Assessment

Functional Impact

• Critical: Complete loss of MCP server functionality through the standard MCP client interface
• Universal: Affects all stdio-based MCP servers using the official Python SDK
• Workaround Required: Manual JSON-RPC implementation needed to bypass MCP framework

Affected Components

• MCP client-server communication layer
• Tool response serialization
• All MCP Python SDK versions (confirmed across multiple versions)
• Stdio transport protocol implementation

Suggested Implementation

In MCP SDK - replace problematic serialization

def serialize_tool_result(result: CallToolResult) -> dict:
# Use Pydantic v2 compatible serialization
return result.model_dump() # Direct dictionary conversion

Example Code

Expected Behavior:

# MCP server returns properly structured response
result = CallToolResult(
    content=[TextContent(type="text", text="analysis result")],
    isError=False
)
# Should serialize to: {"content": [...], "isError": false}

Actual Behavior:

# MCP SDK with Pydantic v2 produces tuple corruption
result = CallToolResult(...)  
# Incorrectly serializes to: [("content", [...]), ("isError", false)]
# Instead of: {"content": [...], "isError": false}

Error Manifestation:
Input should be a valid dictionary or instance of TextContent [type=model_type, input_value=('meta', None), input_type=tuple]

This indicates the MCP framework is receiving Python tuples where it expects dictionaries.

Reproduction Steps
1. Environment Setup
# Install MCP SDK (any current version)
pip install mcp

# Create a basic MCP server
cat > test_server.py << 'EOF'
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import CallToolResult, TextContent

app = Server("test-server")

@app.call_tool()
def test_tool():
    return CallToolResult(
        content=[TextContent(type="text", text="Hello World")],
        isError=False
    )

@app.list_tools()
def list_tools():
    return [{"name": "test_tool", "description": "Test tool"}]

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, app.create_initialization_options())

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())
EOF

2. MCP Client Configuration
{
  "mcpServers": {
    "test-server": {
      "command": "python",
      "args": ["test_server.py"]
    }
  }
}

3. Attempt Tool Usage
# This will fail with "Not connected" error
use_mcp_tool(
    server_name="test-server",
    tool_name="test_tool",
    arguments={}
)

Python & MCP Python SDK

__Environment Versions for MCP Bug Report:__

## Python & MCP Python SDK Versions

__Python Version:__ `3.13.5`

__MCP SDK Version:__ `1.18.0`

__Pydantic Version:__ `2.12.3`

## Additional Context

__Installation Method:__ Virtual environment (`venv`)

__Platform:__ Windows 11 Pro (x64)

__MCP Server Implementation:__ Custom stdio-based MCP server for WinDbg crash analysis

__Issue Confirmed On:__ MCP SDK version 1.18.0 with Pydantic 2.12.3

## Version History Tested

During troubleshooting, we tested multiple MCP SDK versions:

- ✅ `1.18.0` (current) - __Bug confirmed__
- ✅ `1.12.3` (downgraded) - __Bug still present__
- ❌ `<1.12.4` (earlier versions) - Still had serialization issues

__Note:__ The bug persists across MCP SDK versions and appears to be a fundamental Pydantic v1/v2 compatibility issue in the MCP framework's serialization logic.

This issue prevents the adoption and use of MCP servers through standard MCP clients and requires urgent attention to restore compatibility with modern Python environments.