Pluggable Transport Abstractions for Client and Shared sessions

[sreenithi]

This PR introduces abstract Protocol classes above the existing classes to help with pluggable transport. Two new Protocol classes are introduced - AbstractBaseSession and BaseClientSession.

AbstractBaseSession

AbstractBaseSession is a class above the existing BaseSession class in hierarchy. It is a structural protocol with no implementation state or __init__ method and just defines the contract that all session implementations must satisfy, irrespective of the transport used. State management and response routing now becomes the responsibility of the concrete implementations of this class, such as the Base session.
Hence the Generic types required for this Protocol are also limited to the ones needed by the methods in the Protocol - SendRequestT and SendNotificationT

BaseClientSession

BaseClientSession is a new Protocol defining the interface for MCP client sessions specifiying all methods that a client session must implement irrespective of the transport used.

To support these 2 new Protocols, the following types have been changed/introduced.

• SessionT has changed to be a covariant type bound to the AbstractBaseSession Protocol so that it can support both the existing BaseSession and any newer classes that inherit from AbstractBaseSession
• Similarly, a new contravariant type ClientSessionT_contra bound to the BaseClientSession is introduced.
• Types SendRequestT and SendNotificationT are changed to contravariant and renamed with *_contra to support its use in the AbstractBaseSession Protocol
• ReceiveResultT is also changed to be a covariant type and renamed to ReceiveResultT_co

Finally class definitions that used RequestContext[ClientSession] specifically such as SamplingFnT, ElicitationFnT, GetTaskHandlerFnT, etc. are now made to use the Generic[ClientSessionT_contra] type to allow other pluggable transport classes to comply with the BaseClientSession Protocol.

Motivation and Context

This PR introduces abstract classes and types to make it easier for users writing their own pluggable transports. This PR is the result of a discussion with the MCP core maintainers in December, where it was agreed that we would add a pluggable transport abstraction to the MCP SDKs. The current implementations assumes the use of JSON-RPC, and this PR aims to introduce abstractions to keep it transport and message type agnostic.

How Has This Been Tested?

All checks mentioned in the contributing guide (pytest, pyright and ruff) passes.

Breaking Changes

Classes like SamplingFnT, ElicitationFnT, GetTaskHandlerFnT, etc. have now been modified to use Generic types. So users, using these classes for type hints will need to mention the specific type like ElicitationFnT[ClientSession]

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

[Kludex]

How do we even use this abstraction? On the client side, it needs to be able to be used by the Client class somehow.

[sreenithi]

How do we even use this abstraction? On the client side, it needs to be able to be used by the Client class somehow.

The idea was to introduce the abstraction in the Sessions (ClientSession and BaseSession) so that any new clients with custom transports (possibly without read/write streams) can just implement the BaseClientSession via structural typing, it wouldn't have to use the existing Client and ClientSession classes.

And for the existing flow for clients using read/write streams, while the Client class is not directly using the abstraction, it uses the ClientSession which in turn would have the BaseClientSession structure.

If we want to make the Client class also use the abstractions directly, there might be some more changes needed, I'll update this PR accordingly.

[sreenithi]

@Kludex I looked into this, and because BaseClientSession is intended for custom sessions that don't rely on read-write streams or JSON-RPC, it isn't feasible to decouple the high-level Client class from ClientSession. The Client class inherently acts as a context manager that extracts streams from a Transport to instantiate the session, so using the transport agnostic BaseClientSession abstraction within the Client class definition doesn't make sense.

However, because the new callback protocols (SamplingFnT, ElicitationFnT, etc.) are defined with the contravariant TypeVar [ClientSessionT_contra], the type-checker inherently allows developers to inject abstract callbacks into the concrete Client.

I've added two new examples showing this:

1. custom_transport_client.py: How to implement a custom non-stream transport session using ONLY BaseClientSession.
2. client_example.py: How developers can write callbacks typed strictly against the generic BaseClientSession and still plug them natively into the existing Client.

Please let me know if this makes sense, or if you had a different expectation for how Client should interact with these abstractions!

[felixweinberger]

~~Hi @sreenithi thanks for submitting this! Just to clarify, is your goal here to:

1. Allow creation of new "pipes" through which JSON-RPC can be passed? E.g. we have Stdio and SHTTP currently, but you want to be able to build a Websocket pipe or gRPC pipe (while still sending JSON-RPC bytes through the wire).
2. Allow custom transports to use some message format other than JSON-RPC, say gRPC or Thrift directly?

