New examples docs (full-ingest style) (#6)

* new example docs

* fixed nav

* fix doc index and TOC

* examples feature matrix

* populate transport column

* link to example headings

Author: mmacy

docs/asgi-integration.md

@@ -0,0 +1,146 @@
+# Authentication examples
+
+MCP supports OAuth 2.1 authentication for protecting server resources. This section demonstrates both server-side token verification and client-side authentication flows.
+
+## OAuth server implementation
+
+FastMCP server with OAuth token verification:
+
+```python
+--8<-- "examples/snippets/servers/oauth_server.py"
+```
+
+This example shows:
+
+- Implementing the `TokenVerifier` protocol for token validation
+- Using `AuthSettings` for RFC 9728 Protected Resource Metadata
+- Resource server configuration with authorization server discovery
+- Protected tools that require authentication
+
+## Complete authentication server
+
+Full Authorization Server implementation with token introspection:
+
+```python
+--8<-- "examples/servers/simple-auth/mcp_simple_auth/auth_server.py"
+```
+
+This comprehensive example includes:
+
+- OAuth 2.1 authorization flows (authorization code, refresh token)
+- Token introspection endpoint for resource servers
+- Client registration and metadata management
+- RFC 9728 protected resource metadata endpoint
+
+## Resource server with introspection
+
+MCP Resource Server that validates tokens via Authorization Server introspection:
+
+```python
+--8<-- "examples/servers/simple-auth/mcp_simple_auth/server.py"
+```
+
+This demonstrates:
+
+- Token introspection for validation instead of local token verification
+- Separation of Authorization Server (AS) and Resource Server (RS)
+- Protected MCP tools and resources
+- Production-ready server patterns
+
+## Token verification implementation
+
+Custom token verification logic:
+
+```python
+--8<-- "examples/servers/simple-auth/mcp_simple_auth/token_verifier.py"
+```
+
+This component handles:
+
+- HTTP token introspection requests
+- Token validation with scope checking
+- RFC 8707 resource parameter validation
+- Error handling and logging
+
+## Simple authentication provider
+
+Authentication provider for development and testing:
+
+```python
+--8<-- "examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py"
+```
+
+This utility provides:
+
+- Simplified token generation for testing
+- Development authentication flows
+- Testing utilities for protected resources
+
+## Legacy Authorization Server
+
+Backward compatibility with older OAuth implementations:
+
+```python
+--8<-- "examples/servers/simple-auth/mcp_simple_auth/legacy_as_server.py"
+```
+
+This example shows:
+
+- Support for non-RFC 9728 compliant clients
+- Legacy endpoint compatibility
+- Migration patterns for existing systems
+
+## OAuth architecture
+
+The MCP OAuth implementation follows the OAuth 2.1 authorization code flow with token introspection:
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant AS as Authorization Server
+    participant RS as Resource Server<br/>(MCP Server)
+    participant U as User
+
+    Note over C,RS: 1. Discovery Phase (RFC 9728)
+    C->>RS: GET /.well-known/oauth-protected-resource
+    RS->>C: Protected Resource Metadata<br/>(issuer, scopes, etc.)
+    
+    Note over C,AS: 2. Authorization Phase
+    C->>AS: GET /authorize?response_type=code&client_id=...
+    AS->>U: Redirect to login/consent
+    U->>AS: User authenticates and consents
+    AS->>C: Authorization code (via redirect)
+    
+    Note over C,AS: 3. Token Exchange
+    C->>AS: POST /token<br/>(authorization_code grant)
+    AS->>C: Access token + refresh token
+    
+    Note over C,RS: 4. Resource Access
+    C->>RS: MCP request + Authorization: Bearer <token>
+    RS->>AS: POST /introspect<br/>(validate token)
+    AS->>RS: Token info (active, scopes, user)
+    RS->>C: MCP response (if authorized)
+    
+    Note over C,AS: 5. Token Refresh (when needed)
+    C->>AS: POST /token<br/>(refresh_token grant)
+    AS->>C: New access token
+```
+
+**Components:**
+
+- **Authorization Server (AS)**: Handles OAuth flows, issues and validates tokens
+- **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 MCP server
+- **User**: Resource owner who authorizes access
+
+## Security considerations
+
+When implementing authentication:
+
+1. **Use HTTPS**: All OAuth flows must use HTTPS in production
+2. **Token validation**: Always validate tokens on the resource server side
+3. **Scope checking**: Verify that tokens have required scopes
+4. **Introspection**: Use token introspection for distributed validation
+5. **RFC compliance**: Follow RFC 9728 for proper AS discovery
+
+These examples provide a complete OAuth 2.1 implementation suitable for production use with proper security practices.

docs/authentication.md

@@ -0,0 +1,127 @@
+# Client examples
+
+MCP clients connect to servers to access tools, resources, and prompts. This section demonstrates various client patterns and connection types.
+
+## Basic stdio client
+
+Connecting to MCP servers over stdio transport:
+
+```python
+--8<-- "examples/snippets/clients/stdio_client.py"
+```
+
+This fundamental example demonstrates:
+
+- Creating `StdioServerParameters` for server connection
+- Using `ClientSession` for MCP communication
+- Listing and calling tools, reading resources, getting prompts
+- Handling both structured and unstructured tool results
+- Sampling callback implementation for LLM integration
+
+## Streamable HTTP client
+
+Connecting to HTTP-based MCP servers:
+
+```python
+--8<-- "examples/snippets/clients/streamable_basic.py"
+```
+
+This example shows:
+
+- Using `streamablehttp_client` for HTTP connections
+- Simpler connection setup for web-deployed servers
+- Basic tool listing and execution over HTTP
+
+## Display utilities
+
+Helper utilities for client user interfaces:
+
+```python
+--8<-- "examples/snippets/clients/display_utilities.py"
+```
+
+This practical example covers:
+
+- Using `get_display_name()` for human-readable names
+- Proper precedence rules for tool/resource titles
+- Building user-friendly client interfaces
+- Consistent naming across different MCP objects
+
+## OAuth authentication client
+
+Client-side OAuth 2.1 authentication flow:
+
+```python
+--8<-- "examples/snippets/clients/oauth_client.py"
+```
+
+This comprehensive example demonstrates:
+
+- `OAuthClientProvider` setup and configuration
+- Token storage with custom `TokenStorage` implementation
+- Authorization flow handling (redirect and callback)
+- Authenticated requests to protected MCP servers
+
+## Completion client
+
+Using completion suggestions for better user experience:
+
+```python
+--8<-- "examples/snippets/clients/completion_client.py"
+```
+
+This advanced example shows:
+
+- Resource template argument completion
+- Context-aware completions (e.g., repository suggestions based on owner)
+- Prompt argument completion
+- Dynamic suggestion generation
+
+## Tool result parsing
+
+Understanding and processing tool results:
+
+```python
+--8<-- "examples/snippets/clients/parsing_tool_results.py"
+```
+
+This detailed example covers:
+
+- Parsing different content types (`TextContent`, `ImageContent`, `EmbeddedResource`)
+- Handling structured output data
+- Processing embedded resources
+- Error handling for failed tool executions
+
+## Complete chatbot client
+
+A full-featured chatbot that integrates with multiple MCP servers:
+
+```python
+--8<-- "examples/clients/simple-chatbot/mcp_simple_chatbot/main.py"
+```
+
+This production-ready example includes:
+
+- **Multi-server management**: Connect to multiple MCP servers simultaneously
+- **LLM integration**: Use Groq API for natural language processing
+- **Tool orchestration**: Automatic tool selection and execution
+- **Error handling**: Retry mechanisms and graceful failure handling
+- **Configuration management**: JSON-based server configuration
+- **Session management**: Persistent conversation context
+
+## Authentication client
+
+Complete OAuth client implementation:
+
+```python
+--8<-- "examples/clients/simple-auth-client/mcp_simple_auth_client/main.py"
+```
+
+This example demonstrates:
+
+- Full OAuth 2.1 client implementation
+- Token management and refresh
+- Protected resource access
+- Integration with authenticated MCP servers
+
+These examples provide comprehensive patterns for building MCP clients that can handle various server types, authentication methods, and interaction patterns.

docs/completions.md

@@ -0,0 +1,75 @@
+# Echo server examples
+
+Echo servers are simple examples that demonstrate basic MCP functionality by echoing input back to clients. These are useful for testing and understanding MCP fundamentals.
+
+## Simple echo server
+
+The most basic echo implementation:
+
+```python
+--8<-- "examples/fastmcp/simple_echo.py"
+```
+
+This minimal example shows:
+
+- Single tool implementation with string input/output
+- Basic parameter handling
+- Simple string manipulation and return
+
+## Enhanced echo server
+
+More sophisticated echo patterns:
+
+```python
+--8<-- "examples/fastmcp/echo.py"
+```
+
+This enhanced version demonstrates:
+
+- Multiple echo variants (basic echo, uppercase, reverse)
+- Different parameter types and patterns
+- Tool naming and description best practices
+
+Echo servers are useful for:
+
+- **Testing client connections**: Verify that your client can connect and call tools
+- **Understanding MCP basics**: Learn the fundamental request/response patterns
+- **Development and debugging**: Simple, predictable behavior for testing
+- **Protocol verification**: Ensure transport layers work correctly
+
+## Usage patterns
+
+These echo servers can be used to test different aspects of MCP:
+
+```bash
+# Test with MCP Inspector
+uv run mcp dev echo.py
+
+# Test direct execution
+python echo.py
+
+# Test with custom clients
+# (Use the client examples to connect to these echo servers)
+```
+
+## Testing tool calls
+
+Example tool calls you can make to echo servers:
+
+```json
+{
+  "tool": "echo",
+  "arguments": {
+    "message": "Hello, MCP!"
+  }
+}
+```
+
+Expected response:
+```json
+{
+  "result": "Echo: Hello, MCP!"
+}
+```
+
+Echo servers provide a foundation for understanding MCP patterns before building more complex functionality.