Deprecate httpx in favor of httpx2

Mirrors Kludex/starlette@508023b and pydantic/pydantic-ai#5664: prefer
`httpx2` at import time and fall back to `httpx` with an
`MCPDeprecationWarning` emitted lazily on first use of an HTTP-touching
surface (`create_mcp_http_client`, `OAuthClientProvider`, `HttpResource`).
The v2-cut PR will drop the fallback.

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

Author: dsfaccini

pyproject.toml

@@ -206,6 +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.
+    "ignore:Using `httpx` with `mcp` is deprecated:mcp.shared._httpx.MCPDeprecationWarning",
 ]
 
 [tool.markdown.lint]

src/mcp/client/auth/extensions/client_credentials.py

@@ -13,11 +13,11 @@
 from typing import Any, Literal
 from uuid import uuid4
 
-import httpx
 import jwt
 from pydantic import BaseModel, Field
 
 from mcp.client.auth import OAuthClientProvider, OAuthFlowError, OAuthTokenError, TokenStorage
+from mcp.shared._httpx import httpx
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata
 
 

src/mcp/client/auth/oauth2.py

@@ -15,7 +15,6 @@
 from urllib.parse import quote, urlencode, urljoin, urlparse
 
 import anyio
-import httpx
 from pydantic import BaseModel, Field, ValidationError
 
 from mcp.client.auth.exceptions import OAuthFlowError, OAuthTokenError
