docs: comprehensive feature documentation for SEP-1730 Tier 1

Add documentation for all 48 non-experimental MCP features, closing the
documentation gap for SEP-1730 Tier 1 compliance.

New files:
- docs/server.md: tools (all result types, change notifications), resources
  (text/binary, templates, subscribing/unsubscribing, change notifications),
  prompts (simple/args/embedded resources/images, change notifications),
  logging (messages + set level), completions, sampling, elicitation
  (form/URL/schema/defaults/enums/complete notification), transports
- docs/client.md: roots (listing + change notifications), transports
  (stdio/HTTP/SSE), using server features (tools/resources/prompts/completions)
- docs/protocol.md: ping, progress, cancellation, pagination, capability
  negotiation, protocol version negotiation, JSON Schema 2020-12

Modified:
- README.md: added links to new docs
- docs/index.md: added Guides section linking all doc files

All 66 code snippets verified against SDK source and runtime-tested.

Author: felixweinberger

README.md

@@ -2547,6 +2547,13 @@ MCP servers declare capabilities during initialization:
 
 ## Documentation
 
+- [Building Servers](docs/server.md) - tools, resources, prompts, logging, elicitation, sampling, completions, and transports
+- [Writing Clients](docs/client.md) - connecting to servers, roots, and client transports
+- [Protocol Features](docs/protocol.md) - ping, progress, cancellation, pagination, capability negotiation
+- [Authorization](docs/authorization.md) - OAuth 2.1, token verification, and client authentication
+- [Low-Level Server](docs/low-level-server.md) - direct handler registration for advanced use cases
+- [Testing](docs/testing.md) - in-memory transport testing with pytest
+- [Concepts](docs/concepts.md) - architecture overview
 - [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)

docs/client.md

