Emit deprecation warnings as a visible MCPDeprecationWarning

The SEP-2577 method deprecations now warn via `mcp.MCPDeprecationWarning`, a
`UserWarning` subclass, instead of the built-in `DeprecationWarning`. Python
silences `DeprecationWarning` by default outside `__main__`, so most users never
see it; inheriting from `UserWarning` makes the deprecation visible by default.

Pass `category=MCPDeprecationWarning` to every `@deprecated` decorator, export
the class from `mcp`, and document how to silence it.

Author: Kludex

docs/migration.md

@@ -1226,6 +1226,15 @@ The user-facing methods for these features now carry `typing_extensions.deprecat
 - Roots: `ServerSession.list_roots()`, `ClientPeer.list_roots()`, `ClientSession.send_roots_list_changed()`, `Client.send_roots_list_changed()`
 - Logging: `ServerSession.send_log_message()`, `ClientSession.set_logging_level()`, `Client.set_logging_level()`, and the `MCPServer` `Context` helpers `log()`, `debug()`, `info()`, `warning()`, `error()`
 
+The runtime warning is emitted as `mcp.MCPDeprecationWarning`, which subclasses `UserWarning` (not `DeprecationWarning`) so it is visible by default. To silence it, filter that category:
+
+```python
+import warnings
+from mcp import MCPDeprecationWarning
+
+warnings.filterwarnings("ignore", category=MCPDeprecationWarning)
+```
+
 No migration is required during the deprecation window. New code should avoid building on these features, since they may be removed in a future spec version.
 
 ## Bug Fixes

pyproject.toml

@@ -216,7 +216,7 @@ filterwarnings = [
     # SEP-2577 deprecates the roots/sampling/logging methods; the SDK still calls
     # them internally (e.g. `ctx.debug` -> `log` -> `send_log_message`), so the
     # advisory warning is silenced. Tests asserting it opt back in with pytest.warns.
-    "ignore:`.*` is deprecated as of 2026-07-28 \\(SEP-2577\\).:DeprecationWarning",
+    "ignore:`.*` is deprecated as of 2026-07-28 \\(SEP-2577\\).:mcp.MCPDeprecationWarning",
 ]
 
 [tool.markdown.lint]

src/mcp/__init__.py

@@ -4,7 +4,7 @@
 from .client.stdio import StdioServerParameters, stdio_client
 from .server.session import ServerSession
 from .server.stdio import stdio_server
-from .shared.exceptions import MCPError, UrlElicitationRequiredError
+from .shared.exceptions import MCPDeprecationWarning, MCPError, UrlElicitationRequiredError
 from .types import (
     CallToolRequest,
     ClientCapabilities,
@@ -96,6 +96,7 @@
     "ListToolsResult",
     "LoggingLevel",
     "LoggingMessageNotification",
+    "MCPDeprecationWarning",
     "MCPError",
     "Notification",
     "PingRequest",

src/mcp/client/client.py

@@ -15,6 +15,7 @@
 from mcp.server import Server
 from mcp.server.mcpserver import MCPServer
 from mcp.shared.dispatcher import ProgressFnT
+from mcp.shared.exceptions import MCPDeprecationWarning
 from mcp.types import (
     CallToolResult,
     CompleteResult,
@@ -197,7 +198,7 @@ async def send_progress_notification(
             message=message,
         )
 
-    @deprecated("`set_logging_level` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`set_logging_level` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def set_logging_level(self, level: LoggingLevel, *, meta: RequestParamsMeta | None = None) -> EmptyResult:
         """Set the logging level on the server."""
         return await self.session.set_logging_level(level=level, meta=meta)  # pyright: ignore[reportDeprecated]
@@ -315,7 +316,7 @@ async def list_tools(self, *, cursor: str | None = None, meta: RequestParamsMeta
         """List available tools from the server."""
         return await self.session.list_tools(params=PaginatedRequestParams(cursor=cursor, _meta=meta))
 
-    @deprecated("`send_roots_list_changed` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`send_roots_list_changed` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def send_roots_list_changed(self) -> None:
         """Send a notification that the roots list has changed."""
         # TODO(Marcelo): Currently, there is no way for the server to handle this. We should add support.

src/mcp/client/session.py

@@ -16,7 +16,7 @@
 from mcp.client._transport import ReadStream, WriteStream
 from mcp.shared._compat import resync_tracer
 from mcp.shared.dispatcher import CallOptions, DispatchContext, Dispatcher, ProgressFnT
-from mcp.shared.exceptions import MCPError
+from mcp.shared.exceptions import MCPDeprecationWarning, MCPError
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.shared.session import RequestResponder
@@ -386,7 +386,7 @@ async def send_progress_notification(
             )
         )
 
-    @deprecated("`set_logging_level` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`set_logging_level` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def set_logging_level(
         self,
         level: types.LoggingLevel,
@@ -551,7 +551,7 @@ async def list_tools(self, *, params: types.PaginatedRequestParams | None = None
 
         return result
 
-    @deprecated("`send_roots_list_changed` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`send_roots_list_changed` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def send_roots_list_changed(self) -> None:
         """Send a roots/list_changed notification."""
         await self.send_notification(types.RootsListChangedNotification())

src/mcp/server/context.py

@@ -9,6 +9,7 @@
 from mcp.server.session import ServerSession
 from mcp.shared.context import BaseContext
 from mcp.shared.dispatcher import DispatchContext
+from mcp.shared.exceptions import MCPDeprecationWarning
 from mcp.shared.message import CloseSSEStreamCallback
 from mcp.shared.peer import Meta
 from mcp.shared.transport_context import TransportContext
@@ -92,7 +93,7 @@ def headers(self) -> Mapping[str, str] | None:
         """
         return self.transport.headers
 
-    @deprecated("`log` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`log` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def log(self, level: LoggingLevel, data: Any, logger: str | None = None, *, meta: Meta | None = None) -> None:
         """Send a request-scoped `notifications/message` log entry.
 

src/mcp/server/mcpserver/context.py

@@ -15,6 +15,7 @@
     elicit_with_validation,
 )
 from mcp.server.lowlevel.helper_types import ReadResourceContents
+from mcp.shared.exceptions import MCPDeprecationWarning
 from mcp.types import LoggingLevel
 
 if TYPE_CHECKING:
@@ -190,7 +191,7 @@ async def elicit_url(
             related_request_id=self.request_id,
         )
 
-    @deprecated("`log` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`log` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def log(
         self,
         level: LoggingLevel,
@@ -267,22 +268,22 @@ async def close_standalone_sse_stream(self) -> None:
             await self._request_context.close_standalone_sse_stream()
 
     # Convenience methods for common log levels
-    @deprecated("`debug` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`debug` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def debug(self, data: Any, *, logger_name: str | None = None) -> None:
         """Send a debug log message."""
         await self.log("debug", data, logger_name=logger_name)  # pyright: ignore[reportDeprecated]
 
-    @deprecated("`info` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`info` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def info(self, data: Any, *, logger_name: str | None = None) -> None:
         """Send an info log message."""
         await self.log("info", data, logger_name=logger_name)  # pyright: ignore[reportDeprecated]
 
-    @deprecated("`warning` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`warning` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def warning(self, data: Any, *, logger_name: str | None = None) -> None:
         """Send a warning log message."""
         await self.log("warning", data, logger_name=logger_name)  # pyright: ignore[reportDeprecated]
 
-    @deprecated("`error` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`error` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def error(self, data: Any, *, logger_name: str | None = None) -> None:
         """Send an error log message."""
         await self.log("error", data, logger_name=logger_name)  # pyright: ignore[reportDeprecated]

src/mcp/server/session.py

@@ -18,7 +18,7 @@
 from mcp.server.connection import Connection
 from mcp.server.validation import validate_sampling_tools, validate_tool_use_result_messages
 from mcp.shared.dispatcher import CallOptions, Dispatcher, ProgressFnT
-from mcp.shared.exceptions import NoBackChannelError, StatelessModeNotSupported
+from mcp.shared.exceptions import MCPDeprecationWarning, NoBackChannelError, StatelessModeNotSupported
 from mcp.shared.message import ServerMessageMetadata
 from mcp.types import methods as _methods
 
@@ -127,7 +127,7 @@ def check_client_capability(self, capability: types.ClientCapabilities) -> bool:
         """Check if the client supports a specific capability."""
         return self._connection.check_capability(capability)
 
-    @deprecated("`send_log_message` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`send_log_message` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def send_log_message(
         self,
         level: types.LoggingLevel,
@@ -156,7 +156,7 @@ async def send_resource_updated(self, uri: str | AnyUrl) -> None:
         )
 
     @overload
-    @deprecated("`create_message` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`create_message` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def create_message(
         self,
         messages: list[types.SamplingMessage],
@@ -176,7 +176,7 @@ async def create_message(
         ...
 
     @overload
-    @deprecated("`create_message` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`create_message` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def create_message(
         self,
         messages: list[types.SamplingMessage],
@@ -195,7 +195,7 @@ async def create_message(
         """Overload: With tools, returns array-capable content."""
         ...
 
-    @deprecated("`create_message` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`create_message` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def create_message(
         self,
         messages: list[types.SamplingMessage],
@@ -272,7 +272,7 @@ async def create_message(
             metadata=metadata_obj,
         )
 
-    @deprecated("`list_roots` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`list_roots` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def list_roots(self) -> types.ListRootsResult:
         """Send a roots/list request."""
         if self._stateless:

src/mcp/shared/exceptions.py

@@ -5,6 +5,17 @@
 from mcp.types import INVALID_REQUEST, URL_ELICITATION_REQUIRED, ElicitRequestURLParams, ErrorData, JSONRPCError
 
 
+class MCPDeprecationWarning(UserWarning):
+    """A custom deprecation warning for the MCP SDK.
+
+    Unlike the built-in `DeprecationWarning`, this inherits from `UserWarning` so
+    it is shown by default, helping users discover deprecated features without
+    enabling warnings explicitly.
+
+    Reference: https://sethmlarson.dev/deprecations-via-warnings-dont-work-for-python-libraries
+    """
+
+
 class MCPError(Exception):
     """Exception type raised when an error arrives over an MCP connection."""
 

src/mcp/shared/peer.py

@@ -16,6 +16,7 @@
 from typing_extensions import deprecated
 
 from mcp.shared.dispatcher import CallOptions, Outbound
+from mcp.shared.exceptions import MCPDeprecationWarning
 from mcp.types import (
     CreateMessageRequestParams,
     CreateMessageResult,
@@ -84,7 +85,7 @@ async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
         await self._outbound.notify(method, params)
 
     @overload
-    @deprecated("`sample` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`sample` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def sample(
         self,
         messages: list[SamplingMessage],
@@ -102,7 +103,7 @@ async def sample(
         opts: CallOptions | None = None,
     ) -> CreateMessageResult: ...
     @overload
-    @deprecated("`sample` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`sample` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def sample(
         self,
         messages: list[SamplingMessage],
@@ -119,7 +120,7 @@ async def sample(
         meta: Meta | None = None,
         opts: CallOptions | None = None,
     ) -> CreateMessageResultWithTools: ...
-    @deprecated("`sample` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`sample` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def sample(
         self,
         messages: list[SamplingMessage],
@@ -199,7 +200,7 @@ async def elicit_url(
         result = await self.send_raw_request("elicitation/create", dump_params(params, meta), opts)
         return ElicitResult.model_validate(result, by_name=False)
 
-    @deprecated("`list_roots` is deprecated as of 2026-07-28 (SEP-2577).")
+    @deprecated("`list_roots` is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def list_roots(self, *, meta: Meta | None = None, opts: CallOptions | None = None) -> ListRootsResult:
         """Send a `roots/list` request.