From b8a90b847ab06d781fdc9696c8c250af6bcfde5b Mon Sep 17 00:00:00 2001
From: Marcelo Trylesinski <marcelotryle@gmail.com>
Date: Thu, 15 Jan 2026 11:07:47 +0100
Subject: [PATCH] docs: add migrations page

---
 docs/migration.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml        |  1 +
 2 files changed, 70 insertions(+)
 create mode 100644 docs/migration.md

diff --git a/docs/migration.md b/docs/migration.md
new file mode 100644
index 000000000..881014a93
--- /dev/null
+++ b/docs/migration.md
@@ -0,0 +1,69 @@
+# Migration Guide: v1 to v2
+
+This guide covers the breaking changes introduced in v2 of the MCP Python SDK and how to update your code.
+
+## Overview
+
+Version 2 of the MCP Python SDK introduces several breaking changes to improve the API, align with the MCP specification, and provide better type safety.
+
+## Breaking Changes
+
+### `streamablehttp_client` removed
+
+The deprecated `streamablehttp_client` function has been removed. Use `streamable_http_client` instead.
+
+**Before (v1):**
+
+```python
+from mcp.client.streamable_http import streamablehttp_client
+
+async with streamablehttp_client(
+    url="http://localhost:8000/mcp",
+    headers={"Authorization": "Bearer token"},
+    timeout=30,
+    sse_read_timeout=300,
+    auth=my_auth,
+) as (read_stream, write_stream, get_session_id):
+    ...
+```
+
+**After (v2):**
+
+```python
+import httpx
+from mcp.client.streamable_http import streamable_http_client
+
+# Configure headers, timeout, and auth on the httpx.AsyncClient
+http_client = httpx.AsyncClient(
+    headers={"Authorization": "Bearer token"},
+    timeout=httpx.Timeout(30, read=300),
+    auth=my_auth,
+)
+
+async with http_client:
+    async with streamable_http_client(
+        url="http://localhost:8000/mcp",
+        http_client=http_client,
+    ) as (read_stream, write_stream, get_session_id):
+        ...
+```
+
+### `StreamableHTTPTransport` parameters removed
+
+The `headers`, `timeout`, `sse_read_timeout`, and `auth` parameters have been removed from `StreamableHTTPTransport`. Configure these on the `httpx.AsyncClient` instead (see example above).
+
+## Deprecations
+
+<!-- Add deprecations below -->
+
+## New Features
+
+<!-- Add new features below -->
+
+## Need Help?
+
+If you encounter issues during migration:
+
+1. Check the [API Reference](api.md) for updated method signatures
+2. Review the [examples](https://github.com/modelcontextprotocol/python-sdk/tree/main/examples) for updated usage patterns
+3. Open an issue on [GitHub](https://github.com/modelcontextprotocol/python-sdk/issues) if you find a bug or need further assistance
diff --git a/mkdocs.yml b/mkdocs.yml
index 7ae8000c7..3019f5214 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,6 +13,7 @@ site_url: https://modelcontextprotocol.github.io/python-sdk
 nav:
   - Introduction: index.md
   - Installation: installation.md
+  - Migration Guide: migration.md
   - Documentation:
       - Concepts: concepts.md
       - Low-Level Server: low-level-server.md