docs: fix stub pages and improve docs structure (#2101)

Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com>

Author: felixweinberger

README.md

@@ -170,7 +170,6 @@ The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you bui
 - [Authorization](docs/authorization.md) -- OAuth 2.1, token verification, client authentication
 - [Low-Level Server](docs/low-level-server.md) -- direct handler registration for advanced use cases
 - [Protocol Features](docs/protocol.md) -- MCP primitives, server capabilities
-- [Concepts](docs/concepts.md) -- architecture overview
 - [Testing](docs/testing.md) -- in-memory transport testing with pytest
 - [API Reference](https://modelcontextprotocol.github.io/python-sdk/api/)
 - [Experimental Features (Tasks)](https://modelcontextprotocol.github.io/python-sdk/experimental/tasks/)

docs/authorization.md

@@ -1,5 +1,177 @@
 # Authorization
 
-!!! warning "Under Construction"
+This page covers OAuth 2.1 authentication for both MCP servers and clients.
 
-    This page is currently being written. Check back soon for complete documentation.
+## Server-Side Authentication
+
+Authentication can be used by servers that want to expose tools accessing protected resources.
+
+`mcp.server.auth` implements OAuth 2.1 resource server functionality, where MCP servers act as Resource Servers (RS) that validate tokens issued by separate Authorization Servers (AS). This follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) and implements RFC 9728 (Protected Resource Metadata) for AS discovery.
+
+MCP servers can use authentication by providing an implementation of the `TokenVerifier` protocol:
+
+<!-- snippet-source examples/snippets/servers/oauth_server.py -->
+```python
+"""
+Run from the repository root:
+    uv run examples/snippets/servers/oauth_server.py
+"""
+
+from pydantic import AnyHttpUrl
+
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+from mcp.server.auth.settings import AuthSettings
+from mcp.server.fastmcp import FastMCP
+
+
+class SimpleTokenVerifier(TokenVerifier):
+    """Simple token verifier for demonstration."""
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        pass  # This is where you would implement actual token validation
+
+
+# Create FastMCP instance as a Resource Server
+mcp = FastMCP(
+    "Weather Service",
+    json_response=True,
+    # Token verifier for authentication
+    token_verifier=SimpleTokenVerifier(),
+    # Auth settings for RFC 9728 Protected Resource Metadata
+    auth=AuthSettings(
+        issuer_url=AnyHttpUrl("https://auth.example.com"),  # Authorization Server URL
+        resource_server_url=AnyHttpUrl("http://localhost:3001"),  # This server's URL
+        required_scopes=["user"],
+    ),
+)
+
+
+@mcp.tool()
+async def get_weather(city: str = "London") -> dict[str, str]:
+    """Get weather data for a city"""
+    return {
+        "city": city,
+        "temperature": "22",
+        "condition": "Partly cloudy",
+        "humidity": "65%",
+    }
+
+
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http")
+```
+
+_Full example: [examples/snippets/servers/oauth_server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/oauth_server.py)_
+<!-- /snippet-source -->
+
+For a complete example with separate Authorization Server and Resource Server implementations, see [`examples/servers/simple-auth/`](examples/servers/simple-auth/).
+
+**Architecture:**
+
+- **Authorization Server (AS)**: Handles OAuth flows, user authentication, and token issuance
+- **Resource Server (RS)**: Your MCP server that validates tokens and serves protected resources
+- **Client**: Discovers AS through RFC 9728, obtains tokens, and uses them with the MCP server
+
+See [TokenVerifier](src/mcp/server/auth/provider.py) for more details on implementing token validation.
+
+## Client-Side Authentication
+
+The SDK includes [authorization support](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) for connecting to protected MCP servers:
+
+<!-- snippet-source examples/snippets/clients/oauth_client.py -->
+```python
+"""
+Before running, specify running MCP RS server URL.
+To spin up RS server locally, see
+    examples/servers/simple-auth/README.md
+
+cd to the `examples/snippets` directory and run:
+    uv run oauth-client
+"""
+
+import asyncio
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+from pydantic import AnyUrl
+
+from mcp import ClientSession
+from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+
+
+class InMemoryTokenStorage(TokenStorage):
+    """Demo In-memory token storage implementation."""
+
+    def __init__(self):
+        self.tokens: OAuthToken | None = None
+        self.client_info: OAuthClientInformationFull | None = None
+
+    async def get_tokens(self) -> OAuthToken | None:
+        """Get stored tokens."""
+        return self.tokens
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        """Store tokens."""
+        self.tokens = tokens
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        """Get stored client information."""
+        return self.client_info
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        """Store client information."""
+        self.client_info = client_info
+
+
+async def handle_redirect(auth_url: str) -> None:
+    print(f"Visit: {auth_url}")
+
+
+async def handle_callback() -> tuple[str, str | None]:
+    callback_url = input("Paste callback URL: ")
+    params = parse_qs(urlparse(callback_url).query)
+    return params["code"][0], params.get("state", [None])[0]
+
+
+async def main():
+    """Run the OAuth client example."""
+    oauth_auth = OAuthClientProvider(
+        server_url="http://localhost:8001",
+        client_metadata=OAuthClientMetadata(
+            client_name="Example MCP Client",
+            redirect_uris=[AnyUrl("http://localhost:3000/callback")],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+            scope="user",
+        ),
+        storage=InMemoryTokenStorage(),
+        redirect_handler=handle_redirect,
+        callback_handler=handle_callback,
+    )
+
+    async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
+        async with streamable_http_client("http://localhost:8001/mcp", http_client=custom_client) as (read, write, _):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+
+                tools = await session.list_tools()
+                print(f"Available tools: {[tool.name for tool in tools.tools]}")
+
+                resources = await session.list_resources()
+                print(f"Available resources: {[r.uri for r in resources.resources]}")
+
+
+def run():
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()
+```
+
+_Full example: [examples/snippets/clients/oauth_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/oauth_client.py)_
+<!-- /snippet-source -->
+
+For a complete working example, see [`examples/clients/simple-auth-client/`](examples/clients/simple-auth-client/).

docs/client.md

@@ -1,6 +1,6 @@
 # Writing MCP Clients
 
-The SDK provides a high-level client interface for connecting to MCP servers using various [transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports):
+The SDK provides a high-level client interface for connecting to MCP servers using various [transports](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports):
 
 <!-- snippet-source examples/snippets/clients/stdio_client.py -->
 ```python
@@ -68,7 +68,7 @@ async def run():
             # Read a resource (greeting resource from fastmcp_quickstart)
             resource_content = await session.read_resource(AnyUrl("greeting://World"))
             content_block = resource_content.contents[0]
-            if isinstance(content_block, types.TextContent):
+            if isinstance(content_block, types.TextResourceContents):
                 print(f"Resource content: {content_block.text}")
 
             # Call a tool (add tool from fastmcp_quickstart)
@@ -92,7 +92,7 @@ if __name__ == "__main__":
 _Full example: [examples/snippets/clients/stdio_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/stdio_client.py)_
 <!-- /snippet-source -->
 
-Clients can also connect using [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http):
+Clients can also connect using [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http):
 
 <!-- snippet-source examples/snippets/clients/streamable_basic.py -->
 ```python
@@ -215,107 +215,9 @@ The `get_display_name()` function implements the proper precedence rules for dis
 
 This ensures your client UI shows the most user-friendly names that servers provide.
 
-## OAuth Authentication for Clients
+## OAuth Authentication
 
-The SDK includes [authorization support](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for connecting to protected MCP servers:
-
-<!-- snippet-source examples/snippets/clients/oauth_client.py -->
-```python
-"""
-Before running, specify running MCP RS server URL.
-To spin up RS server locally, see
-    examples/servers/simple-auth/README.md
-
-cd to the `examples/snippets` directory and run:
-    uv run oauth-client
-"""
-
-import asyncio
-from urllib.parse import parse_qs, urlparse
-
-import httpx
-from pydantic import AnyUrl
-
-from mcp import ClientSession
-from mcp.client.auth import OAuthClientProvider, TokenStorage
-from mcp.client.streamable_http import streamable_http_client
-from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
-
-
-class InMemoryTokenStorage(TokenStorage):
-    """Demo In-memory token storage implementation."""
-
-    def __init__(self):
-        self.tokens: OAuthToken | None = None
-        self.client_info: OAuthClientInformationFull | None = None
-
-    async def get_tokens(self) -> OAuthToken | None:
-        """Get stored tokens."""
-        return self.tokens
-
-    async def set_tokens(self, tokens: OAuthToken) -> None:
-        """Store tokens."""
-        self.tokens = tokens
-
-    async def get_client_info(self) -> OAuthClientInformationFull | None:
-        """Get stored client information."""
-        return self.client_info
-
-    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
-        """Store client information."""
-        self.client_info = client_info
-
-
-async def handle_redirect(auth_url: str) -> None:
-    print(f"Visit: {auth_url}")
-
-
-async def handle_callback() -> tuple[str, str | None]:
-    callback_url = input("Paste callback URL: ")
-    params = parse_qs(urlparse(callback_url).query)
-    return params["code"][0], params.get("state", [None])[0]
-
-
-async def main():
-    """Run the OAuth client example."""
-    oauth_auth = OAuthClientProvider(
-        server_url="http://localhost:8001",
-        client_metadata=OAuthClientMetadata(
-            client_name="Example MCP Client",
-            redirect_uris=[AnyUrl("http://localhost:3000/callback")],
-            grant_types=["authorization_code", "refresh_token"],
-            response_types=["code"],
-            scope="user",
-        ),
-        storage=InMemoryTokenStorage(),
-        redirect_handler=handle_redirect,
-        callback_handler=handle_callback,
-    )
-
-    async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
-        async with streamable_http_client("http://localhost:8001/mcp", http_client=custom_client) as (read, write, _):
-            async with ClientSession(read, write) as session:
-                await session.initialize()
-
-                tools = await session.list_tools()
-                print(f"Available tools: {[tool.name for tool in tools.tools]}")
-
-                resources = await session.list_resources()
-                print(f"Available resources: {[r.uri for r in resources.resources]}")
-
-
-def run():
-    asyncio.run(main())
-
-
-if __name__ == "__main__":
-    run()
-```
-
-_Full example: [examples/snippets/clients/oauth_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/oauth_client.py)_
-<!-- /snippet-source -->
-
-For a complete working example, see [`examples/clients/simple-auth-client/`](../examples/clients/simple-auth-client/).
+For OAuth 2.1 client authentication, see [Authorization](authorization.md#client-side-authentication).
 
 ## Roots
 
@@ -324,14 +226,12 @@ For a complete working example, see [`examples/clients/simple-auth-client/`](../
 Clients can provide a `list_roots_callback` so that servers can discover the client's workspace roots (directories, project folders, etc.):
 
 ```python
-from typing import Any
-
 from mcp import ClientSession, types
 from mcp.shared.context import RequestContext
 
 
 async def handle_list_roots(
-    context: RequestContext[ClientSession, Any],
+    context: RequestContext[ClientSession, None],
 ) -> types.ListRootsResult:
     """Return the client's workspace roots."""
     return types.ListRootsResult(
@@ -384,7 +284,7 @@ async def main():
 asyncio.run(main())
 ```
 
-The `sse_client()` function accepts optional `headers`, `timeout`, `sse_read_timeout`, and `auth` parameters. The SSE transport is considered legacy; prefer [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) for new servers.
+The `sse_client()` function accepts optional `headers`, `timeout`, `sse_read_timeout`, and `auth` parameters. The SSE transport is considered legacy; prefer [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http) for new servers.
 
 ## Ping
 

docs/concepts.md

@@ -58,12 +58,11 @@ npx -y @modelcontextprotocol/inspector
 
 <!-- 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. **[Build servers](server.md)** - tools, resources, prompts, transports, ASGI mounting
-4. **[Write clients](client.md)** - connect to servers, use tools/resources/prompts
-5. **[Explore authorization](authorization.md)** - add security to your servers
-6. **[Use low-level APIs](low-level-server.md)** - for advanced customization
-7. **[Protocol features](protocol.md)** - MCP primitives, server capabilities
+2. **[Build servers](server.md)** - tools, resources, prompts, transports, ASGI mounting
+3. **[Write clients](client.md)** - connect to servers, use tools/resources/prompts
+4. **[Explore authorization](authorization.md)** - add security to your servers
+5. **[Use low-level APIs](low-level-server.md)** - for advanced customization
+6. **[Protocol features](protocol.md)** - MCP primitives, server capabilities
 
 ## API Reference