ClientSession receive loop swallows callback exceptions, replying "Invalid request parameters" to the server instead of propagating to the call_tool awaiter

[danielgshea]

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

I hit this while wiring an MCP tool that uses ctx.elicit(...) into a
LangGraph agent — the natural pattern of calling interrupt() from the
client elicitation callback does not work because the callback's exception
is swallowed by _receive_loop and replied to the server as
Invalid request parameters. The same limitation blocks any framework that
relies on exception-based control flow on the awaiter's task (custom
async-cancellation strategies, Trio nursery patterns, retry/backoff
libraries, any human-in-the-loop integration), so a small SDK-level escape
hatch would unblock a broad class of MCP client developers, not just this
one use case.

Any exception raised inside a ClientSession callback
(elicitation_callback, sampling_callback, list_roots_callback) is
caught by the blanket except Exception in BaseSession._receive_loop
(src/mcp/shared/session.py) and turned into a JSON-RPC
Invalid request parameters reply to the server:

except Exception:
    logging.warning("Failed to validate request", exc_info=True)
    error_response = JSONRPCError(
        jsonrpc="2.0",
        id=message.message.id,
        error=ErrorData(code=INVALID_PARAMS, message="Invalid request parameters", data=""),
    )
    await self._write_stream.send(SessionMessage(message=error_response))

Consequences:

1. The server is blamed for "invalid params" when the failure was on the
   client. The original callback traceback is lost from the awaiter of
   session.call_tool(...).
2. Callbacks have no way to abort back to the awaiter. Frameworks that use
   exception-based flow control on the caller's task (LangGraph's
   interrupt() for human-in-the-loop pause/resume is the motivating
   case) cannot be wired through MCP without per-framework workarounds.

Expected: an opt-in escape hatch so a callback can raise an exception
that propagates out of the in-flight session.call_tool(...) instead of
becoming a JSON-RPC error to the server. Defaulting opt-in to off preserves
existing behaviour.

Proposed minimal fix (single file, ~30 lines, three coordinated edits):

# src/mcp/shared/session.py
#
# (1) BaseSession.__init__: add a per-session stash for marked exceptions.
self._propagate_errors: dict[RequestId, BaseException] = {}

# (2) Inside _receive_loop's request-handler `except Exception as e:` block,
#     branch on the marker before the existing INVALID_PARAMS path.
if getattr(e, "__mcp_propagate__", False):
    # Notify the peer so their request doesn't hang.
    error_response = JSONRPCError(
        jsonrpc="2.0",
        id=message.message.root.id,
        error=ErrorData(code=INTERNAL_ERROR, message="Handler raised", data=""),
    )
    await self._write_stream.send(SessionMessage(message=JSONRPCMessage(error_response)))
    # Surface to the awaiter of any in-flight outgoing request on this session.
    for in_flight_id, stream in list(self._response_streams.items()):
        self._propagate_errors[in_flight_id] = e
        await stream.aclose()
    continue
# ...existing INVALID_PARAMS path unchanged below this point.

# (3) Inside send_request, alongside the existing `except TimeoutError:`,
#     consume the stash on EndOfStream and re-raise the original exception.
except anyio.EndOfStream:
    propagate = self._propagate_errors.pop(request_id, None)
    if propagate is not None:
        raise propagate from None
    raise

I've already implemented and tested this locally against v1.x (and the
same shape on main for the V2 rework): ~33 lines added to
src/mcp/shared/session.py plus regression tests in
tests/shared/test_session.py. The patch is strictly additive — without the
__mcp_propagate__ marker, behaviour is byte-identical to today. End-to-end
verified by surfacing a LangGraph interrupt() from an elicitation callback
as a normal __interrupt__ on the agent's first invoke. ruff / pyright
clean, existing session tests still pass. Happy to open a PR once the issue
is accepted and you've confirmed the direction.

Example Code

# Self-contained reproduction. No third-party agent framework needed.
#
# Terminal A:  python repro_server.py
# Terminal B:  python repro_client.py
#
# Observed in A: WARNING:root:Failed to validate request: CallbackBoom(...)
# Observed in B: tool result.isError = True, CallbackBoom was NEVER raised
#                on the awaiter — silently converted to INVALID_PARAMS.

# --- repro_server.py ---
from mcp.server.fastmcp import Context, FastMCP
from pydantic import BaseModel

class Answer(BaseModel):
    value: str

server = FastMCP(name="repro", port=8765)

@server.tool()
async def ask(ctx: Context) -> str:
    result = await ctx.elicit(message="hello?", schema=Answer)
    return f"got: {result}"

if __name__ == "__main__":
    server.run(transport="streamable-http")


# --- repro_client.py ---
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

class CallbackBoom(Exception):
    """Stand-in for any framework's flow-control exception (e.g. GraphInterrupt)."""

async def on_elicit(ctx, params):
    raise CallbackBoom("callback wants to abort back to the awaiter")

