Introduce a shared Transport abstraction to reduce stdio/SSE/WebSocket/HTTP duplication

[dgenio]

Summary

The SDK currently implements multiple server and client transports (stdio, SSE, WebSocket, Streamable HTTP). Each one has its own message loop, error handling, and resource management logic with significant duplication.

This makes it harder to:

• fix bugs consistently across transports,
• add new transports, and
• ensure feature parity between them.

A small Transport abstraction could centralize most of the shared behavior.

Problems

• Duplication: Similar read/write loops and error handling are repeated in:
  • src/mcp/server/stdio.py
  • src/mcp/server/sse.py
  • src/mcp/server/websocket.py
  • src/mcp/server/streamable_http.py
• Inconsistent behavior: Features like cancellation, error mapping, and shutdown can diverge between transports.
• Maintenance cost: Adding a new transport or changing session semantics requires updating each implementation.

Proposal

1. Define a Transport protocol/interface

   For example:

   class Transport(Protocol):
       async def connect(self) -> None: ...
       async def send_message(self, message: JSONType) -> None: ...
       async def receive_message(self) -> JSONType | None: ...
       async def close(self) -> None: ...

• Implementations handle encoding details (JSON lines, SSE, WebSocket frames, HTTP streaming).

2. Refactor sessions to depend on Transport

   • BaseSession (and server/client sessions) should operate on a Transport instance rather than transport-specific primitives.
   • Transport-agnostic session logic (request routing, error mapping) lives in one place.

3. Align behavior across transports

   • Standardize behavior for:

     • connection setup/teardown,
     • error handling,
     • cancellation and shutdown semantics.

4. Incremental migration

   • Start with one or two transports (e.g. stdio + Streamable HTTP) to validate the abstraction.
   • Gradually migrate remaining transports.

Why this matters

• Consistency: Users can expect the same semantics regardless of transport choice.
• Easier maintenance: Bug fixes and feature additions happen once, in a shared layer.
• Future-proofing: Adding new transports becomes easier and less error-prone.

Acceptance criteria

• A Transport interface (or equivalent) is defined for server and client usage.
• At least two transports are refactored to use the shared abstraction.
• Session logic no longer duplicates transport-specific read/write loops.
• Tests verify identical semantics (errors, cancellation, shutdown) across transports.

[maxisbey]

Note: This issue now consolidates the following related issues:

• Replace anyio memory streams with a simpler transport abstraction #1735 (Replace anyio memory streams with a simpler transport abstraction) - the new Transport abstraction should use simpler primitives that propagate errors clearly
• Should add a guiding TransportProtocol for custom transports? (similar to TypeScript interface) #1187 (Add guiding TransportProtocol for custom transports) - the Transport Protocol defined here serves as guidance for custom transport implementations

Both are being closed as duplicates.

[dgenio]

Checking back in after following the related activity since this was filed.

PR #2320 — Dispatcher component

@maxisbey's Draft PR #2320 ("Extract JSON-RPC wrapping into a Dispatcher component") addresses the coupling I described between session semantics and wire encoding. The approach — composition rather than inheritance, extracting JSONRPCDispatcher from BaseSession with a Dispatcher protocol — is a pragmatic first step that lets teams plug in non-JSON-RPC wire formats (gRPC, message brokers, etc.) without rebuilding the entire MCP method surface.

A question for maintainers: does #2320 satisfy this issue's acceptance criteria, or is there still a desire for a lower-level Transport protocol (encoding + connection lifecycle, not just dispatch)? That lower layer was part of the original proposal and would help with items like standardising cancellation and shutdown semantics across transports.

Spec gate update — no longer a blocker

The spec blocker mentioned in PR #2320 (custom transports MUST preserve JSON-RPC per the 2025-11-25 spec) now has a clear resolution path:

• SEP-1352 (gRPC as official transport) was closed on Jan 14, 2026 by its Google authors, explicitly because pluggable/custom transports in the SDK are the preferred path — so gRPC and similar alternatives are expected to land as community custom transports, not spec-mandated ones.
• SEP-1319 (decouple request payload from RPC methods) is marked final/completed, meaning the schema-level decoupling needed as a foundation is done.
• The Transport Working Group's Dec 2025 roadmap explicitly states: "Our focus is on making Custom Transports easier to implement by improving SDK integration."

So the remaining spec update (loosening the JSON-RPC requirement for custom transports) is aligned with the official roadmap and should not block merging the Dispatcher plumbing in the SDK.

Happy to help with the spec wording update if that would unblock #2320.