@@ -0,0 +1,333 @@
+# Writing MCP Clients
+
+This guide covers building MCP clients -- programs that connect to MCP servers and use
+their tools, resources, prompts, and other capabilities.
+
+## Client Session Basics
+
+Every MCP client starts by opening a transport connection and creating a `ClientSession`.
+The session handles the MCP protocol lifecycle: initialization, request/response exchange,
+and shutdown.
+
+```python
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+server_params = StdioServerParameters(command="uv", args=["run", "my-server"])
+
+async with stdio_client(server_params) as (read_stream, write_stream):
+    async with ClientSession(read_stream, write_stream) as session:
+        await session.initialize()
+        # Session is now ready to use
+```
+
+## Transports
+
+### stdio Transport
+
+The `stdio_client` context manager spawns a subprocess and communicates over
+stdin/stdout. This is the most common transport for local servers.
+
+```python
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+server_params = StdioServerParameters(
+    command="uv",
+    args=["run", "my-server"],
+    env={"API_KEY": "secret"},  # merged with safe defaults
+    cwd="/path/to/working/dir",
+)
+
+async with stdio_client(server_params) as (read_stream, write_stream):
+    async with ClientSession(read_stream, write_stream) as session:
+        await session.initialize()
+```
+
+### Streamable HTTP Transport
+
+The `streamablehttp_client` connects to a remote server over HTTP, with optional
+SSE streaming for server-to-client messages.
+
+```python
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+async with streamablehttp_client("http://localhost:8000/mcp") as (
+    read_stream,
+    write_stream,
+    get_session_id,
+):
+    async with ClientSession(read_stream, write_stream) as session:
+        await session.initialize()
+        # get_session_id() returns the server-assigned session ID, or None
+```
+
+### SSE Transport (Legacy)
+
+The `sse_client` context manager connects to a server using the legacy
+Server-Sent Events transport. This transport is deprecated in favor of Streamable
+HTTP, but remains available for backward compatibility with older servers.
+
+```python
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+
+async with sse_client(
+    url="http://localhost:8000/sse",
+    headers={"Authorization": "Bearer token"},
+    timeout=5,              # HTTP timeout for regular operations
+    sse_read_timeout=300,   # how long to wait for a new SSE event
+) as (read_stream, write_stream):
+    async with ClientSession(read_stream, write_stream) as session:
+        await session.initialize()
+```
+
+## Roots
+
+Roots tell the server which directories or files the client is making available.
+A server may request the list of roots at any time during a session.
+
+### Providing Roots
+
+Supply a `list_roots_callback` when constructing the `ClientSession`. The callback
+receives a `RequestContext` and must return a `ListRootsResult`.
+
+```python
+from mcp import ClientSession, types
+from mcp.client.stdio import stdio_client
+from mcp.shared.context import RequestContext
+
+async def handle_list_roots(
+    context: RequestContext[ClientSession, None],
+) -> types.ListRootsResult:
+    return types.ListRootsResult(
+        roots=[
+            types.Root(
+                uri="file:///home/user/project",
+                name="My Project",
+            ),
+            types.Root(
+                uri="file:///home/user/data",
+                name="Data Directory",
+            ),
+        ]
+    )
+
+server_params = StdioServerParameters(command="uv", args=["run", "my-server"])
+
+async with stdio_client(server_params) as (read_stream, write_stream):
+    async with ClientSession(
+        read_stream,
+        write_stream,
+        list_roots_callback=handle_list_roots,
+    ) as session:
+        await session.initialize()
+```
+
+When a `list_roots_callback` is provided, the client automatically advertises the
+`roots` capability (with `listChanged=True`) during initialization.
+
+### Sending Roots Changed Notifications
+
+When the set of roots changes after initialization, notify the server so it can
+re-request the list:
+
+```python
+# After updating what handle_list_roots would return:
+await session.send_roots_list_changed()
+```
+
+The server will then call the `list_roots_callback` again to get the updated list.
+
+## Tools
+
+### Listing Tools
+
+```python
+result = await session.list_tools()
+for tool in result.tools:
+    print(f"{tool.name}: {tool.description}")
+```
+
+Paginated listing is supported via `PaginatedRequestParams`:
+
+```python
+result = await session.list_tools()
+while result.nextCursor:
+    result = await session.list_tools(
+        params=types.PaginatedRequestParams(cursor=result.nextCursor)
+    )
+```
+
+### Calling Tools
+
+```python
+result = await session.call_tool(
+    "get_weather",
+    arguments={"city": "San Francisco"},
+)
+for content in result.content:
+    if isinstance(content, types.TextContent):
+        print(content.text)
+```
+
+You can pass a `read_timeout_seconds` for long-running tools and a
+`progress_callback` for progress updates:
+
+```python
+from datetime import timedelta
+
+async def on_progress(
+    progress: float, total: float | None, message: str | None
+) -> None:
+    print(f"Progress: {progress}/{total} - {message}")
+
+result = await session.call_tool(
+    "long_running_analysis",
+    arguments={"dataset": "large.csv"},
+    read_timeout_seconds=timedelta(minutes=5),
+    progress_callback=on_progress,
+)
+```
+
+## Resources
+
+### Listing Resources
+
+```python
+result = await session.list_resources()
+for resource in result.resources:
+    print(f"{resource.uri}: {resource.name}")
+```
+
+### Listing Resource Templates
+
+```python
+result = await session.list_resource_templates()
+for template in result.resourceTemplates:
+    print(f"{template.uriTemplate}: {template.name}")
+```
+
+### Reading Resources
+
+```python
+from pydantic import AnyUrl
+
+result = await session.read_resource(AnyUrl("file:///path/to/file.txt"))
+for content in result.contents:
+    if isinstance(content, types.TextResourceContents):
+        print(content.text)
+    elif isinstance(content, types.BlobResourceContents):
+        print(f"Binary data: {len(content.blob)} bytes")
+```
+
+## Prompts
+
+### Listing Prompts
+
+```python
+result = await session.list_prompts()
+for prompt in result.prompts:
+    print(f"{prompt.name}: {prompt.description}")
+```
+
+### Getting a Prompt
+
+```python
+result = await session.get_prompt(
+    "code_review",
+    arguments={"language": "python", "code": "def hello(): pass"},
+)
+print(f"Description: {result.description}")
+for message in result.messages:
+    print(f"[{message.role}]: {message.content}")
+```
+
+## Completions
+
+The `complete` method requests argument completions from the server. This is useful
+for building interactive UIs where users fill in prompt or resource template arguments.
+
+```python
+# Complete a prompt argument
+result = await session.complete(
+    ref=types.PromptReference(type="ref/prompt", name="code_review"),
+    argument={"name": "language", "value": "py"},
+)
+for value in result.completion.values:
+    print(value)  # e.g., "python"
+
+# Complete a resource template argument
+result = await session.complete(
+    ref=types.ResourceTemplateReference(
+        type="ref/resource", uri="file:///{path}"
+    ),
+    argument={"name": "path", "value": "/home/user/"},
+)
+```
+
+## Ping
+
+Send a ping to verify the server is responsive:
+
+```python
+await session.send_ping()
+```
+
+## Logging
+
+Set the server's logging level and handle log messages via a callback:
+
+```python
+async def handle_log(params: types.LoggingMessageNotificationParams) -> None:
+    print(f"[{params.level}] {params.logger}: {params.data}")
+
+async with ClientSession(
+    read_stream,
+    write_stream,
+    logging_callback=handle_log,
+) as session:
+    await session.initialize()
+    await session.set_logging_level("info")
+```
+
+## Full Example
+
+Putting it all together -- a client that connects to a server, lists its
+capabilities, and calls a tool:
+
+```python
+import anyio
+from mcp import ClientSession, StdioServerParameters, types
+from mcp.client.stdio import stdio_client
+
+
+async def main() -> None:
+    server_params = StdioServerParameters(
+        command="uv", args=["run", "my-server"]
+    )
+
+    async with stdio_client(server_params) as (read_stream, write_stream):
+        async with ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+
+            # List available tools
+            tools_result = await session.list_tools()
+            for tool in tools_result.tools:
+                print(f"Tool: {tool.name}")
+
+            # List available resources
+            resources_result = await session.list_resources()
+            for resource in resources_result.resources:
+                print(f"Resource: {resource.uri}")
+
+            # Call a tool
+            result = await session.call_tool(
+                "greet", arguments={"name": "World"}
+            )
+            print(result.content[0].text)
+
+
+anyio.run(main)
+```

docs/index.md

@@ -56,11 +56,17 @@ npx -y @modelcontextprotocol/inspector
 
 ## Getting Started
 
-<!-- TODO(Marcelo): automatically generate the follow references with a header on each of those files. -->
 1. **[Install](installation.md)** the MCP SDK
 2. **[Learn concepts](concepts.md)** - understand the three primitives and architecture
-3. **[Explore authorization](authorization.md)** - add security to your servers
-4. **[Use low-level APIs](low-level-server.md)** - for advanced customization
+
+## Guides
+
+- **[Building Servers](server.md)** - tools, resources, prompts, logging, elicitation, sampling, completions, and server transports
+- **[Writing Clients](client.md)** - connecting to servers, using tools/resources/prompts, roots, and client transports
+- **[Protocol Features](protocol.md)** - ping, progress, cancellation, pagination, capability negotiation, and JSON Schema 2020-12
+- **[Authorization](authorization.md)** - OAuth 2.1, token verification, and client authentication
+- **[Low-Level Server](low-level-server.md)** - direct handler registration for advanced use cases
+- **[Testing](testing.md)** - in-memory transport testing with pytest
 
 ## API Reference