async def main():
    async with streamablehttp_client("http://127.0.0.1:8765/mcp") as (r, w, _):
        async with ClientSession(r, w, elicitation_callback=on_elicit) as session:
            await session.initialize()
            try:
                result = await session.call_tool("ask", {})
            except CallbackBoom:
                print("OK: CallbackBoom propagated to the awaiter")
                return
            print("BUG: awaiter did not raise; result.isError =", result.isError)
            print("     content =", result.content)

asyncio.run(main())

Python & MCP Python SDK

Python: 3.13
mcp:    1.27.1

[norika1207-lab]

This looks worth pinning down as a protocol-level regression rather than only an implementation bug.

For receive loop swallows callback exceptions, the acceptance test I would want is a minimal client/server fixture that records the exact JSON-RPC or HTTP exchange, then asserts both the wire result and the local lifecycle state after the failure path. In MCP deployments, the dangerous failures are often not just wrong return values; they are pending requests, dropped notifications, mismatched session state, or errors that get translated into a generic response and become impossible to diagnose.

A useful fix boundary would preserve three signals: the protocol error sent to the peer, the local exception or cancellation reason available to application code, and a trace/log field that ties the two together. That makes the behavior debuggable for agent hosts without requiring every host to special-case this SDK detail.

[Ar-maan05]

Following up on @scosemicolon's correlation point, since it's the crux of whether this is actionable:

Correlation scope. The motivating case, a synchronous session.call_tool(...) awaiter whose server triggered the elicitation/sampling callback, has exactly one in-flight outgoing request on the session when the callback runs, so attribution is unambiguous. For sessions with multiple concurrent in-flight requests, the protocol carries no callback→originating-request link, so I'd propose defining the behavior as session-scoped: the marked exception is stashed against every in-flight outgoing request, and each awaiter on that session re-raises it. Coarse but safe (all in-flight callers abort rather than hang); finer per-request attribution would need a protocol change and is explicitly out of scope here.

Rewrite-proof acceptance. Since #2710 deletes BaseSession, the behavior is best pinnssion rather than tied to _receive_loop:

# opt-in marker → exception reaches the awaiter, NOT result.isError
class Boom(Exception):
    __mcp_propagate__ = True
async def on_elicit(ctx, params):
    raise Boom()
# in-memory client/server pair, elicitation_callback=on_elicit
with pytest.raises(Boom):
    await session.call_tool("ask", {})

# no marker → behaviour byte-identical to today (server gets INVALID_PARAMS,
# awaiter sees result.isError, no exception)

That keeps the contract intact whether it lands on the current loop or the new JSONRPCDispatcher/ServerRunner path.

[Oxygen56]

I'd like to pick this up and implement the fix — thanks for the detailed write-up and repro.

Root cause (confirmed). In BaseSession._receive_loop (src/mcp/shared/session.py), the request branch wraps the dispatch to _received_request(...) in a blanket except Exception, which turns any callback failure (elicitation_callback / sampling_callback / list_roots_callback) into a JSON-RPC INVALID_PARAMS reply to the server. The original traceback is lost and the awaiter of the in-flight call_tool(...) never sees it, so exception-based control flow (LangGraph interrupt(), Trio nursery cancellation, human-in-the-loop) can't be wired through.

On the session-level escape hatch. I agree with @scosemicolon's concern: a session-wide "propagate to every in-flight stream" approach is racy under concurrency — if two call_tool(...) calls are in flight and only one triggers the failing callback, closing/erroring all response streams would incorrectly tear down the unrelated sibling. The escape hatch should be scoped to the single interaction that produced the failing server request.

Proposed direction — precise correlation. The transport already knows which outgoing request a server-initiated request belongs to: in streamable_http.py, each POST opens its own per-request SSE stream and tracks the original_request_id. The problem is that this correlation isn't surfaced to the session layer today — incoming messages are wrapped as SessionMessage(message) with no metadata, so _receive_loop has no way to map the failing callback back to the originating outgoing request.

Concretely I'd:

1. Have the streamable-HTTP client attach related_request_id (the SSE stream's original_request_id) to the inbound SessionMessage.metadata for server-initiated requests — mirroring how the server side already uses ServerMessageMetadata.related_request_id for outbound routing.
2. In _receive_loop, on an opt-in marked callback exception, error only the _response_streams[related_request_id] entry and re-raise the original exception to that specific awaiter — leaving sibling in-flight requests untouched. Default behavior (no marker) stays byte-identical to today.

This keeps the default JSON-RPC INVALID_PARAMS path intact for ordinary callback bugs while making framework-level control-flow exceptions usable without surprising unrelated requests. I'd add a regression test with two concurrent call_tool() calls (one triggers a raising callback, the other must complete normally), as @scosemicolon suggested.

This does span two modules (transport + session), so before I open a PR I'd like to confirm the direction:

• (a) Is the precise-correlation approach (threading related_request_id from transport into the session layer) acceptable?
• (b) Or would you prefer a lighter-weight mechanism to achieve the same per-request scoping?

I have a working local prototype and am happy to open the PR once the direction is confirmed.