PrefectHQ/fastmcp · warning · FastMCPDeprecationWarning

Passing an httpx.AsyncClient to OpenAPIProvider is deprecate

Error message

Passing an httpx.AsyncClient to OpenAPIProvider is deprecated and will be removed in a future release. Pass an httpx2.AsyncClient instead.

What it means

OpenAPIProvider now expects an `httpx2.AsyncClient`. Passing the legacy `httpx.AsyncClient` still works but is deprecated and will be removed, so FastMCP emits a `FastMCPDeprecationWarning` when it detects a legacy client instance.

Source

Thrown at fastmcp_slim/fastmcp/server/providers/openapi/provider.py:119

                Legacy httpx clients are temporarily accepted with a deprecation
                warning.
            route_maps: Optional list of RouteMap objects defining route mappings
            route_map_fn: Optional callable for advanced route type mapping
            mcp_component_fn: Optional callable for component customization
            mcp_names: Optional dictionary mapping operationId to component names
            tags: Optional set of tags to add to all components
            validate_output: If True (default), tools use the output schema
                extracted from the OpenAPI spec for response validation. If
                False, a permissive schema is used instead, allowing any
                response structure while still returning structured JSON.
        """
        super().__init__()

        self._owns_client = client is None
        if client is None:
            client = self._create_default_client(openapi_spec)
        elif _is_legacy_httpx_client(client):
            warnings.warn(
                "Passing an httpx.AsyncClient to OpenAPIProvider is deprecated "
                "and will be removed in a future release. Pass an "
                "httpx2.AsyncClient instead.",
                FastMCPDeprecationWarning,
                stacklevel=2,
            )
        self._client = client
        self._mcp_component_fn = mcp_component_fn
        self._validate_output = validate_output

        # Keep track of names to detect collisions
        self._used_names: dict[str, Counter[str]] = {
            "tool": Counter(),
            "resource": Counter(),
            "resource_template": Counter(),
            "prompt": Counter(),
        }

View on GitHub (pinned to 1f02114297)

Solutions

1. Construct the client from `httpx2` instead: `client = httpx2.AsyncClient(base_url=...)` and pass that.
2. If you manage a shared client, register it as `httpx2.AsyncClient` at the injection site.
3. Check `_is_legacy_httpx_client` conditions and update all call paths constructing the client.
4. Pin/monitor the FastMCP changelog to finish the migration before the removal release.

Example fix

// before
client = httpx.AsyncClient(base_url="https://api.example.com")
provider = OpenAPIProvider(openapi_spec=spec, client=client)
// after
import httpx2
client = httpx2.AsyncClient(base_url="https://api.example.com")
provider = OpenAPIProvider(openapi_spec=spec, client=client)

import httpx, httpx2
assert isinstance(client, httpx2.AsyncClient) and not isinstance(client, httpx.AsyncClient), "pass an httpx2.AsyncClient to OpenAPIProvider"

import httpx
def is_legacy_httpx_client(client) -> bool:
    return isinstance(client, httpx.AsyncClient)  # mirror of _is_legacy_httpx_client

import warnings
from fastmcp.exceptions import FastMCPDeprecationWarning
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always", FastMCPDeprecationWarning)
    provider = OpenAPIProvider(openapi_spec=spec, client=client)
if any("httpx2.AsyncClient" in str(w.message) for w in caught):
    raise TypeError("OpenAPIProvider requires an httpx2.AsyncClient")

When it happens

Trigger: `OpenAPIProvider(openapi_spec=spec, client=httpx.AsyncClient(...))` — any legacy httpx client passed explicitly (passing `client=None` builds the default and is fine).

Common situations: Code written before the httpx2 migration; shared HTTP client pools still typed as `httpx.AsyncClient`; dependency-injection containers that construct httpx clients generically.

Related errors

• StreamingASGITransport requires an async request stream; got
• Accessing `{cls_name}.{camel}` is deprecated; MCP SDK v2 ren
• Both 'httpx_client_factory' and 'verify' were provided. The
• Both 'httpx_client_factory' and 'verify' were provided. The
• `ProxyInitializeMiddleware` is deprecated and will be remove

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/8a3cf4f8863fdb39. Report an issue: GitHub.