@@ -37,6 +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.auth import (
     OAuthClientInformationFull,
     OAuthClientMetadata,
@@ -255,6 +255,8 @@ 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/client/auth/utils.py

@@ -1,11 +1,11 @@
 import re
 from urllib.parse import urljoin, urlparse
 
-from httpx import Request, Response
 from pydantic import AnyUrl, ValidationError
 
 from mcp.client.auth import OAuthRegistrationError, OAuthTokenError
 from mcp.client.streamable_http import MCP_PROTOCOL_VERSION
+from mcp.shared._httpx import httpx
 from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthClientMetadata,
@@ -16,7 +16,7 @@
 from mcp.types import LATEST_PROTOCOL_VERSION
 
 
-def extract_field_from_www_auth(response: Response, field_name: str) -> str | None:
+def extract_field_from_www_auth(response: httpx.Response, field_name: str) -> str | None:
     """Extract field from WWW-Authenticate header.
 
     Returns:
@@ -37,7 +37,7 @@ def extract_field_from_www_auth(response: Response, field_name: str) -> str | No
     return None
 
 
-def extract_scope_from_www_auth(response: Response) -> str | None:
+def extract_scope_from_www_auth(response: httpx.Response) -> str | None:
     """Extract scope parameter from WWW-Authenticate header as per RFC 6750.
 
     Returns:
@@ -46,7 +46,7 @@ def extract_scope_from_www_auth(response: Response) -> str | None:
     return extract_field_from_www_auth(response, "scope")
 
 
-def extract_resource_metadata_from_www_auth(response: Response) -> str | None:
+def extract_resource_metadata_from_www_auth(response: httpx.Response) -> str | None:
     """Extract protected resource metadata URL from WWW-Authenticate header as per RFC 9728.
 
     Returns:
@@ -175,7 +175,7 @@ def build_oauth_authorization_server_metadata_discovery_urls(auth_server_url: st
 
 
 async def handle_protected_resource_response(
-    response: Response,
+    response: httpx.Response,
 ) -> ProtectedResourceMetadata | None:
     """Handle protected resource metadata discovery response.
 
@@ -198,7 +198,7 @@ async def handle_protected_resource_response(
         return None
 
 
-async def handle_auth_metadata_response(response: Response) -> tuple[bool, OAuthMetadata | None]:
+async def handle_auth_metadata_response(response: httpx.Response) -> tuple[bool, OAuthMetadata | None]:
     if response.status_code == 200:
         try:
             content = await response.aread()
@@ -211,13 +211,13 @@ async def handle_auth_metadata_response(response: Response) -> tuple[bool, OAuth
     return True, None
 
 
-def create_oauth_metadata_request(url: str) -> Request:
-    return Request("GET", url, headers={MCP_PROTOCOL_VERSION: LATEST_PROTOCOL_VERSION})
+def create_oauth_metadata_request(url: str) -> httpx.Request:
+    return httpx.Request("GET", url, headers={MCP_PROTOCOL_VERSION: LATEST_PROTOCOL_VERSION})
 
 
 def create_client_registration_request(
     auth_server_metadata: OAuthMetadata | None, client_metadata: OAuthClientMetadata, auth_base_url: str
-) -> Request:
+) -> httpx.Request:
     """Build a client registration request."""
 
     if auth_server_metadata and auth_server_metadata.registration_endpoint:
@@ -227,10 +227,10 @@ def create_client_registration_request(
 
     registration_data = client_metadata.model_dump(by_alias=True, mode="json", exclude_none=True)
 
-    return Request("POST", registration_url, json=registration_data, headers={"Content-Type": "application/json"})
+    return httpx.Request("POST", registration_url, json=registration_data, headers={"Content-Type": "application/json"})
 
 
-async def handle_registration_response(response: Response) -> OAuthClientInformationFull:
+async def handle_registration_response(response: httpx.Response) -> OAuthClientInformationFull:
     """Handle registration response."""
     if response.status_code not in (200, 201):
         await response.aread()
@@ -316,7 +316,7 @@ def create_client_info_from_metadata_url(
 
 
 async def handle_token_response_scopes(
-    response: Response,
+    response: httpx.Response,
 ) -> OAuthToken:
     """Parse and validate a token response.
 

src/mcp/client/session_group.py

@@ -14,7 +14,6 @@
 from typing import Any, TypeAlias
 
 import anyio
-import httpx
 from pydantic import BaseModel, Field
 from typing_extensions import Self
 
@@ -24,6 +23,7 @@
 from mcp.client.sse import sse_client
 from mcp.client.stdio import StdioServerParameters
 from mcp.client.streamable_http import streamable_http_client
+from mcp.shared._httpx import httpx
 from mcp.shared._httpx_utils import create_mcp_http_client
 from mcp.shared.exceptions import MCPError
 from mcp.shared.session import ProgressFnT

src/mcp/client/sse.py

@@ -5,12 +5,12 @@
 from urllib.parse import parse_qs, urljoin, urlparse
 
 import anyio
-import httpx
 from anyio.abc import TaskStatus
 from httpx_sse import SSEError, aconnect_sse
 
 from mcp import types
 from mcp.shared._context_streams import create_context_streams
+from mcp.shared._httpx import httpx
 from mcp.shared._httpx_utils import McpHttpClientFactory, create_mcp_http_client
 from mcp.shared.message import SessionMessage
 

src/mcp/client/streamable_http.py

@@ -9,13 +9,13 @@
 from dataclasses import dataclass
 
 import anyio
-import httpx
 from anyio.abc import TaskGroup
 from httpx_sse import EventSource, ServerSentEvent, aconnect_sse
 from pydantic import ValidationError
 
 from mcp.client._transport import TransportStreams
 from mcp.shared._context_streams import ContextReceiveStream, ContextSendStream, create_context_streams
+from mcp.shared._httpx import httpx
 from mcp.shared._httpx_utils import create_mcp_http_client
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.types import (

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

@@ -9,13 +9,13 @@
 
 import anyio
 import anyio.to_thread
-import httpx
 import pydantic
 import pydantic_core
 from pydantic import Field, ValidationInfo, validate_call
 
 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.types import Annotations, Icon
 
 
@@ -159,6 +159,7 @@ 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

@@ -0,0 +1,55 @@
+"""Compatibility shim: prefer `httpx2`, fall back to `httpx` with a deprecation warning.
+
+Mirrors the pattern from
+[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`.
+"""
+
+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.
+
+    Subclasses `UserWarning` (not `DeprecationWarning`) so it is visible by default —
+    `DeprecationWarning` is silenced at the Python level for non-`__main__` callers.
+    """
+
+
+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,
+        )

src/mcp/shared/_httpx_utils.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Protocol
 
-import httpx
+from mcp.shared._httpx import emit_httpx_deprecation_warning, httpx
 
 __all__ = ["create_mcp_http_client", "MCP_DEFAULT_TIMEOUT", "MCP_DEFAULT_SSE_READ_TIMEOUT"]
 
@@ -77,6 +77,8 @@ 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}