Pluggable Transport Abstractions

[asheshvidyut]

Motivation and Context

Add support for Pluggable Transport Abstractions in MCP Python SDK.

Add abstractions to support Pluggable Transport.

This PR majorly adds two abstract classes and APIs that every transport must implement. The abstract classes are

• src/mcp/client/transport_session.py -> ClientTransportSession
• src/mcp/server/transport_session.py -> ServerTransportSession

Both the above classes have minimal APIs that every transport must implement in order to achieve the features defined in MCP Specification

Additionally existing transport classes which are based on JSONRPC inherits from these two new classes.

src/mcp/client/session.py -> ClientSession -> inherits from src/mcp/client/transport_session.py -> ClientTransportSession
src/mcp/server/session.py -> ServerSession -> inherits from src/mcp/server/transport_session.py -> ServerTransportSession

Type Hints Fixes

Since ClientSession and ServerSession has a higher level abstraction so this PR also updates the type hints to the parent classes. Precisely - places where we use ClientSession are updated to use ClientTransportSession and similarly ServerSession type hints are updated to use ServerTransportSession.

How Has This Been Tested?

Tested using pyright and uv run pytest. Changes are also validated using CI runs.

Breaking Changes

No.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

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

Additional context

In future if we want to add more transports, those could implement abstract classes introduced in the PR which are - ClientTransportSesssion and ServerTransportSession.

[Kludex]

The session objects aren't transport specific, what problem are you trying to solve?

---

Why does this PR has so many "👍" ?

[asheshvidyut]

The session objects aren't transport specific, what problem are you trying to solve?

Why does this PR has so many "👍" ?

Hey @Kludex , Thanks for your reply.

Currently BaseSession, ServerSession and ClientSession are dependent on read write streams. If we want to add a gRPC Transport in a pluggable fashion, problem now is that we don't know what are the minimum APIs on Server and Client side which we need to implement to be fully compatible with MCP Specification.

Since gRPC Transport does not require read write streams, we have created abstract classes in this PR following interface segregation principle so that the abstract classes could be inherited by the current transport in this sdk as well as any future transport like gRPC.

This is part of modelcontextprotocol/modelcontextprotocol#1352 initiative.

Please let me know if I need to explain further. Thanks.

[Kludex]

[...] dependent on read write streams [...]

Yeah, I don't think there's any problem in that. Again, the session classes do not depend on any transport.

problem now is that we don't know what are the minimum APIs on Server and Client side which we need to implement to be fully compatible with MCP Specification.

The minimum is having the streams, check the stdio.py and websockets.py in this repository.

Since gRPC Transport does not require read write streams

Are you talking about what is implemented in: #1936 ? Streams are the same as queue, you do require queues in that PR, replace the asyncio.Queue by the streams.