Correct framing: httpx2 is on PyPI; CI exercises the fallback because the lockfile pins httpx

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dsfaccini

pyproject.toml

@@ -206,10 +206,11 @@ filterwarnings = [
     "ignore:websockets.server.WebSocketServerProtocol is deprecated:DeprecationWarning",
     # pywin32 internal deprecation warning
     "ignore:getargs.*The 'u' format is deprecated:DeprecationWarning",
-    # `mcp` prefers `httpx2`; HTTP surfaces warn when falling back to `httpx`. `httpx2` is
-    # not yet on PyPI, so every HTTP-touching test would trip the warning. The dedicated
-    # test in `tests/shared/test_httpx_shim.py` covers emission. Remove this entry once
-    # `httpx2` is the default and the fallback is dropped.
+    # `mcp` prefers `httpx2`; HTTP surfaces warn when falling back to `httpx`. The lockfile
+    # pins `httpx` (not `httpx2`), so CI always exercises the fallback and every HTTP-touching
+    # test would trip the warning. The dedicated test in `tests/shared/test_httpx_shim.py`
+    # covers emission. Remove this entry once `httpx2` is the dependency and the fallback is
+    # dropped.
     "ignore:Using `httpx` with `mcp` is deprecated:mcp.shared._httpx.MCPDeprecationWarning",
 ]
 

src/mcp/shared/_httpx.py

@@ -4,9 +4,10 @@
 [Kludex/starlette@508023b](https://github.com/Kludex/starlette/commit/508023b488b649d97c091eb60da1d8ef3636ee06)
 and [pydantic/pydantic-ai#5664](https://github.com/pydantic/pydantic-ai/pull/5664).
 
-`httpx2` is not yet on PyPI, so every install today exercises the fallback path. The warning
-is emitted lazily on first use (not at module import) to avoid breaking pytest's filter
-parser during collection. The MCP v2 cut will drop the fallback and require `httpx2`.
+`mcp` declares `httpx` (not `httpx2`) as a dependency, so unless the user installs `httpx2`
+explicitly the fallback path is exercised. The warning is emitted lazily on first use (not at
+module import) to avoid breaking pytest's filter parser during collection. The MCP v2 cut will
+drop the fallback and bump the dependency to `httpx2`.
 """
 
 from __future__ import annotations

tests/shared/test_httpx_shim.py

@@ -70,8 +70,9 @@ async def test_create_mcp_http_client_silent_with_httpx2(
 def test_shim_picks_up_httpx2_when_present(monkeypatch: pytest.MonkeyPatch) -> None:
     """Aliasing `httpx2` to the installed `httpx` module exercises the preferred import path.
 
-    Without this test, the `import httpx2 as httpx` branch is uncovered (since `httpx2` is not
-    yet on PyPI). Once `httpx2` is real, this test will continue to pass naturally.
+    `mcp`'s lockfile pins `httpx` (not `httpx2`), so the `import httpx2 as httpx` branch is
+    otherwise uncovered in CI. This test injects `httpx2` into `sys.modules` and reloads the
+    shim to cover that branch deterministically.
     """
     import importlib
     import sys