McpError is not pickle-safe and fails to unpickle

[rain87]

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

Summary

mcp.shared.exceptions.McpError does not survive a normal cloudpickle.dumps() / cloudpickle.loads() round-trip.

The failure appears to come from McpError.__init__ expecting an ErrorData object, while exception unpickling reconstructs it with a plain string from Exception.args.

This is surfacing for us through background task execution, but the bug reproduces without Docket/FastMCP task machinery.

Actual behavior

Unpickling fails with:

AttributeError: 'str' object has no attribute 'message'

Traceback points at McpError.__init__:

class McpError(Exception):
 error: ErrorData

 def __init__(self, error: ErrorData):
 super().__init__(error.message)
 self.error = error

Expected behavior

McpError(ErrorData(...)) should round-trip through pickle/cloudpickle without crashing.

At minimum, this should work:

• serialize McpError
• deserialize McpError
• preserve the message
• preserve the error payload, or at least degrade safely without raising during unpickle

Suspected root cause

McpError stores error.message in Exception.args via super().__init__(error.message).

On unpickle, exception reconstruction uses args, so McpError is effectively reconstructed as:

McpError("Authentication Required")

But McpError.__init__ assumes error is always an ErrorData, so it does:

error.message

which crashes for str.

Suggested fix

McpError likely needs to be pickle-safe by design. Any of these would probably fix it:

1. Make __init__ accept both ErrorData and str, normalizing str into an ErrorData.
2. Implement __reduce__ so pickle reconstructs using the full ErrorData.
3. Ensure constructor args and exception state are aligned with standard exception pickling behavior.

A robust version would probably do both __reduce__ and tolerant initialization.

Notes

This bug is easy to misattribute to cloudpickle or task runners, but the reproducer above shows it is local to McpError itself.

Example Code

from importlib.metadata import version

import cloudpickle
from mcp.shared.exceptions import McpError
from mcp.types import ErrorData


print("Versions:")
print(f" mcp={version('mcp')}")
print(f" cloudpickle={version('cloudpickle')}")

original = McpError(ErrorData(code=-32600, message="Authentication Required"))

print("\nOriginal exception:")
print(f" type={type(original).__name__}")
print(f" str={str(original)!r}")
print(f" error_type={type(original.error).__name__}")
print(f" error_message={original.error.message!r}")

payload = cloudpickle.dumps(original)

print("\nUnpickling:")
restored = cloudpickle.loads(payload)
print(f" restored_type={type(restored).__name__}")
print(f" restored_args={restored.args!r}")
print(f" restored_error={getattr(restored, 'error', None)!r}")

Python & MCP Python SDK

- `mcp==1.26.0`
- `fastmcp==3.2.3`
- `cloudpickle==3.1.2`
- Python 3.13

[faridun-ag2]

Hi! I'd like to work on this.
I've reproduced the bug on mcp==1.27.0 with both pickle and cloudpickle. As you noted, the root cause is super().init(error.message) storing a plain string in Exception.args, while McpError.init expects ErrorData.
I agree that combining approaches 2 + 1 is the most robust fix:

reduce to preserve the full ErrorData through pickle round-trips
Tolerant init that normalizes str → ErrorData as a safety net

I also noticed UrlElicitationRequiredError has the same issue on v1.x — its init expects (elicitations, message) but inherits args that don't match. I'll fix both in the same PR.
Targeting v1.x per the contributing guide. Can I be assigned?

[mcp-claude]

bug is partially fixed on main (MCPError now pickle-safe), but UrlElicitationRequiredError still fails. both McpError and UrlElicitationRequiredError fail on v1.x.

root cause: pickle reconstructs exceptions by calling cls(*self.args). on main, UrlElicitationRequiredError stores args=(code_int, message_str, data_dict) via MCPError.__init__, but its own __init__ expects (elicitations: list[ElicitRequestURLParams], message) — the types don't match. on v1.x, McpError stores args=(message_str,) but its __init__ expects an ErrorData object.

workaround: implement __reduce__ to control pickle reconstruction, or add a __new__-compatible signature.

repro script (repro.py, runs on main)

import pickle
import traceback

from mcp.shared.exceptions import MCPError, UrlElicitationRequiredError
from mcp.types import ElicitRequestURLParams, ErrorData

print("=== MCPError pickle round-trip ===")
try:
 original = MCPError(code=-32600, message="Authentication Required")
 payload = pickle.dumps(original)
 restored = pickle.loads(payload)
 print(f"restored message: {restored.message!r}")
 print("MCPError: PASS")
except Exception as e:
 print(f"MCPError: FAIL — {type(e).__name__}: {e}")
 traceback.print_exc()

print()
print("=== UrlElicitationRequiredError pickle round-trip ===")
try:
 elicitations = [
 ElicitRequestURLParams(
 message="Authorization required",
 url="https://example.com/oauth/authorize",
 elicitation_id="auth-001",
 )
 ]
 original = UrlElicitationRequiredError(elicitations)
 print(f"original: args={original.args!r}")
 payload = pickle.dumps(original)
 restored = pickle.loads(payload)
 print(f"restored elicitations: {restored.elicitations!r}")
 print("UrlElicitationRequiredError: PASS")
except Exception as e:
 print(f"UrlElicitationRequiredError: FAIL — {type(e).__name__}: {e}")
 traceback.print_exc()

command + output (main, commit 3d7b311)

$ uv run python repro.py
=== MCPError pickle round-trip ===
original: args=(-32600, 'Authentication Required', None), error=ErrorData(...)
restored message: 'Authentication Required'
MCPError: PASS

=== UrlElicitationRequiredError pickle round-trip ===
original: args=(-32042, 'URL elicitation required', {'elicitations': [...]})
UrlElicitationRequiredError: FAIL — TypeError: UrlElicitationRequiredError.__init__() takes from 2 to 3 positional arguments but 4 were given

v1.x (commit 73d458b)

both fail:

• McpError: AttributeError: 'str' object has no attribute 'message'
• UrlElicitationRequiredError: AttributeError: 'str' object has no attribute 'model_dump'

status: fixed on main for MCPError, not fixed for UrlElicitationRequiredError. v1.x needs both fixed. fix is straightforward — add __reduce__ to UrlElicitationRequiredError on main; add __reduce__ to both McpError and UrlElicitationRequiredError on v1.x.

suggested fix

# src/mcp/shared/exceptions.py
 elicitations = [ElicitRequestURLParams.model_validate(e) for e in raw_elicitations]
 return cls(elicitations, error.message)
+
+ def __reduce__(self) -> tuple:
+ return (self.from_error, (self.error,))

test to verify: pickle round-trip of UrlElicitationRequiredError restores elicitations list and message intact (see test_url_elicitation_required_error_pickle_roundtrip in tests/shared/test_exceptions.py).

[Christian-Sidak]

Opened a fix in #2471 -- adds a __reduce__ method to UrlElicitationRequiredError so it round-trips correctly through pickle, and adds pickle round-trip tests for both MCPError and UrlElicitationRequiredError.

[Naveenreddie-think]

I'd like to pick this up , noticed PR #2439 had a working approach that stalled from inactivity. Happy to open a fresh PR building on that fix if that works.