fix: scope deprecation warning filter to FastMCPDeprecationWarning (#3649)

src/fastmcp/__init__.py

@@ -19,16 +19,15 @@ if settings.log_enabled:
         enable_rich_tracebacks=settings.enable_rich_tracebacks,
     )
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.server.server import FastMCP
 from fastmcp.server.context import Context
 import fastmcp.server
 
 __version__ = _version("fastmcp")
 
-
-# ensure deprecation warnings are displayed by default
 if settings.deprecation_warnings:
-    warnings.simplefilter("default", DeprecationWarning)
+    warnings.simplefilter("default", FastMCPDeprecationWarning)
 
 
 # --- Lazy imports for performance (see #3292) ---
@@ -55,5 +54,6 @@ __all__ = [
     "Context",
     "FastMCP",
     "FastMCPApp",
+    "FastMCPDeprecationWarning",
     "settings",
 ]

src/fastmcp/client/transports/http.py

@@ -19,6 +19,7 @@ import fastmcp
 from fastmcp.client.auth.bearer import BearerAuth
 from fastmcp.client.auth.oauth import OAuth
 from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.server.dependencies import get_http_headers
 from fastmcp.utilities.timeout import normalize_timeout_to_timedelta
 
@@ -88,7 +89,7 @@ class StreamableHttpTransport(ClientTransport):
                     "The new streamable_http_client API does not support this parameter. "
                     "Use `read_timeout_seconds` in session_kwargs or configure timeout on "
                     "the httpx client via `httpx_client_factory` instead.",
-                    DeprecationWarning,
+                    FastMCPDeprecationWarning,
                     stacklevel=2,
                 )
         self.sse_read_timeout = normalize_timeout_to_timedelta(sse_read_timeout)

src/fastmcp/contrib/mcp_mixin/mcp_mixin.py

@@ -6,6 +6,7 @@ from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
 import fastmcp
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.prompts.base import Prompt
 from fastmcp.resources.base import Resource
 from fastmcp.tools.base import Tool
@@ -77,7 +78,7 @@ def mcp_tool(
             "The `serializer` parameter is deprecated. "
             "Return ToolResult from your tools for full control over serialization. "
             "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
-            DeprecationWarning,
+            FastMCPDeprecationWarning,
             stacklevel=2,
         )
 

src/fastmcp/exceptions.py

@@ -3,6 +3,15 @@
 from mcp import McpError  # noqa: F401
 
 
+class FastMCPDeprecationWarning(DeprecationWarning):
+    """Deprecation warning for FastMCP APIs.
+
+    Subclass of DeprecationWarning so that standard warning filters
+    still apply, but FastMCP can selectively enable its own warnings
+    without affecting other libraries in the process.
+    """
+
+
 class FastMCPError(Exception):
     """Base error for FastMCP."""
 

src/fastmcp/experimental/server/openapi/__init__.py

@@ -2,11 +2,13 @@
 
 import warnings
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
+
 # Deprecated in 2.14 when OpenAPI support was promoted out of experimental
 warnings.warn(
     "Importing from fastmcp.experimental.server.openapi is deprecated. "
     "Import from fastmcp.server.providers.openapi instead.",
-    DeprecationWarning,
+    FastMCPDeprecationWarning,
     stacklevel=2,
 )
 

src/fastmcp/experimental/utilities/openapi/__init__.py