My read of the blog post is that we want to allow 1, but not 2 (I could be wrong though). This PR seems to attempt implementation of 2, but I'm not sure hence double checking. The "Custom Transports" section of the spec also suggests JSON-RPC should be preserved even in custom-transports:

> Implementers who choose to support custom transports MUST ensure they preserve the JSON-RPC message format and lifecycle requirements defined by MCP.

Source: https://modelcontextprotocol.io/specification/draft/basic/transports#custom-transports

Edit: having looked through Discord it does look like 2 is what we're trying to achieve here. That does raise the question though of how this can be reflected in the spec, because how do we ensure that say gRPC conforms to the same MCP message types?

[maxisbey]

After taking a look through this PR I think there are better options for adding pluggable transports than the approach here.

Currently this just turns ClientSession into a Protocol, so if you were wanting to make a custom transport you'd then need to reimplement all the logic yourself, and you wouldn't be able to use anything from the SDK. I'd be keen to hear what your use case for this is? The only thing I can think of is if you have existing code which currently uses the ClientSession object, but you'd want to swap it out for your own full reimplementation without changing any of the type hints. Additionally this doesn't solve the server side, and still leaves us with needing JSONRPC.

The layers I see in the SDK:

• Client code - stuff that uses ClientSession
• Session Logic - The code handling how a call_tool works, or how .initialize() implements the initialization handshake and ClientCapabilities calculation
• Dispatching - this is the interface to the BaseSession class (basically your AbstractBaseSession)
• Wire Format - This is the actual building of (currently) JSONRPC requests/respones/notifications/errors
• Transport - The layer that handles SHTTP/SSE/STDIO

Currently, Session Logic, Dispatching, and Wire Format are all inside the same BaseSession/ClientSession class and tightly coupled, which makes any sort of abstraction of Wire Format incredibly difficult.

Now, if the goal of pluggable transports as currently written in the SDK was to keep JSONRPC and only change the transport, then there's no need to modify any of the Session classes, and instead just make a new Transport class. This is already supported in the SDK today, and anyone can do it, all you need to do is create a memory stream and pass it to the ClientSession class when you construct it.

But, that's obviously pretty jank, you'd then have to smuggle JSONRPC through gRPC or w/e.

So we're wanting to do both, we're wanting to be able to swap out both the Wire Format and the Transport. To do that I think the best path forward is to actually separate out those three layers (Session logic, Dispatching, and Wire Format), allowing you to replace the dispatching/wire format easily, without having to reimplement the entire SDK to do so.

I got Claude to draft up a PR here if you want to take a look at what I mean: #2320 (note this is definitely not ready to merge, more of a PoC to demonstrate the idea)

[maxisbey]

🔴 This unanchored pattern matches ... anywhere in a line — coverage.py uses re.search() for exclude_lines, so it will silently exclude executable lines like fn: Callable[..., Any] = Field(exclude=True) (tools/base.py:26), tuple[int, ...] annotations, and any string literal containing an ellipsis. It also makes the anchored pattern on the line above completely redundant.

To match the inline Protocol stubs in base_client_session.py (e.g. ) -> Any: ...), use an end-anchored pattern instead: ":\\s*\\.\\.\\.\\s*(#.*)?$".

Extended reasoning...

What the bug is

The TOML string "\\.\\.\\." decodes to the regex \.\.\., which matches three literal consecutive periods. Because coverage.py applies exclude_lines patterns using re.search() (not re.fullmatch()), this pattern matches anywhere in a line — not just lines that consist solely of ....

This is a strict superset of the existing pattern one line above ("^\\s*\\.\\.\\.\\s*$" → ^\s*\.\.\.\s*$), which correctly anchors to match only bare-ellipsis lines. The fact that the new pattern makes the old one dead code is itself a signal that the new pattern is broader than intended.

How it would be triggered

Any source line under src/ or tests/ (per [tool.coverage.run].source) that contains three consecutive dots — in any context — will be marked as excluded from coverage. No action is required to trigger it; the exclusion applies automatically on every coverage run.

Concretely, these patterns all match:

• Callable[..., Any] — variadic callable type hints
• tuple[int, ...] — variadic tuple type hints
• arr[..., 0] — NumPy-style ellipsis indexing
• raise ValueError("expected foo... got bar") — string literals
• logger.info("Processing...") — log messages
• # see the docs for more... — comments

Impact and blast radius

Verified real impact: src/mcp/server/mcpserver/tools/base.py:26 contains:

fn: Callable[..., Any] = Field(exclude=True)

This is executable code — a class-body assignment with a Field() call — and it will be silently dropped from the coverage report.

This repo enforces fail_under = 100 with branch = true and uses strict-no-cover to police pragma usage (per pyproject.toml and CLAUDE.md). This pattern is effectively a permanent, invisible # pragma: no cover applied to every line containing ..., which defeats that gate. Future code that should be covered can silently slip through, and the escape hatch won't be visible to reviewers because there's no pragma comment in the source.

Why it was added (and why it's too broad)

The new BaseClientSession Protocol in src/mcp/client/base_client_session.py uses inline stub bodies:

async def send_request(
    self,
    ...
) -> Any: ...

The existing ^\s*\.\.\.\s*$ pattern only matches standalone ... lines, so it misses ) -> Any: .... Commit 609778f ("resolve coverage failures") added this pattern to make those lines pass — but the fix didn't anchor.

Step-by-step proof

1. TOML decodes "\\.\\.\\." → Python string \.\.\. (each \\ → \).
2. As a regex, \.\.\. means "three literal dots" (each \. escapes a single .).
3. re.search(r"\.\.\.", "fn: Callable[..., Any] = Field(exclude=True)") → <re.Match object; span=(16, 19), match='...'> — matches.
4. Coverage.py's exclude_lines mechanism uses re.search, so any match anywhere excludes the whole line.
5. The line is dropped from coverage reporting despite being executable and unrelated to Protocol stubs.

Suggested fix

Replace the new pattern with one anchored to : ... at end-of-line (optionally followed by a comment):

 exclude_lines = [
     "pragma: no cover",
     "pragma: lax no cover",
     "if TYPE_CHECKING:",
     "@overload",
     "raise NotImplementedError",
     "^\\s*\\.\\.\\.\\s*$",
-    "\\.\\.\\.",
+    ":\\s*\\.\\.\\.\\s*(#.*)?$",
 ]

This matches ) -> Any: ..., ) -> None: ... # comment, and def foo(): ... while leaving Callable[..., Any], tuple[int, ...], and string literals covered.

On the refutation

One verifier noted bug_002 is a duplicate of bug_001. That's correct — they describe the same line and the same mechanism, which is why synthesis merged them. The refutation is procedural (deduplication), not a claim that the bug is invalid.

[maxisbey]

🔴 This crashes at runtime with AttributeError: 'InitializeResult' object has no attribute 'serverInfo' — must be init_result.server_info. MCPModel's populate_by_name=True allows construction via the camelCase alias (so line 27's serverInfo=... works), but Pydantic never creates attributes for aliases; attribute access is always via the Python field name.

CI didn't catch this because examples/pluggable_transport/ isn't in pyproject.toml's [tool.pyright].include list (only examples/servers, examples/snippets, examples/clients are). Adding it would also flag two smaller issues in client_example.py: result.content.text at L30 needs isinstance(..., TextContent) narrowing (content is a union — the same file does it correctly at L60), and the import from private mcp.shared._context at L10 should be from mcp.client import ClientRequestContext (which is literally RequestContext[BaseClientSession], exactly what L38 uses).

Extended reasoning...

The bug

examples/pluggable_transport/custom_transport_client.py:117 accesses init_result.serverInfo, but InitializeResult has no such attribute — the Python field name is server_info (defined at src/mcp/types/_types.py:569). Running this example raises AttributeError on the very first line after initialize() returns.

This is one of only two examples demonstrating the PR's headline feature (pluggable transport abstractions), and it crashes on first run.

Why the confusion exists

MCPModel is configured at src/mcp/types/_types.py:42 with:

model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)

This creates an asymmetry that's easy to miss:

• Construction accepts both the Python name (server_info=...) and the camelCase alias (serverInfo=...). That's what populate_by_name=True does.
• Attribute access is only via the Python name. Pydantic v2 has no mechanism to expose aliases as attributes — aliases exist solely for serialization and parsing.

So when line 27 writes serverInfo=types.Implementation(...) inside the InitializeResult(...) constructor, Pydantic happily accepts it, looks up the field by alias, and stores it under server_info. But when line 117 reads init_result.serverInfo, Python's normal attribute lookup runs — there's no serverInfo on the instance or class, so it raises.

For confirmation, this PR's own src/mcp/client/session_group.py correctly uses result.server_info when handling an InitializeResult.

Why CI passed

