Merge branch 'main' into docs/stateless-http-clarification

Author: dgenio

README.md

@@ -948,8 +948,9 @@ async def generate_poem(topic: str, ctx: Context[ServerSession, None]) -> str:
         max_tokens=100,
     )
 
-    if all(c.type == "text" for c in result.content_as_list):
-        return "\n".join(c.text for c in result.content_as_list if c.type == "text")
+    # Since we're not passing tools param, result.content is single content
+    if result.content.type == "text":
+        return result.content.text
     return str(result.content)
 ```
 
@@ -2657,6 +2658,7 @@ MCP servers declare capabilities during initialization:
 ## Documentation
 
 - [API Reference](https://modelcontextprotocol.github.io/python-sdk/api/)
+- [Experimental Features (Tasks)](https://modelcontextprotocol.github.io/python-sdk/experimental/tasks/)
 - [Model Context Protocol documentation](https://modelcontextprotocol.io)
 - [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest)
 - [Officially supported servers](https://github.com/modelcontextprotocol/servers)

docs/experimental/index.md

@@ -0,0 +1,43 @@
+# Experimental Features
+
+!!! warning "Experimental APIs"
+
+    The features in this section are experimental and may change without notice.
+    They track the evolving MCP specification and are not yet stable.
+
+This section documents experimental features in the MCP Python SDK. These features
+implement draft specifications that are still being refined.
+
+## Available Experimental Features
+
+### [Tasks](tasks.md)
+
+Tasks enable asynchronous execution of MCP operations. Instead of waiting for a
+long-running operation to complete, the server returns a task reference immediately.
+Clients can then poll for status updates and retrieve results when ready.
+
+Tasks are useful for:
+
+- **Long-running computations** that would otherwise block
+- **Batch operations** that process many items
+- **Interactive workflows** that require user input (elicitation) or LLM assistance (sampling)
+
+## Using Experimental APIs
+
+Experimental features are accessed via the `.experimental` property:
+
+```python
+# Server-side
+@server.experimental.get_task()
+async def handle_get_task(request: GetTaskRequest) -> GetTaskResult:
+    ...
+
+# Client-side
+result = await session.experimental.call_tool_as_task("tool_name", {"arg": "value"})
+```
+
+## Providing Feedback
+
+Since these features are experimental, feedback is especially valuable. If you encounter
+issues or have suggestions, please open an issue on the
+[python-sdk repository](https://github.com/modelcontextprotocol/python-sdk/issues).