@@ -2,6 +2,8 @@
 
 import warnings
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
+
 from fastmcp.utilities.openapi import (
     HTTPRoute,
     HttpMethod,
@@ -18,7 +20,7 @@ from fastmcp.utilities.openapi import (
 warnings.warn(
     "Importing from fastmcp.experimental.utilities.openapi is deprecated. "
     "Import from fastmcp.utilities.openapi instead.",
-    DeprecationWarning,
+    FastMCPDeprecationWarning,
     stacklevel=2,
 )
 

src/fastmcp/prompts/base.py

@@ -29,6 +29,7 @@ from mcp.types import PromptArgument as SDKPromptArgument
 from pydantic import Field
 from pydantic.json_schema import SkipJsonSchema
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.server.auth.authorization import AuthCheck
 from fastmcp.server.tasks.config import TaskConfig, TaskMeta
 from fastmcp.utilities.components import FastMCPComponent
@@ -429,7 +430,7 @@ def __getattr__(name: str) -> Any:
             warnings.warn(
                 f"Importing {name} from fastmcp.prompts.prompt is deprecated. "
                 f"Import from fastmcp.prompts.function_prompt instead.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         from fastmcp.prompts import function_prompt

src/fastmcp/prompts/function_prompt.py

@@ -24,7 +24,7 @@ from pydantic.json_schema import SkipJsonSchema
 
 import fastmcp
 from fastmcp.decorators import resolve_task_config
-from fastmcp.exceptions import PromptError
+from fastmcp.exceptions import FastMCPDeprecationWarning, PromptError
 from fastmcp.prompts.base import Prompt, PromptArgument, PromptResult
 from fastmcp.server.auth.authorization import AuthCheck
 from fastmcp.server.dependencies import (
@@ -461,7 +461,7 @@ def prompt(
             warnings.warn(
                 "decorator_mode='object' is deprecated and will be removed in a future version. "
                 "Decorators now return the original function with metadata attached.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=4,
             )
             return create_prompt(fn, prompt_name)  # type: ignore[return-value]  # ty:ignore[invalid-return-type]

src/fastmcp/resources/base.py

@@ -29,6 +29,7 @@ from pydantic import (
 from pydantic.json_schema import SkipJsonSchema
 from typing_extensions import Self
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.server.auth.authorization import AuthCheck
 from fastmcp.server.tasks.config import TaskConfig, TaskMeta
 from fastmcp.utilities.components import FastMCPComponent
@@ -456,7 +457,7 @@ def __getattr__(name: str) -> Any:
             warnings.warn(
                 f"Importing {name} from fastmcp.resources.resource is deprecated. "
                 f"Import from fastmcp.resources.function_resource instead.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         from fastmcp.resources import function_resource

src/fastmcp/resources/function_resource.py

@@ -15,6 +15,7 @@ from pydantic.json_schema import SkipJsonSchema
 
 import fastmcp
 from fastmcp.decorators import resolve_task_config
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.resources.base import Resource, ResourceResult
 from fastmcp.server.auth.authorization import AuthCheck
 from fastmcp.server.dependencies import (
@@ -335,7 +336,7 @@ def resource(
             warnings.warn(
                 "decorator_mode='object' is deprecated and will be removed in a future version. "
                 "Decorators now return the original function with metadata attached.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=3,
             )
             return create_resource(fn)  # type: ignore[return-value]  # ty:ignore[invalid-return-type]

src/fastmcp/server/app.py

@@ -9,10 +9,11 @@ import warnings
 from fastmcp.apps.app import FastMCPApp as FastMCPApp
 from fastmcp.apps.app import _dispatch_decorator as _dispatch_decorator
 from fastmcp.apps.app import _resolve_tool_ref as _resolve_tool_ref
+from fastmcp.exceptions import FastMCPDeprecationWarning
 
 warnings.warn(
     "'fastmcp.server.app' is deprecated. "
     "Use 'fastmcp.apps.app' or 'from fastmcp import FastMCPApp' instead.",
-    DeprecationWarning,
+    FastMCPDeprecationWarning,
     stacklevel=2,
 )

src/fastmcp/server/apps.py

@@ -11,11 +11,12 @@ from fastmcp.apps.config import AppConfig as AppConfig
 from fastmcp.apps.config import ResourceCSP as ResourceCSP
 from fastmcp.apps.config import ResourcePermissions as ResourcePermissions
 from fastmcp.apps.config import app_config_to_meta_dict as app_config_to_meta_dict
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.utilities.mime import UI_MIME_TYPE as UI_MIME_TYPE
 from fastmcp.utilities.mime import resolve_ui_mime_type as resolve_ui_mime_type
 
 warnings.warn(
     "'fastmcp.server.apps' is deprecated. Use 'from fastmcp.apps import ...' instead.",
-    DeprecationWarning,
+    FastMCPDeprecationWarning,
     stacklevel=2,
 )

src/fastmcp/server/middleware/tool_injection.py

@@ -11,6 +11,7 @@ from pydantic import AnyUrl
 from typing_extensions import override
 
 import fastmcp
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.resources.base import ResourceResult
 from fastmcp.server.context import Context
 from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
@@ -91,7 +92,7 @@ class PromptToolMiddleware(ToolInjectionMiddleware):
             warnings.warn(
                 "PromptToolMiddleware is deprecated. Use the PromptsAsTools transform instead: "
                 "from fastmcp.server.transforms import PromptsAsTools",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         tools: list[Tool] = [list_prompts_tool, get_prompt_tool]
@@ -133,7 +134,7 @@ class ResourceToolMiddleware(ToolInjectionMiddleware):
             warnings.warn(
                 "ResourceToolMiddleware is deprecated. Use the ResourcesAsTools transform instead: "
                 "from fastmcp.server.transforms import ResourcesAsTools",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         tools: list[Tool] = [list_resources_tool, read_resource_tool]

src/fastmcp/server/openapi/__init__.py

@@ -20,10 +20,12 @@ FastMCPOpenAPI is still available but deprecated.
 
 import warnings
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
+
 warnings.warn(
     "fastmcp.server.openapi is deprecated. "
     "Import from fastmcp.server.providers.openapi instead.",
-    DeprecationWarning,
+    FastMCPDeprecationWarning,
     stacklevel=2,
 )
 

src/fastmcp/server/openapi/components.py

@@ -7,10 +7,12 @@ from __future__ import annotations
 
 import warnings
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
+
 warnings.warn(
     "fastmcp.server.openapi.components is deprecated. "
     "Import from fastmcp.server.providers.openapi instead.",
-    DeprecationWarning,
+    FastMCPDeprecationWarning,
     stacklevel=2,
 )
 

src/fastmcp/server/openapi/routing.py

@@ -8,6 +8,8 @@
 
 import warnings
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
+
 # Backwards compatibility - export everything that was previously public
 __all__ = [
     "DEFAULT_ROUTE_MAPPINGS",
@@ -21,7 +23,7 @@ __all__ = [
 warnings.warn(
     "fastmcp.server.openapi.routing is deprecated. "
     "Import from fastmcp.server.providers.openapi instead.",
-    DeprecationWarning,
+    FastMCPDeprecationWarning,
     stacklevel=2,
 )
 

src/fastmcp/server/openapi/server.py

@@ -18,6 +18,7 @@ from typing import Any
 
 import httpx
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.server.providers.openapi import (
     ComponentFn,
     OpenAPIProvider,
@@ -90,7 +91,7 @@ class FastMCPOpenAPI(FastMCP):
             "FastMCPOpenAPI is deprecated. Use FastMCP with OpenAPIProvider instead:\n"
             "    provider = OpenAPIProvider(openapi_spec=spec, client=client)\n"
             "    mcp = FastMCP('name', providers=[provider])",
-            DeprecationWarning,
+            FastMCPDeprecationWarning,
             stacklevel=2,
         )
 

src/fastmcp/server/providers/local_provider/decorators/tools.py

@@ -27,6 +27,7 @@ import mcp.types
 from mcp.types import AnyFunction, ToolAnnotations
 
 import fastmcp
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.server.auth.authorization import AuthCheck
 from fastmcp.server.tasks.config import TaskConfig
 from fastmcp.tools.base import Tool
@@ -319,7 +320,7 @@ class ToolDecoratorMixin:
                 "The `serializer` parameter is deprecated. "
                 "Return ToolResult from your tools for full control over serialization. "
                 "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         if isinstance(annotations, dict):

src/fastmcp/server/providers/openapi/components.py

@@ -13,6 +13,7 @@ from mcp.types import ToolAnnotations
 from pydantic.networks import AnyUrl
 
 import fastmcp
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.resources import (
     Resource,
     ResourceContent,
@@ -157,7 +158,7 @@ class OpenAPITool(Tool):
                 "The `serializer` parameter is deprecated. "
                 "Return ToolResult from your tools for full control over serialization. "
                 "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         super().__init__(

src/fastmcp/server/proxy.py

@@ -9,9 +9,11 @@ from __future__ import annotations
 
 import warnings
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
+
 warnings.warn(
     "fastmcp.server.proxy is deprecated. Use fastmcp.server.providers.proxy instead.",
-    DeprecationWarning,
+    FastMCPDeprecationWarning,
     stacklevel=2,
 )
 

src/fastmcp/server/server.py

@@ -48,6 +48,7 @@ from fastmcp.apps.config import (
 )
 from fastmcp.exceptions import (
     AuthorizationError,
+    FastMCPDeprecationWarning,
     FastMCPError,
     NotFoundError,
     PromptError,
@@ -521,7 +522,7 @@ class FastMCP(
             warnings.warn(
                 "add_tool_transformation is deprecated. Use "
                 "server.add_transform(ToolTransform({tool_name: config})) instead.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         self.add_transform(ToolTransform({tool_name: transformation}))
@@ -537,7 +538,7 @@ class FastMCP(
                 "remove_tool_transformation is deprecated and has no effect. "
                 "Transforms are immutable once added. Use server.disable(keys=[...]) "
                 "to hide tools instead.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
 
@@ -1460,7 +1461,7 @@ class FastMCP(
             warnings.warn(
                 "remove_tool() is deprecated. Use "
                 "mcp.local_provider.remove_tool(name) instead.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         try:
@@ -1955,7 +1956,7 @@ class FastMCP(
         if prefix is not None:
             warnings.warn(
                 "The 'prefix' parameter is deprecated, use 'namespace' instead",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
             if namespace is None:
@@ -1968,7 +1969,7 @@ class FastMCP(
                 "as_proxy is deprecated and will be removed in a future version. "
                 "Mounted servers now always have their lifespan and middleware invoked. "
                 "To create a proxy server, use create_proxy() explicitly.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
             # Still honor the flag for backward compatibility
@@ -2037,7 +2038,7 @@ class FastMCP(
 
         warnings.warn(
             "import_server is deprecated, use mount() instead",
-            DeprecationWarning,
+            FastMCPDeprecationWarning,
             stacklevel=2,
         )
 
@@ -2229,7 +2230,7 @@ class FastMCP(
             warnings.warn(
                 "FastMCP.as_proxy() is deprecated. Use create_proxy() from "
                 "fastmcp.server instead: `from fastmcp.server import create_proxy`",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         # Call the module-level create_proxy function directly

src/fastmcp/tools/base.py

@@ -26,6 +26,7 @@ from mcp.types import Tool as MCPTool
 from pydantic import BaseModel, Field, model_validator
 from pydantic.json_schema import SkipJsonSchema
 
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.server.auth.authorization import AuthCheck
 from fastmcp.server.tasks.config import TaskConfig, TaskMeta
 from fastmcp.utilities.components import FastMCPComponent
@@ -589,7 +590,7 @@ def __getattr__(name: str) -> Any:
             warnings.warn(
                 f"Importing {name} from fastmcp.tools.tool is deprecated. "
                 f"Import from fastmcp.tools.function_tool instead.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         from fastmcp.tools import function_tool

src/fastmcp/tools/function_tool.py

@@ -25,6 +25,7 @@ from pydantic.json_schema import SkipJsonSchema
 
 import fastmcp
 from fastmcp.decorators import resolve_task_config
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.server.auth.authorization import AuthCheck
 from fastmcp.server.dependencies import without_injected_parameters
 from fastmcp.server.tasks.config import TaskConfig
@@ -174,7 +175,7 @@ class FunctionTool(Tool):
                 "The `serializer` parameter is deprecated. "
                 "Return ToolResult from your tools for full control over serialization. "
                 "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         if metadata.exclude_args and fastmcp.settings.deprecation_warnings:
@@ -182,7 +183,7 @@ class FunctionTool(Tool):
                 "The `exclude_args` parameter is deprecated as of FastMCP 2.14. "
                 "Use dependency injection with `Depends()` instead for better lifecycle management. "
                 "See https://gofastmcp.com/servers/dependency-injection#using-depends for examples.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
 
@@ -434,7 +435,7 @@ def tool(
             warnings.warn(
                 "decorator_mode='object' is deprecated and will be removed in a future version. "
                 "Decorators now return the original function with metadata attached.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=4,
             )
             return create_tool(fn, tool_name)  # type: ignore[return-value]  # ty:ignore[invalid-return-type]

src/fastmcp/tools/tool_transform.py

@@ -16,6 +16,7 @@ from pydantic.functional_validators import BeforeValidator
 from pydantic.json_schema import SkipJsonSchema
 
 import fastmcp
+from fastmcp.exceptions import FastMCPDeprecationWarning
 from fastmcp.tools.base import Tool, ToolResult, _convert_to_content
 from fastmcp.tools.function_parsing import ParsedFunction
 from fastmcp.utilities.components import _convert_set_default_none
@@ -459,7 +460,7 @@ class TransformedTool(Tool):
                 "The `serializer` parameter is deprecated. "
                 "Return ToolResult from your tools for full control over serialization. "
                 "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
-                DeprecationWarning,
+                FastMCPDeprecationWarning,
                 stacklevel=2,
             )
         transform_args = transform_args or {}