Simplify shim per @Kludex: emit warning at module import, drop the lazy helper

Module-level `warnings.warn(...)` inside the `except ImportError` branch fires once per
process via Python's module cache — no flag or helper function needed. `MCPDeprecationWarning`
moves to `mcp.shared._warnings` so the class symbol exists independently of the shim, and the
pytest `filterwarnings` entry matches on the message string only. Naming the category would
force pytest's filter parser to import `mcp.shared._warnings`, which cascades through
`mcp/__init__.py` and triggers the very warning we're filtering (the pydantic-ai pitfall).

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

Author: dsfaccini

pyproject.toml

@@ -206,12 +206,14 @@ 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`. 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",
+    # `mcp` prefers `httpx2`; importing `mcp.shared._httpx` warns when falling back to
+    # `httpx`. The lockfile pins `httpx`, so CI always exercises the fallback. We match on
+    # the message string only — naming the category would force pytest to import
+    # `mcp.shared._warnings`, which cascades through `mcp/__init__.py` and triggers the
+    # very warning we're trying to filter (the same trap pydantic-ai documents). 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",
 ]
 
 [tool.markdown.lint]

src/mcp/client/auth/oauth2.py

@@ -36,7 +36,7 @@
     should_use_client_metadata_url,
 )
 from mcp.client.streamable_http import MCP_PROTOCOL_VERSION
-from mcp.shared._httpx import emit_httpx_deprecation_warning, httpx
+from mcp.shared._httpx import httpx
 from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthClientMetadata,
@@ -255,8 +255,6 @@ def __init__(
             ValueError: If client_metadata_url is provided but not a valid HTTPS URL
                 with a non-root pathname.
         """
-        emit_httpx_deprecation_warning()
-
         # Validate client_metadata_url if provided
         if client_metadata_url is not None and not is_valid_client_metadata_url(client_metadata_url):
             raise ValueError(

src/mcp/server/mcpserver/resources/types.py

@@ -15,7 +15,7 @@
 
 from mcp.server.mcpserver.resources.base import Resource
 from mcp.shared._callable_inspection import is_async_callable
-from mcp.shared._httpx import emit_httpx_deprecation_warning, httpx
+from mcp.shared._httpx import httpx
 from mcp.types import Annotations, Icon
 
 
@@ -159,7 +159,6 @@ class HttpResource(Resource):
 
     async def read(self) -> str | bytes:
         """Read the HTTP content."""
-        emit_httpx_deprecation_warning()  # pragma: no cover
         async with httpx.AsyncClient() as client:  # pragma: no cover
             response = await client.get(self.url)
             response.raise_for_status()

src/mcp/shared/_httpx.py

@@ -5,52 +5,34 @@
 and [pydantic/pydantic-ai#5664](https://github.com/pydantic/pydantic-ai/pull/5664).
 
 `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`.
+explicitly the fallback path is exercised. The MCP v2 cut will drop the fallback and bump the
+dependency to `httpx2`.
+
+The warning is emitted at module-import time and fires at most once per process via Python's
+module cache. `MCPDeprecationWarning` lives in `mcp.shared._warnings` so pytest's
+`filterwarnings` parser can resolve the category symbol without importing this shim.
 """
 
 from __future__ import annotations
 
 import warnings
 from typing import TYPE_CHECKING
 
-__all__ = ["MCPDeprecationWarning", "emit_httpx_deprecation_warning", "httpx"]
-
-
-class MCPDeprecationWarning(UserWarning):
-    """Deprecation warning emitted by the `mcp` package.
+from mcp.shared._warnings import MCPDeprecationWarning
 
-    Subclasses `UserWarning` (not `DeprecationWarning`) so it is visible by default —
-    `DeprecationWarning` is silenced at the Python level for non-`__main__` callers.
-    """
+__all__ = ["MCPDeprecationWarning", "httpx"]
 
 
 if TYPE_CHECKING:
     import httpx as httpx
-
-    _HTTPX_IS_DEPRECATED = False
 else:
     try:
         import httpx2 as httpx
-
-        _HTTPX_IS_DEPRECATED = False
     except ImportError:
         import httpx
 
-        _HTTPX_IS_DEPRECATED = True
-
-
-_warning_emitted = False
-
-
-def emit_httpx_deprecation_warning() -> None:
-    """Emit the `httpx` → `httpx2` deprecation warning at most once per process."""
-    global _warning_emitted
-    if _HTTPX_IS_DEPRECATED and not _warning_emitted:
-        _warning_emitted = True
         warnings.warn(
             "Using `httpx` with `mcp` is deprecated; install `httpx2` instead.",
             MCPDeprecationWarning,
-            stacklevel=3,
+            stacklevel=2,
         )

src/mcp/shared/_httpx_utils.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Protocol
 
-from mcp.shared._httpx import emit_httpx_deprecation_warning, httpx
+from mcp.shared._httpx import httpx
 
 __all__ = ["create_mcp_http_client", "MCP_DEFAULT_TIMEOUT", "MCP_DEFAULT_SSE_READ_TIMEOUT"]
 
@@ -77,8 +77,6 @@ def create_mcp_http_client(
             response = await client.get("/protected-endpoint")
         ```
     """
-    emit_httpx_deprecation_warning()
-
     # Set MCP defaults
     kwargs: dict[str, Any] = {"follow_redirects": True}
 

src/mcp/shared/_warnings.py

@@ -0,0 +1,19 @@
+"""Warning categories emitted by the `mcp` package."""
+
+from __future__ import annotations
+
+__all__ = ["MCPDeprecationWarning"]
+
+
+class MCPDeprecationWarning(UserWarning):
+    """Deprecation warning emitted by the `mcp` package.
+
+    Subclasses `UserWarning` (not `DeprecationWarning`) so it is visible by default —
+    `DeprecationWarning` is silenced at the Python level for non-`__main__` callers.
+
+    Defined in its own module so that pytest's `filterwarnings` parser can resolve the
+    category symbol without importing any side-effecting module — e.g.
+    `mcp.shared._httpx` emits a `MCPDeprecationWarning` at import time when only `httpx`
+    is installed, and resolving the symbol through that module would fire the warning
+    before pytest finishes registering the filter.
+    """

tests/shared/test_httpx_shim.py

@@ -1,91 +1,61 @@
 """Tests for the `httpx` → `httpx2` migration shim in `mcp.shared._httpx`.
 
