Deprecate Connection.log for consistency with the logging capability

Kludex · Kludex · commit 7ee2e0d362b6 · 2026-06-20T18:11:50.000+02:00
Address PR review: `Connection.log()` sends the same `notifications/message`
the logging capability covers and `Context.log`'s docstring steers users to it,
so it now carries the same SEP-2577 `@deprecated` marker. Its two test call
sites get `# pyright: ignore[reportDeprecated]`, and the migration guide lists
it among the deprecated logging entry points.
diff --git a/README.v2.md b/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"
 ```
@@ -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()
diff --git a/docs/migration.md b/docs/migration.md
@@ -1224,7 +1224,7 @@ The user-facing methods for these features now carry `typing_extensions.deprecat
 
 - 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 `MCPServer` `Context.log()`. The `Context.debug()` / `info()` / `warning()` / `error()` helpers delegate to `log()`, so they warn through it rather than carrying their own marker.
+- Logging: `ServerSession.send_log_message()`, `Connection.log()`, `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:
 
diff --git a/examples/servers/everything-server/mcp_everything_server/server.py b/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"
 
 
@@ -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"
 
 
diff --git a/examples/snippets/servers/notifications.py b/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()
diff --git a/examples/snippets/servers/tool_progress.py b/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"
diff --git a/src/mcp/server/connection.py b/src/mcp/server/connection.py
@@ -20,9 +20,10 @@
 
 import anyio
 from pydantic import BaseModel
+from typing_extensions import deprecated
 
 from mcp.shared.dispatcher import CallOptions, Outbound
-from mcp.shared.exceptions import NoBackChannelError
+from mcp.shared.exceptions import MCPDeprecationWarning, NoBackChannelError
 from mcp.shared.peer import Meta, dump_params
 from mcp.types import (
     ClientCapabilities,
@@ -209,6 +210,7 @@ async def ping(self, *, meta: Meta | None = None, opts: CallOptions | None = Non
         """
         await self.send_raw_request("ping", dump_params(None, meta), opts)
 
+    @deprecated("The logging capability 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 `notifications/message` log entry on the standalone stream. Best-effort."""
         params: dict[str, Any] = {"level": level, "data": data}
diff --git a/src/mcp/server/mcpserver/context.py b/src/mcp/server/mcpserver/context.py
@@ -268,18 +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("The logging capability 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("The logging capability 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("The logging capability 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("The logging capability 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]
diff --git a/tests/interaction/mcpserver/test_context.py b/tests/interaction/mcpserver/test_context.py
@@ -41,10 +41,10 @@ async def test_context_logging_helpers_send_log_notifications(connect: Connect)
 
     @mcp.tool()
     async def narrate(ctx: Context) -> str:
-        await ctx.debug("d")
-        await ctx.info("i")
-        await ctx.warning("w")
-        await ctx.error("e")
+        await ctx.debug("d")  # pyright: ignore[reportDeprecated]
+        await ctx.info("i")  # pyright: ignore[reportDeprecated]
+        await ctx.warning("w")  # pyright: ignore[reportDeprecated]
+        await ctx.error("e")  # pyright: ignore[reportDeprecated]
         return "done"
 
     async def collect(params: LoggingMessageNotificationParams) -> None:
@@ -136,7 +136,7 @@ async def test_report_progress_without_a_progress_token_sends_nothing(connect: C
     @mcp.tool()
     async def mill(ctx: Context) -> str:
         await ctx.report_progress(1, 3)
-        await ctx.info("milling done")
+        await ctx.info("milling done")  # pyright: ignore[reportDeprecated]
         return "milled"
 
     async def collect(message: IncomingMessage) -> None:
@@ -250,8 +250,8 @@ async def test_set_logging_level_is_rejected_and_messages_are_never_filtered(con
 
     @mcp.tool()
     async def chatter(ctx: Context) -> str:
-        await ctx.debug("noise")
-        await ctx.error("signal")
+        await ctx.debug("noise")  # pyright: ignore[reportDeprecated]
+        await ctx.error("signal")  # pyright: ignore[reportDeprecated]
         return "done"
 
     async def collect(params: LoggingMessageNotificationParams) -> None:
diff --git a/tests/interaction/mcpserver/test_tools.py b/tests/interaction/mcpserver/test_tools.py
@@ -414,7 +414,7 @@ def doomed() -> str:
     async def grow(ctx: Context) -> str:
         mcp.add_tool(extra, name="extra")
         mcp.remove_tool("doomed")
-        await ctx.info("tool set changed")
+        await ctx.info("tool set changed")  # pyright: ignore[reportDeprecated]
         return "mutated"
 
     async def collect(message: IncomingMessage) -> None:
diff --git a/tests/interaction/transports/test_flows.py b/tests/interaction/transports/test_flows.py
@@ -32,7 +32,7 @@ async def test_concurrent_clients_on_one_stateful_server_receive_only_their_own_
     @mcp.tool()
     async def announce(label: str, ctx: Context) -> str:
         """Emit one info-level log carrying the caller's label, then return it."""
-        await ctx.info(label)
+        await ctx.info(label)  # pyright: ignore[reportDeprecated]
         return label
 
     received_a: list[object] = []
diff --git a/tests/interaction/transports/test_hosting_resume.py b/tests/interaction/transports/test_hosting_resume.py
@@ -55,7 +55,7 @@ def _counting_server() -> MCPServer:
     async def count(ctx: Context, n: int) -> str:
         """Emit n log notifications related to this call, plus one unrelated resource update."""
         for i in range(1, n + 1):
-            await ctx.info(f"tick {i}")
+            await ctx.info(f"tick {i}")  # pyright: ignore[reportDeprecated]
         await ctx.session.send_resource_updated("file:///elsewhere.txt")
         return f"counted to {n}"
 
@@ -138,10 +138,10 @@ async def test_get_with_last_event_id_replays_only_that_streams_missed_events()
     @mcp.tool()
     async def count(ctx: Context) -> str:
         """Emit one related notification, wait for the test, then emit two more plus an unrelated one."""
-        await ctx.info("tick 1")
+        await ctx.info("tick 1")  # pyright: ignore[reportDeprecated]
         await release.wait()
-        await ctx.info("tick 2")
-        await ctx.info("tick 3")
+        await ctx.info("tick 2")  # pyright: ignore[reportDeprecated]
+        await ctx.info("tick 3")  # pyright: ignore[reportDeprecated]
         await ctx.session.send_resource_updated("file:///elsewhere.txt")
         return "counted"
 
@@ -219,7 +219,7 @@ async def hold(ctx: Context) -> str:
         """Signal start, wait for the test, signal completion."""
         started.set()
         await release.wait()
-        await ctx.info("released")
+        await ctx.info("released")  # pyright: ignore[reportDeprecated]
         finished.set()
         return "held"
 
@@ -263,10 +263,10 @@ async def test_a_call_whose_stream_the_server_closes_is_resumed_by_the_client()
     @mcp.tool()
     async def interrupt(ctx: Context) -> str:
         """Emit, close this call's SSE stream, then emit again after the test releases the gate."""
-        await ctx.info("before close")
+        await ctx.info("before close")  # pyright: ignore[reportDeprecated]
         await ctx.close_sse_stream()
         await gate.wait()
-        await ctx.info("after close")
+        await ctx.info("after close")  # pyright: ignore[reportDeprecated]
         done.set()
         return "resumed"
 
@@ -321,9 +321,9 @@ async def test_a_captured_resumption_token_replays_missed_messages_on_a_new_conn
     @mcp.tool()
     async def hold(ctx: Context) -> str:
         """Emit one notification, wait for the test, emit another, return."""
-        await ctx.info("first")
+        await ctx.info("first")  # pyright: ignore[reportDeprecated]
         await release.wait()
-        await ctx.info("second")
+        await ctx.info("second")  # pyright: ignore[reportDeprecated]
         return "done"
 
     async def on_token(token: str) -> None:
diff --git a/tests/interaction/transports/test_streamable_http.py b/tests/interaction/transports/test_streamable_http.py
@@ -55,7 +55,7 @@ async def ask(ctx: Context) -> str:
     @mcp.tool()
     async def announce(ctx: Context) -> str:
         """Send one notification related to this request and one that is not."""
-        await ctx.info("about to announce")
+        await ctx.info("about to announce")  # pyright: ignore[reportDeprecated]
         await ctx.session.send_resource_updated("file:///watched.txt")
         return "announced"
 
diff --git a/tests/server/mcpserver/test_server.py b/tests/server/mcpserver/test_server.py
@@ -1110,10 +1110,10 @@ async def test_context_logging(self):
         mcp = MCPServer()
 
         async def logging_tool(msg: str, ctx: Context) -> str:
-            await ctx.debug("Debug message")
-            await ctx.info("Info message")
-            await ctx.warning("Warning message")
-            await ctx.error("Error message")
+            await ctx.debug("Debug message")  # pyright: ignore[reportDeprecated]
+            await ctx.info("Info message")  # pyright: ignore[reportDeprecated]
+            await ctx.warning("Warning message")  # pyright: ignore[reportDeprecated]
+            await ctx.error("Error message")  # pyright: ignore[reportDeprecated]
             return f"Logged messages for {msg}"
 
         mcp.add_tool(logging_tool)
diff --git a/tests/server/test_connection.py b/tests/server/test_connection.py
@@ -206,7 +206,7 @@ async def test_connection_ping_sends_ping_on_standalone():
 async def test_connection_log_sends_logging_message_notification():
     out = StubOutbound()
     conn = Connection(out, has_standalone_channel=True)
-    await conn.log("info", {"k": "v"}, logger="my.logger")
+    await conn.log("info", {"k": "v"}, logger="my.logger")  # pyright: ignore[reportDeprecated]
     method, params = out.notifications[0]
     assert method == "notifications/message"
     assert params is not None
@@ -219,7 +219,7 @@ async def test_connection_log_sends_logging_message_notification():
 async def test_connection_log_with_meta_includes_meta_in_params():
     out = StubOutbound()
     conn = Connection(out, has_standalone_channel=True)
-    await conn.log("info", "x", meta={"traceId": "abc"})
+    await conn.log("info", "x", meta={"traceId": "abc"})  # pyright: ignore[reportDeprecated]
     _, params = out.notifications[0]
     assert params is not None
     assert params["_meta"] == {"traceId": "abc"}
