Merge branch 'main' into nate/fix-pagination-cursor

Author: nbarbettini

README.md

@@ -796,6 +796,60 @@ async def main():
             tool_result = await session.call_tool("echo", {"message": "hello"})
 ```
 
+### OAuth Authentication for Clients
+
+The SDK includes [authorization support](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for connecting to protected MCP servers:
+
+```python
+from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+
+
+class CustomTokenStorage(TokenStorage):
+    """Simple in-memory token storage implementation."""
+
+    async def get_tokens(self) -> OAuthToken | None:
+        pass
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        pass
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        pass
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        pass
+
+
+async def main():
+    # Set up OAuth authentication
+    oauth_auth = OAuthClientProvider(
+        server_url="https://api.example.com",
+        client_metadata=OAuthClientMetadata(
+            client_name="My Client",
+            redirect_uris=["http://localhost:3000/callback"],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+        ),
+        storage=CustomTokenStorage(),
+        redirect_handler=lambda url: print(f"Visit: {url}"),
+        callback_handler=lambda: ("auth_code", None),
+    )
+
+    # Use with streamable HTTP client
+    async with streamablehttp_client(
+        "https://api.example.com/mcp", auth=oauth_auth
+    ) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            # Authenticated session ready
+```
+
+For a complete working example, see [`examples/clients/simple-auth-client/`](examples/clients/simple-auth-client/).
+
+
 ### MCP Primitives
 
 The MCP protocol defines three core primitives that servers can implement:

examples/clients/simple-auth-client/README.md

@@ -0,0 +1,74 @@
+# Simple Auth Client Example
+
+A demonstration of how to use the MCP Python SDK with OAuth authentication over streamable HTTP or SSE transport.
+
+## Features
+
+- OAuth 2.0 authentication with PKCE
+- Support for both StreamableHTTP and SSE transports
+- Interactive command-line interface
+
+## Installation
+
+```bash
+cd examples/clients/simple-auth-client
+uv sync --reinstall 
+```
+
+## Usage
+
+### 1. Start an MCP server with OAuth support
+
+```bash
+# Example with mcp-simple-auth
+cd path/to/mcp-simple-auth
+uv run mcp-simple-auth --transport streamable-http --port 3001
+```
+
+### 2. Run the client
+
+```bash
+uv run mcp-simple-auth-client
+
+# Or with custom server URL
+MCP_SERVER_PORT=3001 uv run mcp-simple-auth-client
+
+# Use SSE transport
+MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client
+```
+
+### 3. Complete OAuth flow
+
+The client will open your browser for authentication. After completing OAuth, you can use commands:
+
+- `list` - List available tools
+- `call <tool_name> [args]` - Call a tool with optional JSON arguments  
+- `quit` - Exit
+
+## Example
+
+```
+🔐 Simple MCP Auth Client
+Connecting to: http://localhost:3001
+
+Please visit the following URL to authorize the application:
+http://localhost:3001/authorize?response_type=code&client_id=...
+
+✅ Connected to MCP server at http://localhost:3001
+
+mcp> list
+📋 Available tools:
+1. echo - Echo back the input text
+
+mcp> call echo {"text": "Hello, world!"}
+🔧 Tool 'echo' result:
+Hello, world!
+
+mcp> quit
+👋 Goodbye!
+```
+
+## Configuration
+
+- `MCP_SERVER_PORT` - Server URL (default: 8000)
+- `MCP_TRANSPORT_TYPE` - Transport type: `streamable_http` (default) or `sse`

examples/clients/simple-auth-client/mcp_simple_auth_client/__init__.py

@@ -0,0 +1 @@
+"""Simple OAuth client for MCP simple-auth server."""