Deprecate roots, sampling, and logging methods per SEP-2577

SEP-2577 deprecates the Roots, Sampling, and Logging features as of the
2026-07-28 spec. The deprecation is advisory only: no wire-level changes,
capability negotiation is unchanged, and every method keeps working for
sessions negotiating 2025-11-25 and earlier.

Mark the user-facing methods for these features with
`typing_extensions.deprecated` so type checkers, IDEs, and the runtime warn at
the call site: `create_message`/`sample` (sampling), `list_roots` /
`send_roots_list_changed` (roots), `send_log_message` / `set_logging_level` and
the `MCPServer` `Context` log helpers (logging). Unlike decorating the schema
types, this keeps the footprint small while still making users aware.

The advisory runtime warning is silenced via a scoped `filterwarnings` entry
since the SDK calls these methods internally (e.g. `ctx.debug` -> `log` ->
`send_log_message`) to serve older sessions.

Author: Kludex

README.v2.md

@@ -360,7 +360,7 @@ mcp = MCPServer(name="Progress Example")
 @mcp.tool()
 async def long_running_task(task_name: str, ctx: Context, steps: int = 5) -> str:
     """Execute a task with progress updates."""
-    await ctx.info(f"Starting: {task_name}")
+    await ctx.info(f"Starting: {task_name}")  # pyright: ignore[reportDeprecated]
 
     for i in range(steps):
         progress = (i + 1) / steps
@@ -369,7 +369,7 @@ async def long_running_task(task_name: str, ctx: Context, steps: int = 5) -> str
             total=1.0,
             message=f"Step {i + 1}/{steps}",
         )
-        await ctx.debug(f"Completed step {i + 1}")
+        await ctx.debug(f"Completed step {i + 1}")  # pyright: ignore[reportDeprecated]
 
     return f"Task '{task_name}' completed"
 ```
@@ -707,7 +707,7 @@ mcp = MCPServer(name="Progress Example")
 @mcp.tool()
 async def long_running_task(task_name: str, ctx: Context, steps: int = 5) -> str:
     """Execute a task with progress updates."""
-    await ctx.info(f"Starting: {task_name}")
+    await ctx.info(f"Starting: {task_name}")  # pyright: ignore[reportDeprecated]
 
     for i in range(steps):
         progress = (i + 1) / steps
@@ -716,7 +716,7 @@ async def long_running_task(task_name: str, ctx: Context, steps: int = 5) -> str
             total=1.0,
             message=f"Step {i + 1}/{steps}",
         )
-        await ctx.debug(f"Completed step {i + 1}")
+        await ctx.debug(f"Completed step {i + 1}")  # pyright: ignore[reportDeprecated]
 
     return f"Task '{task_name}' completed"
 ```
@@ -948,7 +948,7 @@ async def generate_poem(topic: str, ctx: Context) -> str:
     """Generate a poem using LLM sampling."""
     prompt = f"Write a short poem about {topic}"
 
