PrefectHQ/fastmcp · warning · FastMCPDeprecationWarning

`ProxyInitializeMiddleware` is deprecated and will be remove

Error message

`ProxyInitializeMiddleware` is deprecated and will be removed in a future release. `FastMCPProxy` now installs `ProxyMetadataMiddleware` automatically.

What it means

`ProxyInitializeMiddleware` was a middleware for forwarding server instructions during proxy initialization. `FastMCPProxy` now installs `ProxyMetadataMiddleware` automatically, so instantiating this class is deprecated and raises `FastMCPDeprecationWarning`; it will be removed.

Source

Thrown at fastmcp_slim/fastmcp/server/providers/proxy.py:272

    handler's ``get_context()`` would otherwise resolve to the backend context
    and the server-initiated request would hang until timeout.

    We stash a ``(RequestContext, weakref[FastMCP])`` tuple — never a ``Context``
    instance — because ``Context`` properties are themselves ContextVar-dependent
    and would resolve stale values in the receive loop.
    """
    if isinstance(client, ProxyClient):
        client._proxy_rc_ref[0] = (
            ctx.request_context,
            ctx._fastmcp,  # weakref to FastMCP, not the Context
        )


class ProxyInitializeMiddleware(Middleware):
    """Deprecated middleware for forwarding instructions during initialization."""

    def __init__(self, proxy: FastMCPProxy) -> None:
        warnings.warn(
            "`ProxyInitializeMiddleware` is deprecated and will be removed in a "
            "future release. `FastMCPProxy` now installs "
            "`ProxyMetadataMiddleware` automatically.",
            FastMCPDeprecationWarning,
            stacklevel=2,
        )
        self.proxy = proxy

    async def on_initialize(
        self,
        context: MiddlewareContext[mcp_types.InitializeRequest],
        call_next: CallNext[
            mcp_types.InitializeRequest,
            mcp_types.InitializeResult | None,
        ],
    ) -> mcp_types.InitializeResult | None:
        client = await self.proxy._get_client()
        upstream_instructions: str | None = None

View on GitHub (pinned to 1f02114297)

Solutions

1. Delete the `ProxyInitializeMiddleware` usage — `FastMCPProxy` handles metadata/instructions automatically now.
2. If you need custom instructions, configure them on the proxy itself rather than via this middleware.
3. Remove imports of `ProxyInitializeMiddleware` to avoid breakage when it is removed.
4. Test the proxy init handshake after removal to confirm instructions still arrive.

Example fix

// before
server = FastMCPProxy(client=client, middleware=[ProxyInitializeMiddleware(proxy)])
// after
server = FastMCPProxy(client=client)  # ProxyMetadataMiddleware installed automatically

# do not reference ProxyInitializeMiddleware anywhere in middleware lists
assert "ProxyInitializeMiddleware" not in {type(m).__name__ for m in server.middleware}

import warnings
from fastmcp.exceptions import FastMCPDeprecationWarning
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always", FastMCPDeprecationWarning)
    mw = ProxyInitializeMiddleware(proxy)
if any("ProxyInitializeMiddleware" in str(w.message) for w in caught):
    mw = None  # rely on FastMCPProxy's automatic ProxyMetadataMiddleware

When it happens

Trigger: Constructing `ProxyInitializeMiddleware(proxy)` directly, or explicitly passing it into a `FastMCP(middleware=[...])` / proxy server's middleware list.

Common situations: Proxy configs copied from pre-`ProxyMetadataMiddleware` examples; manual middleware stacks where instructions forwarding was set up by hand.

Related errors

• '{name}' is a synthetic search tool and cannot be called via
• Accessing `{cls_name}.{camel}` is deprecated; MCP SDK v2 ren
• Passing an httpx.AsyncClient to OpenAPIProvider is deprecate
• module {__name__!r} has no attribute {name!r}
• Cannot resolve tool reference: {fn!r}

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