The PR description says "pyright passes" — and it does, but only because examples/pluggable_transport/ isn't in the type-checked surface. pyproject.toml's [tool.pyright].include list contains examples/servers, examples/snippets, and examples/clients, but not the new directory. Pyright would have flagged serverInfo immediately as an unknown attribute under strict mode.

Step-by-step proof

1. User runs python examples/pluggable_transport/custom_transport_client.py
2. main() calls interact_with_mcp(custom_session) (line 137)
3. Line 116: init_result = await session.initialize() → returns InitializeResult(protocol_version='2024-11-05', capabilities=..., server_info=Implementation(name='CustomDirectServer', version='1.0.0')). Note the stored field is server_info, even though it was constructed with serverInfo= at line 27.
4. Line 117: init_result.serverInfo → Python looks for serverInfo in __dict__, then on the class, finds nothing → AttributeError: 'InitializeResult' object has no attribute 'serverInfo'
5. Example crashes before listing tools or calling anything.

Two smaller issues in client_example.py (would also be caught by pyright)

Once the directory is added to pyright's include list, it will also flag:

L30 — result.content.text without narrowing. CreateMessageResult.content is TextContent | ImageContent | AudioContent; only TextContent has .text. This won't crash in this self-contained example (the callback at L45 always returns TextContent), but the same file correctly does isinstance(content, TextContent) at L60 — the internal inconsistency is what makes it a bad teaching example.

L10 — from mcp.shared._context import RequestContext imports from a private module (underscore prefix). The example then uses RequestContext[BaseClientSession] at L38 — but that is exactly what ClientRequestContext is (defined in this PR at src/mcp/client/context.py:6 and exported from mcp.client.__all__). The PR's own migration guide tells users to use ClientRequestContext; the example should too.

Suggested fix

--- a/examples/pluggable_transport/custom_transport_client.py
+++ b/examples/pluggable_transport/custom_transport_client.py
@@ -114,7 +114,7 @@ async def interact_with_mcp(session: BaseClientSession) -> None:
 
     # 1. Initialize
     init_result = await session.initialize()
-    print(f"Connected to: {init_result.serverInfo.name}@{init_result.serverInfo.version}")
+    print(f"Connected to: {init_result.server_info.name}@{init_result.server_info.version}")

--- a/examples/pluggable_transport/client_example.py
+++ b/examples/pluggable_transport/client_example.py
@@ -7,9 +7,8 @@ import asyncio
 
 from mcp import Client
-from mcp.client.base_client_session import BaseClientSession
+from mcp.client import ClientRequestContext
 from mcp.server.mcpserver import MCPServer
