fix: raise clear error for server-to-client requests in stateless mode by maxisbey · Pull Request #1827 · modelcontextprotocol/python-sdk

maxisbey · 2026-01-05T16:34:58Z

Motivation and Context

Server-to-client requests (list_roots, create_message, elicit_form, elicit_url) require bidirectional communication which is not available in stateless HTTP mode. Previously, these requests would hang indefinitely. Now they raise an immediate RuntimeError with a clear, actionable message:

RuntimeError: Cannot use list_roots in stateless HTTP mode. Stateless mode does not support server-to-client requests. Use stateful mode (stateless_http=False) to enable this feature.

Technical Context: Why This Cannot Work

The Fundamental Problem

In stateless mode (stateless_http=True), each HTTP request creates a completely fresh transport with no session tracking:

# streamable_http_manager.py:168-173
http_transport = StreamableHTTPServerTransport(
    mcp_session_id=None,    # NO session tracking
    event_store=None,       # NO resumability
)

When a server tool handler calls session.elicit() or session.create_message():

send_request() blocks waiting for a response - It creates a response stream and waits:

response_stream, response_stream_reader = anyio.create_memory_object_stream[...]()
await self._write_stream.send(SessionMessage(...))
response_or_error = await response_stream_reader.receive()  # Blocks forever

In JSON response mode: The server-initiated request is discarded before reaching the client:

# streamable_http.py:548-555
async for event_message in request_stream_reader:
    if isinstance(event_message.message.root, JSONRPCResponse | JSONRPCError):
        response_message = event_message.message
        break
    else:
        logger.debug(f"received: {event_message.message.root.method}")  # Just logs it\!

In SSE mode: The request IS sent to the client via SSE, but:
- Client receives the elicitation request
- Client needs to send back a JSONRPCResponse via POST
- In stateless mode, this POST creates a NEW transport with no knowledge of the pending request
- The original send_request() blocks forever waiting on a response stream that will never receive anything

Why `related_request_id` Doesn't Help

The related_request_id metadata helps route server messages to the correct SSE stream (the one handling the original tool call), but it does NOT solve the fundamental problem:

In JSON mode: Messages are discarded before reaching the client
In SSE mode: The client's response creates a new transport with no correlation mechanism

What This Looks Like in Practice

Mode	Server→Client Request Sent?	Client Can Respond?	Result
JSON Response + Stateless	NO (discarded)	N/A	Hangs
SSE + Stateless	YES	NO (no session)	Hangs
SSE + Stateful	YES	YES	Works

Future Direction (SEP-1442)

The upcoming transport changes will properly address this with:

Intermediate result responses for "pausing" requests
Cookie mechanism for correlating resumed requests
Sessions at the data model layer, not protocol layer

Until then, failing fast with a clear error is the best we can do.

How Has This Been Tested?

Reproduced the original issue with the reporter's code - confirmed hang behavior
Added 7 new unit tests covering all affected methods
Verified existing tests still pass

Breaking Changes

Yes, but intentionally so. Code that previously hung indefinitely will now raise a RuntimeError. This is a strict improvement - failing fast with a clear error is better than hanging.

Types of changes

Bug fix (non-breaking change which fixes an issue)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Server-to-client requests (list_roots, create_message, elicit_form, elicit_url) require bidirectional communication which is not available in stateless HTTP mode. Previously, these requests would hang indefinitely. Now they raise an immediate RuntimeError with a clear message explaining the limitation and how to fix it. Changes: - Store _stateless flag in ServerSession.__init__ - Add _require_stateful_mode() helper that raises RuntimeError - Add checks to list_roots(), create_message(), elicit_form(), elicit_url() - Add comprehensive unit tests Github-Issue: #1097 Claude-Generated-By: Claude Code (cli/claude-opus-4-5=100%) Claude-Steers: 4 Claude-Permission-Prompts: 26 Claude-Escapes: 0

Kludex · 2026-01-05T17:10:49Z

tests/server/test_stateless_mode.py

+            create_init_options(),
+            stateless=True,
+        ) as session:
+            with pytest.raises(RuntimeError) as exc_info:


Add the match= please, RuntimeError can be a lot.

Yep fair will do

Kludex · 2026-01-05T17:11:15Z

tests/server/test_stateless_mode.py

+    (
+        server_to_client_send,
+        server_to_client_receive,
+        client_to_server_send,
+        client_to_server_receive,
+    ) = create_test_streams()
+
+    async with (
+        client_to_server_send,
+        client_to_server_receive,
+        server_to_client_send,
+        server_to_client_receive,
+    ):
+        async with ServerSession(
+            client_to_server_receive,
+            server_to_client_send,
+            create_init_options(),
+            stateless=True,
+        ) as session:


Can't this whole thing be a fixture?

pcarleton

Conceptually LGTM, I defer to @Kludex on test setup

pcarleton · 2026-01-05T17:18:13Z

doh... didn't realize it was on automerge

Kludex · 2026-01-05T17:20:20Z

src/mcp/server/session.py

+    def _require_stateful_mode(self, feature_name: str) -> None:
+        """Raise an error if trying to use a feature that requires stateful mode.
+
+        Server-to-client requests (sampling, elicitation, list_roots) are not
+        supported in stateless HTTP mode because there is no persistent connection
+        for bidirectional communication.
+
+        Args:
+            feature_name: Name of the feature being used (for error message)
+
+        Raises:
+            RuntimeError: If the session is in stateless mode
+        """
+        if self._stateless:
+            raise RuntimeError(
+                f"Cannot use {feature_name} in stateless HTTP mode. "
+                "Stateless mode does not support server-to-client requests. "
+                "Use stateful mode (stateless_http=False) to enable this feature."
+            )


This kind of private function adds a bit of overhead while reading the code. If possible, can we create a specific exception and do the check on each feature method itself?

if self._stateless: raise MethodNotSupported(method="sampling")

On MethodNotSupported you can set up the message.

MethodNotSupported what are you thinking for the error message? As currently it's specific to stateless http and MethodNotSupported sounds more generic

You can think of a better name, but the point stands.

Although I suggested this, I still think that something is missing conceptually - we should be able to check this or define somehow the capabilities of stateless in a different way - and be able to handle this before it reaches the methods.

Yea, although this is more of a bandaid fix given that this version of stateless mode isn't really supported in the spec. The upcoming changes to the spec will significantly change how statefulness will work anyway so I didn't want to spend too much time worrying about how it looks since it has to change anyway.

Kludex · 2026-01-05T17:20:30Z

...

Address review feedback from PR #1827: - Create StatelessModeNotSupported exception that inherits from RuntimeError - Replace _require_stateful_mode() helper with inline checks in each method - Add match= parameter to pytest.raises() calls for more specific error matching - Create stateless_session and stateful_session fixtures to reduce test boilerplate - Add test for exception's method attribute Claude-Generated-By: Claude Code (cli/claude-opus-4-5=100%) Claude-Steers: 7 Claude-Permission-Prompts: 26 Claude-Escapes: 1

maxisbey mentioned this pull request Jan 5, 2026

Roots/List Request Hangs in Client-Server Communication #1097

Closed

2 tasks

maxisbey requested review from Kludex and felixweinberger January 5, 2026 16:39

maxisbey marked this pull request as draft January 5, 2026 16:42

maxisbey marked this pull request as ready for review January 5, 2026 16:53

maxisbey enabled auto-merge (squash) January 5, 2026 17:09

Kludex reviewed Jan 5, 2026

View reviewed changes

pcarleton approved these changes Jan 5, 2026

View reviewed changes

maxisbey merged commit bb6cb02 into main Jan 5, 2026
21 checks passed

maxisbey deleted the fix/stateless-mode-server-to-client-error branch January 5, 2026 17:17

Kludex reviewed Jan 5, 2026

View reviewed changes

maxisbey mentioned this pull request Jan 5, 2026

fix: add StatelessModeNotSupported exception and improve tests #1828

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: raise clear error for server-to-client requests in stateless mode#1827

fix: raise clear error for server-to-client requests in stateless mode#1827
maxisbey merged 1 commit intomainfrom
fix/stateless-mode-server-to-client-error

maxisbey commented Jan 5, 2026 •

edited

Loading

Uh oh!

Kludex Jan 5, 2026

Uh oh!

maxisbey Jan 5, 2026

Uh oh!

Kludex Jan 5, 2026

Uh oh!

pcarleton left a comment

Uh oh!

Uh oh!

pcarleton commented Jan 5, 2026

Uh oh!

Kludex Jan 5, 2026

Uh oh!

maxisbey Jan 5, 2026

Uh oh!

Kludex Jan 5, 2026

Uh oh!

maxisbey Jan 6, 2026

Uh oh!

Kludex commented Jan 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

maxisbey commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Technical Context: Why This Cannot Work

The Fundamental Problem

Why related_request_id Doesn't Help

What This Looks Like in Practice

Future Direction (SEP-1442)

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

Kludex Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

maxisbey Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Kludex Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

pcarleton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pcarleton commented Jan 5, 2026

Uh oh!

Kludex Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

maxisbey Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Kludex Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

maxisbey Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Kludex commented Jan 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

maxisbey commented Jan 5, 2026 •

edited

Loading

Why `related_request_id` Doesn't Help