-    result = await ctx.session.create_message(
+    result = await ctx.session.create_message(  # pyright: ignore[reportDeprecated]
         messages=[
             SamplingMessage(
                 role="user",
@@ -982,10 +982,10 @@ mcp = MCPServer(name="Notifications Example")
 async def process_data(data: str, ctx: Context) -> str:
     """Process data with logging."""
     # Different log levels
-    await ctx.debug(f"Debug: Processing '{data}'")
-    await ctx.info("Info: Starting processing")
-    await ctx.warning("Warning: This is experimental")
-    await ctx.error("Error: (This is just a demo)")
+    await ctx.debug(f"Debug: Processing '{data}'")  # pyright: ignore[reportDeprecated]
+    await ctx.info("Info: Starting processing")  # pyright: ignore[reportDeprecated]
+    await ctx.warning("Warning: This is experimental")  # pyright: ignore[reportDeprecated]
+    await ctx.error("Error: (This is just a demo)")  # pyright: ignore[reportDeprecated]
 
     # Notify about resource changes
     await ctx.session.send_resource_list_changed()

docs/migration.md

@@ -1216,7 +1216,17 @@ Tasks are expected to return as a separate MCP extension in a future release.
 
 ## Deprecations
 
-<!-- Add deprecations below -->
+### Roots, Sampling, and Logging methods deprecated (SEP-2577)
+
+[SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) deprecates the Roots, Sampling, and Logging features as of the 2026-07-28 spec. The deprecation is advisory only: there are no wire-level changes, capability negotiation is unchanged, and every method keeps working for sessions negotiating 2025-11-25 and earlier.
+
+The user-facing methods for these features now carry `typing_extensions.deprecated`, so type checkers, IDEs, and the runtime surface a deprecation warning where they are called:
+
+- Sampling: `ServerSession.create_message()`, `ClientPeer.sample()`
+- 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()`
+
+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
 

examples/servers/everything-server/mcp_everything_server/server.py

@@ -143,13 +143,13 @@ def test_multiple_content_types() -> list[TextContent | ImageContent | EmbeddedR
 @mcp.tool()
 async def test_tool_with_logging(ctx: Context) -> str:
     """Tests tool that emits log messages during execution"""
-    await ctx.info("Tool execution started")
+    await ctx.info("Tool execution started")  # pyright: ignore[reportDeprecated]
     await asyncio.sleep(0.05)
 
-    await ctx.info("Tool processing data")
+    await ctx.info("Tool processing data")  # pyright: ignore[reportDeprecated]
     await asyncio.sleep(0.05)
 
-    await ctx.info("Tool execution completed")
+    await ctx.info("Tool execution completed")  # pyright: ignore[reportDeprecated]
     return "Tool with logging executed successfully"
 
 
@@ -176,7 +176,7 @@ async def test_sampling(prompt: str, ctx: Context) -> str:
     """Tests server-initiated sampling (LLM completion request)"""
     try:
         # Request sampling from client
-        result = await ctx.session.create_message(
+        result = await ctx.session.create_message(  # pyright: ignore[reportDeprecated]
             messages=[SamplingMessage(role="user", content=TextContent(type="text", text=prompt))],
             max_tokens=100,
         )
@@ -314,13 +314,13 @@ def test_error_handling() -> str:
 @mcp.tool()
 async def test_reconnection(ctx: Context) -> str:
     """Tests SSE polling by closing stream mid-call (SEP-1699)"""
-    await ctx.info("Before disconnect")
+    await ctx.info("Before disconnect")  # pyright: ignore[reportDeprecated]
 
     await ctx.close_sse_stream()
 
     await asyncio.sleep(0.2)  # Wait for client to reconnect
 
-    await ctx.info("After reconnect")
+    await ctx.info("After reconnect")  # pyright: ignore[reportDeprecated]
     return "Reconnection test completed"
 
 

examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/server.py

@@ -49,7 +49,7 @@ async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequ
 
     # Send the specified number of notifications with the given interval
     for i in range(count):
-        await ctx.session.send_log_message(
+        await ctx.session.send_log_message(  # pyright: ignore[reportDeprecated]
             level="info",
             data=f"Notification {i + 1}/{count} from caller: {caller}",
             logger="notification_stream",

examples/servers/simple-streamablehttp/mcp_simple_streamablehttp/server.py

@@ -54,7 +54,7 @@ async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequ
     for i in range(count):
         # Include more detailed message for resumability demonstration
         notification_msg = f"[{i + 1}/{count}] Event from '{caller}' - Use Last-Event-ID to resume if disconnected"
-        await ctx.session.send_log_message(
+        await ctx.session.send_log_message(  # pyright: ignore[reportDeprecated]
             level="info",
             data=notification_msg,
             logger="notification_stream",

examples/servers/sse-polling-demo/mcp_sse_polling_demo/server.py

@@ -74,7 +74,7 @@ async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequ
                 content=[types.TextContent(type="text", text="Error: checkpoint_every must be between 1 and 20")]
             )
 
-        await ctx.session.send_log_message(
+        await ctx.session.send_log_message(  # pyright: ignore[reportDeprecated]
             level="info",
             data=f"Starting batch processing of {items} items...",
             logger="process_batch",
@@ -86,7 +86,7 @@ async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequ
             await anyio.sleep(0.5)
 
             # Report progress
-            await ctx.session.send_log_message(
+            await ctx.session.send_log_message(  # pyright: ignore[reportDeprecated]
                 level="info",
                 data=f"[{i}/{items}] Processing item {i}",
                 logger="process_batch",
@@ -95,7 +95,7 @@ async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequ
 
             # Checkpoint: close stream to trigger client reconnect
             if i % checkpoint_every == 0 and i < items:
-                await ctx.session.send_log_message(
+                await ctx.session.send_log_message(  # pyright: ignore[reportDeprecated]
                     level="info",
                     data=f"Checkpoint at item {i} - closing SSE stream for polling",
                     logger="process_batch",

examples/snippets/servers/notifications.py

@@ -7,10 +7,10 @@
 async def process_data(data: str, ctx: Context) -> str:
     """Process data with logging."""
     # Different log levels
-    await ctx.debug(f"Debug: Processing '{data}'")
-    await ctx.info("Info: Starting processing")
-    await ctx.warning("Warning: This is experimental")
-    await ctx.error("Error: (This is just a demo)")
+    await ctx.debug(f"Debug: Processing '{data}'")  # pyright: ignore[reportDeprecated]
+    await ctx.info("Info: Starting processing")  # pyright: ignore[reportDeprecated]
+    await ctx.warning("Warning: This is experimental")  # pyright: ignore[reportDeprecated]
+    await ctx.error("Error: (This is just a demo)")  # pyright: ignore[reportDeprecated]
 
     # Notify about resource changes
     await ctx.session.send_resource_list_changed()

examples/snippets/servers/sampling.py

@@ -9,7 +9,7 @@ async def generate_poem(topic: str, ctx: Context) -> str:
     """Generate a poem using LLM sampling."""
     prompt = f"Write a short poem about {topic}"
 
-    result = await ctx.session.create_message(
+    result = await ctx.session.create_message(  # pyright: ignore[reportDeprecated]
         messages=[
             SamplingMessage(
                 role="user",

examples/snippets/servers/tool_progress.py

@@ -6,7 +6,7 @@
 @mcp.tool()
 async def long_running_task(task_name: str, ctx: Context, steps: int = 5) -> str:
     """Execute a task with progress updates."""
-    await ctx.info(f"Starting: {task_name}")
+    await ctx.info(f"Starting: {task_name}")  # pyright: ignore[reportDeprecated]
 
     for i in range(steps):
         progress = (i + 1) / steps
@@ -15,6 +15,6 @@ async def long_running_task(task_name: str, ctx: Context, steps: int = 5) -> str
             total=1.0,
             message=f"Step {i + 1}/{steps}",
         )
-        await ctx.debug(f"Completed step {i + 1}")
+        await ctx.debug(f"Completed step {i + 1}")  # pyright: ignore[reportDeprecated]
 
     return f"Task '{task_name}' completed"

pyproject.toml

@@ -213,6 +213,10 @@ filterwarnings = [
     "error",
     # pywin32 internal deprecation warning
     "ignore:getargs.*The 'u' format is deprecated:DeprecationWarning",
+    # 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",
 ]
 
 [tool.markdown.lint]