docs: add code fences to Example: docstring blocks

Docstrings using `Example:` sections had indented code without
triple-backtick fences, causing mkdocs to render them as prose
paragraphs instead of code blocks.

- Wrap all unfenced example code in `python ... ` blocks
- Rename `Example usage:` and `Example Usage:` to `Example:` so griffe
  recognizes them as proper docstring sections
- Normalize `Examples:` (plural) to `Example:` (singular) for consistent
  mkdocs rendering
- Split multi-example blocks into separate fenced blocks with prose
  labels where appropriate (`_httpx_utils.py`, `server.py`,
  `experimental.py`, `task_support.py`)

Author: jonathanhefner

src/mcp/client/experimental/task_handlers.py

@@ -187,11 +187,13 @@ class ExperimentalTaskHandlers:
     WARNING: These APIs are experimental and may change without notice.
 
     Example:
+        ```python
         handlers = ExperimentalTaskHandlers(
             get_task=my_get_task_handler,
             list_tasks=my_list_tasks_handler,
         )
         session = ClientSession(..., experimental_task_handlers=handlers)
+        ```
     """
 
     # Pure task request handlers

src/mcp/client/experimental/tasks.py

@@ -5,6 +5,7 @@
 WARNING: These APIs are experimental and may change without notice.
 
 Example:
+    ```python
     # Call a tool as a task
     result = await session.experimental.call_tool_as_task("tool_name", {"arg": "value"})
     task_id = result.task.task_id
@@ -21,6 +22,7 @@
 
     # Cancel a task
     await session.experimental.cancel_task(task_id)
+    ```
 """
 
 from collections.abc import AsyncIterator
