The meta-package is the whole mechanism. In 4.x, `fastmcp` carries no code of its own; it declares a dependency on `fastmcp-slim[client,server]`, and `fastmcp-slim` holds the modules [2]. The remaining functionality sits behind extras: `client`, `server`, `mcp`, `anthropic`, `apps`, `azure`, `code-mode`, `gemini`, `openai`, nine in total [3][25].
On a clean install none of this is visible, because `pip install fastmcp` resolves the base extras and everything imports [4]. The reported failure came from upgrading in place over 3.2.x with `pip install -U fastmcp`, where pip did not re-resolve those base extras and left a package that imported but contained nothing [5]. `fastmcp.__file__` returned `None`, `dir(fastmcp)` returned an empty list, and `from fastmcp import Client` raised `ImportError ... (unknown location)` [6]. That is what a directory with no modules in it looks like from the interpreter side. According to the author it burned two false-alarm debugging sessions, since a `ModuleNotFoundError` on a submodule that is genuinely in the wheel is a persuasive symptom [9].
The repair is to uninstall both `fastmcp` and `fastmcp-slim` and install again, pinning `fastmcp==4.0.x` if you want the version you tested, or to rebuild the virtualenv [7]. Before you generalise the diagnosis: this was hit with `pip -U`, and `uv pip install -U` was not tested [8]. FastMCP documents a separate pip file-manifest problem on the 3.2 to 3.3 hop and notes that uv is unaffected by that one, which is a different bug [8]. Carrying "uv is fine" across from the older note is an assumption, not a finding.
The asymmetry matters for how you find out. A CI job that builds a fresh environment every run will stay green [4]; the machines that break are the ones with history, including any host where a deploy step bumps a pin in place [5].
The second class of breakage compiles and type-checks. FastMCP 4 dropped `httpx` for `httpx2` internally, so a client call that raised `httpx.ConnectError` now raises `httpx2.ConnectError` [11]. Because `httpx` usually remains transitively installed, the old `except httpx.ConnectError` still resolves and simply stops matching [12]. The suggested sweep is a grep for `except httpx.` and a check of whether each one wraps a FastMCP `Client` or transport call [12]. Anything you hand in that was built on `httpx` moves too: a custom `httpx_client_factory`, an `httpx.AsyncClient` given to a transport, an `httpx.Auth` [13]. Log filters keyed on `httpx` or `httpcore.*` need repointing at `httpx2` and `httpcore2.*` [15].
Then the default protocol era. `Client(...)` now defaults to `mode="auto"` and negotiates the sessionless `2026-07-28` era, where the `on_initialize` handshake never fires, `ctx.set_state()` does not persist to the next call, and `ctx.elicit()` raises [16][17]. Clients doing plain `call_tool` and `read_resource` need no change [24]; anything leaning on session state or an init hook gets pinned with `mode="legacy"` [18]. `StreamableHttpTransport` also lost `sse_read_timeout=`, which moves to `timeout=` on the `Client` [19]. Elicitation still exists but requires `response_type` and raises on modern connections, so the rewrite is a guard tool returning an "input required" result [23].
`FastMCP(...)`, `@mcp.tool` and `mcp.run(transport=...)` are unchanged [21]. That is exactly why the rest is quiet: the surface your code touches still looks right.
