Raise CONNECTION_CLOSED for requests sent after the connection closed

send_raw_request raised RuntimeError both before run() and after the
transport closed, contradicting the documented contract that connection
loss surfaces as MCPError(CONNECTION_CLOSED). A closed flag now separates
the two states: RuntimeError remains for use before run(), and a request
after EOF gets the same CONNECTION_CLOSED error the in-flight waiters
receive.

Author: maxisbey

docs/migration.md

@@ -1186,7 +1186,7 @@ Behavior changes:
 - **Unknown-id responses are ignored**, as the spec asks. v1 surfaced them to `message_handler` as a `RuntimeError`; nothing is surfaced now.
 - **Error responses with a null `id`** — the JSON-RPC shape for a peer reporting a parse error — are now dropped with a debug log. v1 surfaced them to `message_handler` as an `MCPError`.
 - **A raising request callback** is answered with `code=0` and the exception text. v1 flattened every callback exception to `INVALID_PARAMS`. Callbacks that want a specific error response should return `ErrorData` (unchanged) or raise `MCPError`. One carve-out: a callback that raises pydantic's `ValidationError` is still answered with `INVALID_PARAMS` (`"Invalid request parameters"`, empty `data`) because the dispatcher cannot distinguish it from inbound-params validation — this conflation is pre-existing v1 behavior, and a revisit is pending.
-- **`send_request` before entering the context manager** raises `RuntimeError` immediately; v1 wrote to the transport and hung until the timeout. `send_notification` before entry still works.
+- **`send_request` before entering the context manager** raises `RuntimeError` immediately; v1 wrote to the transport and hung until the timeout. After the connection has closed, `send_request` instead raises `MCPError` (`CONNECTION_CLOSED`), matching what an in-flight request receives — `RuntimeError` remains only for calls before entry. `send_notification` before entry still works.
 - **`send_notification` no longer takes `related_request_id`, and `send_request` no longer accepts `ServerMessageMetadata`.** The hint was never serialized by any client transport in v1 or v2 — it exists for the server's streamable-HTTP stream routing. Progress and response correlation via `progressToken` and the request id is unaffected.
 - **The private `mcp.shared._context.RequestContext` generic is deleted.** Client callbacks now receive the concrete `mcp.client.ClientRequestContext`, whose `request_id` is always populated (the client only builds a context for inbound requests). Annotations spelled `RequestContext[ClientSession]` become `ClientRequestContext`.
 

src/mcp/shared/jsonrpc_dispatcher.py

@@ -252,6 +252,7 @@ def __init__(
         self._in_flight: dict[RequestId, _InFlight[TransportT]] = {}
         self._tg: anyio.abc.TaskGroup | None = None
         self._running = False
+        self._closed = False
 
     async def send_raw_request(
         self,
@@ -270,10 +271,13 @@ async def send_raw_request(
             MCPError: Peer error response; `REQUEST_TIMEOUT` if
                 `opts["timeout"]` elapsed; `CONNECTION_CLOSED` if the
                 transport closed or the dispatcher shut down.
-            RuntimeError: Called outside `run()`.
+            RuntimeError: Called before `run()`.
         """
+        # Post-close sends get the same CONNECTION_CLOSED contract as in-flight waiters.
+        if self._closed:
+            raise MCPError(code=CONNECTION_CLOSED, message="Connection closed")
         if not self._running:
-            raise RuntimeError("JSONRPCDispatcher.send_raw_request called before run() / after close")
+            raise RuntimeError("JSONRPCDispatcher.send_raw_request called before run()")
         opts = opts or {}
         request_id = self._allocate_id()
         out_params = dict(params) if params is not None else {}
@@ -399,6 +403,7 @@ async def run(
                             logger.debug("read stream closed by transport; treating as EOF")
                     # EOF: wake blocked `send_raw_request` waiters with CONNECTION_CLOSED.
                     self._running = False
+                    self._closed = True
                     self._fan_out_closed()
                 finally:
                     # Cancel in-flight handlers; otherwise the task-group join
@@ -407,6 +412,7 @@ async def run(
         finally:
             # Covers cancel/crash paths that skip the inline fan-out; idempotent.
             self._running = False
+            self._closed = True
             self._tg = None
             self._fan_out_closed()
 

tests/shared/test_jsonrpc_dispatcher.py

@@ -1221,6 +1221,26 @@ async def test_send_raw_request_before_run_raises_runtimeerror():
             s.close()
 
 
+@pytest.mark.anyio
+async def test_send_raw_request_after_connection_close_raises_connection_closed():
+    """Sending after run() saw EOF raises MCPError(CONNECTION_CLOSED) — the same contract
+    in-flight waiters get — not RuntimeError (SDK-defined)."""
+    c2s_send, c2s_recv = anyio.create_memory_object_stream[SessionMessage | Exception](1)
+    s2c_send, s2c_recv = anyio.create_memory_object_stream[SessionMessage | Exception](1)
+    client: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher(s2c_recv, c2s_send)
+    on_request, on_notify = echo_handlers(Recorder())
+    try:
+        s2c_send.close()  # peer drops: run() sees immediate EOF and returns
+        with anyio.fail_after(5):
+            await client.run(on_request, on_notify)
+        with pytest.raises(MCPError) as exc:
+            await client.send_raw_request("ping", None)
+        assert exc.value.error.code == CONNECTION_CLOSED
+    finally:
+        for s in (c2s_send, c2s_recv, s2c_send, s2c_recv):
+            s.close()
+
+
 @pytest.mark.anyio
 async def test_transport_exception_in_read_stream_is_logged_and_dropped():
     c2s_send, c2s_recv = anyio.create_memory_object_stream[SessionMessage | Exception](4)