@@ -72,6 +74,7 @@ async def call_tool_as_task(
             CreateTaskResult containing the task reference
 
         Example:
+            ```python
             # Create task
             result = await session.experimental.call_tool_as_task(
                 "long_running_tool", {"input": "data"}
@@ -87,6 +90,7 @@ async def call_tool_as_task(
 
             # Get result
             final = await session.experimental.get_task_result(task_id, CallToolResult)
+            ```
         """
         return await self._session.send_request(
             types.CallToolRequest(
@@ -189,6 +193,7 @@ async def poll_task(self, task_id: str) -> AsyncIterator[types.GetTaskResult]:
             GetTaskResult for each poll
 
         Example:
+            ```python
             async for status in session.experimental.poll_task(task_id):
                 print(f"Status: {status.status}")
                 if status.status == "input_required":
@@ -197,6 +202,7 @@ async def poll_task(self, task_id: str) -> AsyncIterator[types.GetTaskResult]:
 
             # Task is now terminal, get the result
             result = await session.experimental.get_task_result(task_id, CallToolResult)
+            ```
         """
         async for status in poll_until_terminal(self.get_task, task_id):
             yield status

src/mcp/client/session.py

@@ -206,8 +206,10 @@ def experimental(self) -> ExperimentalClientFeatures:
             These APIs are experimental and may change without notice.
 
         Example:
+            ```python
             status = await session.experimental.get_task(task_id)
             result = await session.experimental.get_task_result(task_id, CallToolResult)
+            ```
         """
         if self._experimental_features is None:
             self._experimental_features = ExperimentalClientFeatures(self)

src/mcp/client/session_group.py

@@ -91,13 +91,14 @@ class ClientSessionGroup:
     For auxiliary handlers, such as resource subscription, this is delegated to
     the client and can be accessed via the session.
 
-    Example Usage:
+    Example:
+        ```python
         name_fn = lambda name, server_info: f"{(server_info.name)}_{name}"
         async with ClientSessionGroup(component_name_hook=name_fn) as group:
             for server_param in server_params:
                 await group.connect_to_server(server_param)
             ...
-
+        ```
     """
 
     class _ComponentNames(BaseModel):

src/mcp/server/experimental/request_context.py

@@ -160,6 +160,7 @@ async def run_task(
             RuntimeError: If task support is not enabled or task_metadata is missing
 
         Example:
+            ```python
             async def handle_tool(ctx: RequestContext, params: CallToolRequestParams) -> CallToolResult:
                 async def work(task: ServerTaskContext) -> CallToolResult:
                     result = await task.elicit(
@@ -170,6 +171,7 @@ async def work(task: ServerTaskContext) -> CallToolResult:
                     return CallToolResult(content=[TextContent(text="Done" if confirmed else "Cancelled")])
 
                 return await ctx.experimental.run_task(work)
+            ```
 
         WARNING: This API is experimental and may change without notice.
         """

src/mcp/server/experimental/task_context.py

@@ -56,6 +56,7 @@ class ServerTaskContext:
     - Status notifications via the session
 
     Example:
+        ```python
         async def my_task_work(task: ServerTaskContext) -> CallToolResult:
             await task.update_status("Starting...")
 
@@ -68,6 +69,7 @@ async def my_task_work(task: ServerTaskContext) -> CallToolResult:
                 return CallToolResult(content=[TextContent(text="Done!")])
             else:
                 return CallToolResult(content=[TextContent(text="Cancelled")])
+        ```
     """
 
     def __init__(

src/mcp/server/experimental/task_support.py

@@ -31,14 +31,20 @@ class TaskSupport:
     - Manages a task group for background task execution
 
     Example:
-        # Simple in-memory setup
+        Simple in-memory setup:
+
+        ```python
         server.experimental.enable_tasks()
+        ```
+
+        Custom store/queue for distributed systems:
 
-        # Custom store/queue for distributed systems
+        ```python
         server.experimental.enable_tasks(
             store=RedisTaskStore(redis_url),
             queue=RedisTaskMessageQueue(redis_url),
         )
+        ```
     """
 
     store: TaskStore

src/mcp/server/lowlevel/experimental.py

@@ -118,14 +118,20 @@ def enable_tasks(
             The TaskSupport configuration object
 
         Example:
-            # Simple in-memory setup
+            Simple in-memory setup:
+
+            ```python
             server.experimental.enable_tasks()
+            ```
+
+            Custom store/queue for distributed systems:
 
-            # Custom store/queue for distributed systems
+            ```python
             server.experimental.enable_tasks(
                 store=RedisTaskStore(redis_url),
                 queue=RedisTaskMessageQueue(redis_url),
             )
+            ```
 
         WARNING: This API is experimental and may change without notice.
         """

src/mcp/server/mcpserver/server.py

@@ -535,19 +535,25 @@ def tool(
                 - If False, unconditionally creates an unstructured tool
 
         Example:
+            ```python
             @server.tool()
             def my_tool(x: int) -> str:
                 return str(x)
+            ```
 
+            ```python
             @server.tool()
             async def tool_with_context(x: int, ctx: Context) -> str:
                 await ctx.info(f"Processing {x}")
                 return str(x)
+            ```
 
+            ```python
             @server.tool()
             async def async_tool(x: int, context: Context) -> str:
                 await context.report_progress(50, 100)
                 return str(x)
+            ```
         """
         # Check if user passed function directly instead of calling decorator
         if callable(name):
@@ -579,12 +585,14 @@ def completion(self):
         - context: Optional CompletionContext with previously resolved arguments
 
         Example:
+            ```python
             @mcp.completion()
             async def handle_completion(ref, argument, context):
                 if isinstance(ref, ResourceTemplateReference):
                     # Return completions based on ref, argument, and context
                     return Completion(values=["option1", "option2"])
                 return None
+            ```
         """
 
         def decorator(func: _CallableT) -> _CallableT:
@@ -647,6 +655,7 @@ def resource(
             meta: Optional metadata dictionary for the resource
 
         Example:
+            ```python
             @server.resource("resource://my-resource")
             def get_data() -> str:
                 return "Hello, world!"
@@ -664,6 +673,7 @@ def get_weather(city: str) -> str:
             async def get_weather(city: str) -> str:
                 data = await fetch_weather(city)
                 return f"Weather for {city}: {data}"
+            ```
         """
         # Check if user passed function directly instead of calling decorator
         if callable(uri):
@@ -747,6 +757,7 @@ def prompt(
             icons: Optional list of icons for the prompt
 
         Example:
+            ```python
             @server.prompt()
             def analyze_table(table_name: str) -> list[Message]:
                 schema = read_table_schema(table_name)
@@ -772,6 +783,7 @@ async def analyze_file(path: str) -> list[Message]:
                         }
                     }
                 ]
+            ```
         """
         # Check if user passed function directly instead of calling decorator
         if callable(name):
@@ -813,9 +825,11 @@ def custom_route(
             include_in_schema: Whether to include in OpenAPI schema, defaults to True
 
         Example:
+            ```python
             @server.custom_route("/health", methods=["GET"])
             async def health_check(request: Request) -> Response:
                 return JSONResponse({"status": "ok"})
+            ```
         """
 
         def decorator(  # pragma: no cover

src/mcp/server/sse.py

@@ -2,8 +2,8 @@
 
 This module implements a Server-Sent Events (SSE) transport layer for MCP servers.
 
-Example usage:
-```
+Example:
+    ```python
     # Create an SSE transport at an endpoint
     sse = SseServerTransport("/messages/")
 
@@ -27,7 +27,7 @@ async def handle_sse(request):
     # Create and run Starlette app
     starlette_app = Starlette(routes=routes)
     uvicorn.run(starlette_app, host="127.0.0.1", port=port)
-```
+    ```
 
 Note: The handle_sse function must return a Response to avoid a
 "TypeError: 'NoneType' object is not callable" error when client disconnects. The example above returns