-from mcp.shared._context import RequestContext
 from mcp.types import (
     CreateMessageRequestParams,
     CreateMessageResult,
@@ -27,7 +26,9 @@ async def main():
         result = await server.get_context().session.create_message(
             messages=[{"role": "user", "content": {"type": "text", "text": message}}],
             max_tokens=100,
         )
-        return f"Assistant replied: {result.content.text}"
+        if isinstance(result.content, TextContent):
+            return f"Assistant replied: {result.content.text}"
+        return "Assistant replied with non-text content"
@@ -35,7 +36,7 @@ async def main():
     async def abstract_sampling_callback(
-        context: RequestContext[BaseClientSession], params: CreateMessageRequestParams
+        context: ClientRequestContext, params: CreateMessageRequestParams
     ) -> CreateMessageResult:

--- a/pyproject.toml
+++ b/pyproject.toml
@@ -106,6 +106,7 @@ include = [
     "examples/servers",
     "examples/snippets",
     "examples/clients",
+    "examples/pluggable_transport",
 ]

Alternatively, move both files under examples/clients/ which is already type-checked.

[maxisbey]

🟡 The first line of this "Before" block shows the new code — it's identical to line 939 in the "After" block. AbstractBaseSession didn't exist before this PR, so it can't appear in a "Before" example.

The actual pre-PR definition (from src/mcp/shared/_context.py) was:

SessionT = TypeVar("SessionT", bound=BaseSession[Any, Any, Any, Any, Any])

Lines 931-933 are correct; only this line needs fixing.

Extended reasoning...

What the bug is

In docs/migration.md, the "Internal TypeVars Renamed and Variance Updated" section provides a Before/After comparison to help users understand the TypeVar renames. However, the first line of the "Before" code block (line 930) is identical to the first line of the "After" code block (line 939):

# Line 930 (labeled "Before:")
SessionT_co = TypeVar("SessionT_co", bound="AbstractBaseSession[Any, Any]", covariant=True)

# Line 939 (labeled "After:")
SessionT_co = TypeVar("SessionT_co", bound="AbstractBaseSession[Any, Any]", covariant=True)

This is a copy-paste error. The other three lines in the "Before" block (SendRequestT, SendNotificationT, ReceiveResultT) correctly show the old definitions — only the SessionT line is wrong.

Why it's definitely wrong

The "Before" block references AbstractBaseSession, but that class is introduced by this very PR — it does not exist in the pre-PR codebase. The diff of src/mcp/shared/_context.py shows the actual change:

-from mcp.shared.session import BaseSession
+if TYPE_CHECKING:
+    from mcp.shared.session import AbstractBaseSession
 ...
-SessionT = TypeVar("SessionT", bound=BaseSession[Any, Any, Any, Any, Any])
+SessionT_co = TypeVar("SessionT_co", bound="AbstractBaseSession[Any, Any]", covariant=True)

Additionally, the table directly above the code block (line 922) correctly states SessionT → SessionT_co, which contradicts the code example showing SessionT_co on both sides.

Step-by-step proof

1. A user reads the table at line 922: "Original Name: SessionT → Updated Name: SessionT_co"
2. They scroll down to the "Before:" code block to see the old definition
3. Line 930 shows SessionT_co with covariant=True and bound="AbstractBaseSession[Any, Any]"
4. They scroll to "After:" — line 939 is identical
5. The user is now confused: the table says the name changed, but the code shows the same thing on both sides. They also have no way to see that the bound changed from BaseSession[Any, Any, Any, Any, Any] to AbstractBaseSession[Any, Any], or that variance was added.

Impact

This is a documentation error in a migration guide for a breaking change. Users migrating code that referenced SessionT cannot use this section to understand:

• What the old name was (SessionT, not SessionT_co)
• What the old bound was (BaseSession[Any, Any, Any, Any, Any], not AbstractBaseSession[Any, Any])
• That variance was added (there was no covariant=True before)

The impact is partially mitigated because the table at line 922 correctly documents the rename, so careful readers won't be completely lost — but the code example directly contradicts it, which is confusing.

Suggested fix

 **Before:**

 ```python
-SessionT_co = TypeVar("SessionT_co", bound="AbstractBaseSession[Any, Any]", covariant=True)
+SessionT = TypeVar("SessionT", bound=BaseSession[Any, Any, Any, Any, Any])
 SendRequestT = TypeVar("SendRequestT", ClientRequest, ServerRequest)
 SendNotificationT = TypeVar("SendNotificationT", ClientNotification, ServerNotification)
 ReceiveResultT = TypeVar("ReceiveResultT", bound=BaseModel)

</details>
<!-- bughunter:bug_ids=bug_005 -->

[maxisbey]

🟡 covariant=True is meaningless here — ReceiveResultT_co is not in any class's Generic[...] list (neither AbstractBaseSession nor BaseSession includes it). It's only used method-scoped in send_request(result_type: type[T]) -> T, where each call binds independently and there's no subtyping relation for variance to govern.

The other renames (SendRequestT_contra, SendNotificationT_contra) are in AbstractBaseSession's Generic[...] so their variance is meaningful — this one was likely renamed by pattern-matching. Suggest reverting to ReceiveResultT (no variance, no _co suffix) and dropping the migration.md table row that documents "Covariant" semantics that don't exist.

Extended reasoning...

What the bug is

The PR renames ReceiveResultT → ReceiveResultT_co and adds covariant=True:

# src/mcp/shared/session.py:44
ReceiveResultT_co = TypeVar("ReceiveResultT_co", bound=BaseModel, covariant=True)

However, ReceiveResultT_co never appears in any class's Generic[...] parameter list. Checking both Generic declarations in the file:

• AbstractBaseSession(Protocol, Generic[SendRequestT_contra, SendNotificationT_contra]) — 2 params, ReceiveResultT_co absent
• BaseSession(..., Generic[SendRequestT_contra, SendNotificationT_contra, SendResultT, ReceiveRequestT, ReceiveNotificationT]) — 5 params, ReceiveResultT_co absent

It only appears inside the send_request method signature (in both AbstractBaseSession and BaseSession):

async def send_request(
    self,
    request: SendRequestT_contra,
    result_type: type[ReceiveResultT_co],   # method-local binding
    ...
) -> ReceiveResultT_co:

Per PEP 484, variance annotations (covariant=True / contravariant=True) only have meaning on TypeVars that parameterize a generic class. Variance governs how Foo[Subtype] relates to Foo[Supertype] — it's a property of the class under subtyping. A TypeVar that's only used inside a single method signature is function-scoped: each call to send_request binds it independently, and there is no inter-call subtyping relation for variance to govern. The covariant=True here is a semantic no-op.

Why this happened — contrast with the correct renames

The same diff hunk renames three TypeVars together, but they are not equivalent:

TypeVar	In a Generic[...] list?	Variance meaningful?
SendRequestT_contra	✅ AbstractBaseSession[SendRequestT_contra, ...]	✅ Yes — governs Protocol subtyping
SendNotificationT_contra	✅ AbstractBaseSession[..., SendNotificationT_contra]	✅ Yes — governs Protocol subtyping
ReceiveResultT_co	❌ Method-scoped only	❌ No — no subtyping relation to govern

The first two renames are correct and necessary — contravariance on input-position TypeVars is what makes the Protocol's structural subtyping sound. ReceiveResultT was renamed by pattern-matching without recognizing that it's fundamentally different: it's a per-method generic (like the T in list.index(x: T)), not a per-class generic.

Step-by-step proof

Consider what covariance would mean if it applied here:

1. ReceiveResultT_co is covariant → for some generic G, G[Child] should be a subtype of G[Parent]
2. But there is no such G — ReceiveResultT_co doesn't parameterize any class
3. The only binding site is send_request. Call 1: send_request(req, CallToolResult) binds T = CallToolResult. Call 2: send_request(req, ListToolsResult) binds T = ListToolsResult.
4. These two calls don't have a subtyping relationship with each other — they're independent invocations. There's no "send_request[Child] is-a send_request[Parent]" relation for covariance to describe.
5. Type checkers (pyright, mypy) recognize this and silently ignore the variance annotation.

Concretely: if you delete covariant=True from line 44, zero observable behavior changes — not at runtime, not in pyright, not in mypy. The annotation is dead code.

Impact

• No runtime impact — TypeVar variance is erased at runtime regardless.
• No CI failure — pyright silently ignores variance on function-scoped TypeVars (which is why CI passes).
• No mypy hard error (correcting the original finding's claim) — mypy's Cannot use a covariant type variable as a parameter error fires for class-scoped covariant TypeVars used in input positions. For purely function-scoped TypeVars, mypy also ignores the variance as a no-op. This is a latent correctness issue, not a build break.
• Misleading documentation — the migration.md table row ("ReceiveResultT → ReceiveResultT_co | Covariant | Handles successful response models safely") documents semantics that don't exist. In a PR whose explicit purpose is to get Protocol variance right, shipping a meaningless variance annotation plus a docs row claiming it "handles response models safely" is the kind of thing that misleads future contributors.
• Misleading naming — the _co suffix (per PEP 484 convention) promises covariance to anyone reading the code.

Suggested fix

Revert the rename and drop the annotation (three-line logical change, ~6 physical lines):

--- a/src/mcp/shared/session.py
+++ b/src/mcp/shared/session.py
@@ -44 +44 @@
-ReceiveResultT_co = TypeVar("ReceiveResultT_co", bound=BaseModel, covariant=True)
+ReceiveResultT = TypeVar("ReceiveResultT", bound=BaseModel)

Then s/ReceiveResultT_co/ReceiveResultT/ at the four usage sites in send_request signatures (two in AbstractBaseSession, two in BaseSession), and remove the ReceiveResultT row from the migration.md TypeVar table.

[maxisbey]

🟡 This imports BaseClientSession from the mcp.client package rather than directly from the module, creating a circular dependency on __init__.py import ordering — it only works because base_client_session is imported on line 4 before context on line 6.

Ruff's isort keeps this safe alphabetically so it won't break accidentally, but it's inconsistent with session.py and task_handlers.py in this same PR, which both use from mcp.client.base_client_session import BaseClientSession. The pre-PR code also used a direct module import here. Suggest matching the other files.

Extended reasoning...

What the bug is

src/mcp/client/context.py:3 imports BaseClientSession from the mcp.client package namespace rather than directly from the mcp.client.base_client_session submodule:

from mcp.client import BaseClientSession

This creates a circular import dependency on the statement ordering inside mcp/client/__init__.py. Both session.py and task_handlers.py in this same PR use the direct-module pattern instead — only context.py deviates. The pre-PR code also used a direct module import (from mcp.client.session import ClientSession).

The code path that triggers it

Walking through what happens when mcp.client is first imported:

1. Python begins executing mcp/client/__init__.py. The mcp.client module object is created and added to sys.modules, but its namespace is empty.
2. Line 3 — from mcp.client._transport import Transport executes; Transport is bound in the partial mcp.client namespace.
3. Line 4 — from mcp.client.base_client_session import BaseClientSession executes; BaseClientSession is now bound in the partial mcp.client namespace.
4. Line 5 — from mcp.client.client import Client executes.
5. Line 6 — from mcp.client.context import ClientRequestContext begins. Python loads context.py.
6. Inside context.py, line 3 runs: from mcp.client import BaseClientSession. Python finds mcp.client already in sys.modules (partially initialized) and looks up BaseClientSession in its namespace. This succeeds only because step 3 already bound it.
7. context.py finishes loading, __init__.py resumes at line 7.

If line 6 of __init__.py were ever moved above line 4, step 6 would fail with ImportError: cannot import name 'BaseClientSession' from partially initialized module 'mcp.client' (most likely due to a circular import).

Impact and blast radius

Low practical risk. The original finding's threat model ("a linter reorders them") is somewhat overstated: pyproject.toml enables ruff's I (isort) rule, which enforces alphabetical ordering within first-party import groups. Since base_client_session sorts before context alphabetically, the linter actively protects the current ordering rather than threatening it. The failure mode would require a manual edit that bypasses pre-commit hooks.

The real cost is inconsistency. This is the only file in the PR that imports BaseClientSession via the package. Compare:

File	Import pattern
session.py:11	from mcp.client.base_client_session import BaseClientSession, ClientSessionT_contra
task_handlers.py:22	from mcp.client.base_client_session import BaseClientSession, ClientSessionT_contra
session_group.py:23	from mcp.client.base_client_session import ClientSessionT_contra
context.py:3	from mcp.client import BaseClientSession ← deviates

The pre-PR context.py used from mcp.client.session import ClientSession (direct module import), so the package-level import is a new pattern introduced by this change, not pre-existing.

Suggested fix

-from mcp.client import BaseClientSession
+from mcp.client.base_client_session import BaseClientSession

This matches every other file in the PR, removes the ordering dependency entirely, and restores the direct-module-import pattern the pre-PR code used. Zero behavioral change.

Addressing verifier objections

The single refutation noted that bug_009 duplicates bug_004 (same file, line, issue, fix). This is correct — the synthesis agent merged them into this single report. It is not a refutation of the finding itself.

[maxisbey]

🟡 The comment on line 21 says these methods are "from AbstractBaseSession", but the redeclarations drop type information that AbstractBaseSession correctly carries:

• send_request uses result_type: type → Any instead of type[ReceiveResultT_co] → ReceiveResultT_co, so code typed against BaseClientSession gets Any back and loses all result type safety
• send_notification uses related_request_id: Any instead of RequestId | None (where RequestId = str | int)

AbstractBaseSession proves the method-scoped-TypeVar pattern works in a @runtime_checkable Protocol (ReceiveResultT_co isn't in its Generic[...] params), and RequestId is already importable from the same module as ProgressFnT on line 6. Also — the comment on line 88 (# Missing methods added per review) is a PR-review-cycle artifact that should be deleted.

Extended reasoning...

What the bug is

BaseClientSession is a new @runtime_checkable Protocol introduced so users can write code typed against an abstract client session rather than the concrete ClientSession. The comment at base_client_session.py:21 states these methods are redeclared from AbstractBaseSession — but the redeclarations are weaker than the source they're mirroring:

Parameter	BaseClientSession (this file)	AbstractBaseSession (session.py:178–198)
send_request → result_type	type	type[ReceiveResultT_co]
send_request → return	Any	ReceiveResultT_co
send_request → metadata	Any	MessageMetadata
send_notification → related_request_id	Any	RequestId | None

There is no technical barrier here. AbstractBaseSession is itself a @runtime_checkable Protocol, and ReceiveResultT_co is not in its Generic[SendRequestT_contra, SendNotificationT_contra] params — it functions as a method-scoped TypeVar. So this same PR has already demonstrated the pattern works.

Separately, line 88 contains # Missing methods added per review, a leftover from commit d0b11ad's review cycle. Contrast with the other section headers in this file (# Methods from AbstractBaseSession..., # Client-specific methods) which describe what the methods are — this one only describes when they were added during development.

How this gets triggered

Any code that accepts a BaseClientSession (which is the entire point of introducing this Protocol) and calls send_request directly hits the Any hole. The PR's own example, custom_transport_client.py, encourages writing functions typed as async def interact_with_mcp(session: BaseClientSession). The moment someone calls session.send_request(...) inside such a function, the contagion starts.

Custom implementers are the second audience: when someone writes a BaseClientSession implementation, pyright will accept any return type for send_request and any argument type for related_request_id, because Any matches everything.

Impact and blast radius

This causes silent type erasure, not runtime failures. Two concrete harms:

1. Callers lose result typing. await session.send_request(req, types.CallToolResult) returns Any, so every downstream .content, .is_error, etc. is unchecked. Any is contagious — it propagates through the caller's code silently.
2. Implementers get no guidance. Someone implementing BaseClientSession in their own transport won't be told by pyright that send_request must return an instance of result_type, or that related_request_id must be str | int | None.

The blast radius is bounded by the fact that most users will call the properly-typed high-level methods (call_tool() -> CallToolResult, list_tools() -> ListToolsResult, etc.), which are correct in this Protocol. send_request is the low-level escape hatch. But since this is a brand-new public API, tightening it later would technically be a breaking change — better to ship it right.

Step-by-step proof

Walk through what pyright sees when code is typed against BaseClientSession:

from mcp.client import BaseClientSession
from mcp import types

async def fetch_tools(session: BaseClientSession) -> list[types.Tool]:
    # session is BaseClientSession, so pyright uses the Protocol's signature:
    #   async def send_request(self, request, result_type: type, ...) -> Any

    result = await session.send_request(
        types.ListToolsRequest(params=None),
        types.ListToolsResult,       # accepted: `type` matches anything
    )
    # reveal_type(result) → Any     ← relationship to ListToolsResult LOST

    return result.tooools            # typo! pyright: no error, Any.anything is Any

Now the same code against AbstractBaseSession (same PR, session.py:178–185):

# signature: result_type: type[ReceiveResultT_co] -> ReceiveResultT_co
# pyright binds ReceiveResultT_co = ListToolsResult
# reveal_type(result) → ListToolsResult
# result.tooools → error: "tooools" is not a known attribute of "ListToolsResult"

And for related_request_id:

async def notify(session: BaseClientSession) -> None:
    await session.send_notification(
        types.InitializedNotification(),
        related_request_id={"oops": "a dict"},   # Any accepts this silently
    )
# With RequestId | None: error — dict is not assignable to str | int | None

Suggested fix

No import barriers exist: line 6 already imports ProgressFnT from mcp.shared.session, and RequestId lives in the same module.

--- a/src/mcp/client/base_client_session.py
+++ b/src/mcp/client/base_client_session.py
@@ -1,11 +1,14 @@
 from typing import Any, TypeVar
 
+from pydantic import BaseModel
 from typing_extensions import Protocol, runtime_checkable
 
 from mcp import types
-from mcp.shared.session import ProgressFnT
+from mcp.shared.session import ProgressFnT, RequestId
 from mcp.types._types import RequestParamsMeta
 
+_ResultT = TypeVar("_ResultT", bound=BaseModel)
+
 ClientSessionT_contra = TypeVar("ClientSessionT_contra", bound="BaseClientSession", contravariant=True)
 
 
@@ -22,16 +25,16 @@ class BaseClientSession(Protocol):
     async def send_request(
         self,
         request: types.ClientRequest,
-        result_type: type,
+        result_type: type[_ResultT],
         request_read_timeout_seconds: float | None = None,
         metadata: Any = None,
         progress_callback: ProgressFnT | None = None,
-    ) -> Any: ...
+    ) -> _ResultT: ...
 
     async def send_notification(
         self,
         notification: types.ClientNotification,
-        related_request_id: Any = None,
+        related_request_id: RequestId | None = None,
     ) -> None: ...
@@ -85,7 +88,6 @@ class BaseClientSession(Protocol):
 
     async def list_tools(self, *, params: types.PaginatedRequestParams | None = None) -> types.ListToolsResult: ...
 
-    # Missing methods added per review
     async def complete(

Note on metadata: Any (line 27): AbstractBaseSession uses MessageMetadata here, but MessageMetadata is JSON-RPC-coupled (from mcp.shared.message), so keeping it Any may be an intentional transport-agnostic choice. related_request_id: Any has no such excuse — RequestId = str | int is a protocol-level MCP concept independent of transport. I've left metadata unchanged in the diff above; adjust if the Any was not intentional.