-`mcp` prefers `httpx2` and falls back to `httpx` with an `MCPDeprecationWarning`. The
-fallback is exercised when only `httpx` is installed (today this is always — `httpx2` is
-not yet on PyPI). The warning is emitted once per process from HTTP-touching surfaces.
+`mcp` prefers `httpx2` and falls back to `httpx` with an `MCPDeprecationWarning` emitted at
+the shim's import time. Today the lockfile pins `httpx` (not `httpx2`), so importing the shim
+exercises the fallback.
 """
 
 from __future__ import annotations
 
+import importlib
+import sys
 import warnings
 
 import pytest
 
-from mcp.shared import _httpx as httpx_shim
-from mcp.shared._httpx import MCPDeprecationWarning, emit_httpx_deprecation_warning
-from mcp.shared._httpx_utils import create_mcp_http_client
+from mcp.shared._warnings import MCPDeprecationWarning
 
-pytestmark = pytest.mark.anyio
 
+def _force_reimport_shim() -> None:
+    """Drop the cached shim module so the next import re-runs its top-level code."""
+    sys.modules.pop("mcp.shared._httpx", None)
 
-@pytest.fixture
-def reset_warning_flag(monkeypatch: pytest.MonkeyPatch):
-    """Reset the once-per-process flag so each test gets a fresh emission state."""
-    monkeypatch.setattr(httpx_shim, "_warning_emitted", False)
 
+def test_fallback_emits_warning_at_import(monkeypatch: pytest.MonkeyPatch) -> None:
+    """With only `httpx` installed, importing the shim emits `MCPDeprecationWarning`."""
+    monkeypatch.delitem(sys.modules, "httpx2", raising=False)
+    _force_reimport_shim()
 
-def test_emit_warns_when_httpx_is_deprecated(monkeypatch: pytest.MonkeyPatch, reset_warning_flag: None) -> None:
-    monkeypatch.setattr(httpx_shim, "_HTTPX_IS_DEPRECATED", True)
-    with pytest.warns(MCPDeprecationWarning, match=r"install `httpx2` instead"):
-        emit_httpx_deprecation_warning()
-
-
-def test_emit_silent_when_httpx2_is_used(monkeypatch: pytest.MonkeyPatch, reset_warning_flag: None) -> None:
-    monkeypatch.setattr(httpx_shim, "_HTTPX_IS_DEPRECATED", False)
-    with warnings.catch_warnings(record=True) as caught:
-        warnings.simplefilter("always", MCPDeprecationWarning)
-        emit_httpx_deprecation_warning()
-    assert [w for w in caught if issubclass(w.category, MCPDeprecationWarning)] == []
+    from collections.abc import Mapping, Sequence
 
+    real_import = __import__
 
-def test_emit_only_warns_once_per_process(monkeypatch: pytest.MonkeyPatch, reset_warning_flag: None) -> None:
-    monkeypatch.setattr(httpx_shim, "_HTTPX_IS_DEPRECATED", True)
-    with warnings.catch_warnings(record=True) as caught:
-        warnings.simplefilter("always", MCPDeprecationWarning)
-        emit_httpx_deprecation_warning()
-        emit_httpx_deprecation_warning()
-        emit_httpx_deprecation_warning()
-    matching = [w for w in caught if issubclass(w.category, MCPDeprecationWarning)]
-    assert len(matching) == 1
-
+    def fake_import(
+        name: str,
+        globals: Mapping[str, object] | None = None,
+        locals: Mapping[str, object] | None = None,
+        fromlist: Sequence[str] = (),
+        level: int = 0,
+    ) -> object:
+        if name == "httpx2":
+            raise ImportError("simulated: httpx2 not installed")
+        return real_import(name, globals, locals, fromlist, level)
 
-async def test_create_mcp_http_client_emits_warning(monkeypatch: pytest.MonkeyPatch, reset_warning_flag: None) -> None:
-    monkeypatch.setattr(httpx_shim, "_HTTPX_IS_DEPRECATED", True)
+    monkeypatch.setattr("builtins.__import__", fake_import)
     with pytest.warns(MCPDeprecationWarning, match=r"install `httpx2` instead"):
-        async with create_mcp_http_client():
-            pass
-
-
-async def test_create_mcp_http_client_silent_with_httpx2(
-    monkeypatch: pytest.MonkeyPatch, reset_warning_flag: None
-) -> None:
-    monkeypatch.setattr(httpx_shim, "_HTTPX_IS_DEPRECATED", False)
-    with warnings.catch_warnings(record=True) as caught:
-        warnings.simplefilter("always", MCPDeprecationWarning)
-        async with create_mcp_http_client():
-            pass
-    assert [w for w in caught if issubclass(w.category, MCPDeprecationWarning)] == []
-
-
-def test_shim_picks_up_httpx2_when_present(monkeypatch: pytest.MonkeyPatch) -> None:
-    """Aliasing `httpx2` to the installed `httpx` module exercises the preferred import path.
+        importlib.import_module("mcp.shared._httpx")
 
-    `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
 
+def test_httpx2_present_is_silent(monkeypatch: pytest.MonkeyPatch) -> None:
+    """When `httpx2` is importable, the shim selects it and emits no warning."""
     import httpx as real_httpx
 
     monkeypatch.setitem(sys.modules, "httpx2", real_httpx)
-    monkeypatch.delitem(sys.modules, "mcp.shared._httpx", raising=False)
-    try:
+    _force_reimport_shim()
+
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always", MCPDeprecationWarning)
         reloaded = importlib.import_module("mcp.shared._httpx")
-        assert reloaded._HTTPX_IS_DEPRECATED is False
-        assert reloaded.httpx is real_httpx
-    finally:
-        # Restore the canonical shim module so subsequent tests see the real state.
-        sys.modules.pop("mcp.shared._httpx", None)
-        importlib.import_module("mcp.shared._httpx")
+
+    assert reloaded.httpx is real_httpx
+    assert [w for w in caught if issubclass(w.category, MCPDeprecationWarning)] == []