feat(auth): add unified auth protocol discovery and optional DPoP support

docs/authorization.md

@@ -1,5 +1,16 @@
 # Authorization
 
-!!! warning "Under Construction"
+The MCP Python SDK supports **multi-protocol authorization**: OAuth 2.0, API Key, DPoP (Demonstrating Proof-of-Possession), and a Mutual TLS placeholder. Servers declare supported protocols via PRM (Protected Resource Metadata) and WWW-Authenticate; clients discover and select a protocol automatically.
 
-    This page is currently being written. Check back soon for complete documentation.
+## Overview
+
+- **OAuth 2.0**: Authorization code flow with PKCE; 401 → discovery → OAuth → token → MCP. Fully supported with `OAuthClientProvider` / `OAuth2Protocol`.
+- **API Key**: Send `X-API-Key` (or `Authorization: Bearer <key>` when configured). No AS required. Use `MCP_API_KEY` on the client and `--api-keys` on the server.
+- **DPoP** (RFC 9449): Binds the access token to a client-held key. Use with OAuth: client sets `MCP_USE_OAUTH=1` and `MCP_DPOP_ENABLED=1`; server starts with `--dpop-enabled`.
+- **Mutual TLS**: Placeholder in the examples (no client certificate validation).
+
+Examples: [simple-auth-multiprotocol](../examples/servers/simple-auth-multiprotocol/) (server), [simple-auth-multiprotocol-client](../examples/clients/simple-auth-multiprotocol-client/) (client). See [examples/README.md](../examples/README.md) for API Key, DPoP, and mTLS running instructions.
+
+---
+
+For protocol implementation, migration from OAuth-only to multi-protocol, DPoP usage, and API reference, see **[Authorization: Multi-Protocol Extension](authorization-multiprotocol.md)**.

examples/README.md

@@ -1,5 +1,25 @@
 # Python SDK Examples
 
-This folders aims to provide simple examples of using the Python SDK. Please refer to the
+This folder aims to provide simple examples of using the Python SDK. Please refer to the
 [servers repository](https://github.com/modelcontextprotocol/servers)
 for real-world servers.
+
+## Multi-protocol auth
+
+- **Server**: [simple-auth-multiprotocol](servers/simple-auth-multiprotocol/) — RS with OAuth, API Key, DPoP, and Mutual TLS (placeholder).
+
+### API Key
+
+- Use `MCP_API_KEY` on the client; start RS with `--api-keys=...` (no AS required).
+- One-command test (from repo root): `./examples/clients/simple-auth-multiprotocol-client/run_multiprotocol_test.sh`
+
+### OAuth + DPoP
+
+- Start AS and RS with `--dpop-enabled`; client: `MCP_USE_OAUTH=1 MCP_DPOP_ENABLED=1`.
+- One-command test (from repo root): `./examples/clients/simple-auth-multiprotocol-client/run_dpop_test.sh` (use `MCP_SKIP_OAUTH=1` to skip manual OAuth step).
+
+### Mutual TLS (placeholder)
+
+- mTLS is a placeholder (no client cert validation). Script: `MCP_AUTH_PROTOCOL=mutual_tls ./examples/clients/simple-auth-multiprotocol-client/run_multiprotocol_test.sh`
+
+**Client**: [simple-auth-multiprotocol-client](clients/simple-auth-multiprotocol-client/) — supports API Key (`MCP_API_KEY`), OAuth+DPoP (`MCP_USE_OAUTH=1`, `MCP_DPOP_ENABLED=1`), and mTLS placeholder.

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

@@ -0,0 +1,63 @@
+# Simple Auth Multiprotocol Client
+
+MCP client example using **MultiProtocolAuthProvider** with **API Key** and **Mutual TLS (placeholder)**.
+
+- Uses `MultiProtocolAuthProvider` and protocol selection from server discovery (PRM / WWW-Authenticate).
+- **API Key**: reads key from env `MCP_API_KEY` (default `demo-api-key-12345`), sends `X-API-Key` header.
+- **Mutual TLS**: placeholder only; when selected, prints a message and exits (no client cert in this example).
+
+## Run
+
+1. Start the multi-protocol resource server (e.g. `simple-auth-multiprotocol` on port 8002).
+2. From this directory: `uv run mcp-simple-auth-multiprotocol-client` or `uv run python -m mcp_simple_auth_multiprotocol_client`.
+3. Optional: `MCP_SERVER_URL=http://localhost:8002/mcp` to override server URL.
+
+## Running with API Key
+
+When the server supports API Key (e.g. `simple-auth-multiprotocol` with `--api-keys`), set:
+
+- **`MCP_API_KEY`** – your API key (e.g. `demo-api-key-12345`). The client sends it as `X-API-Key`.
+- **`MCP_SERVER_URL`** – optional; default is `http://localhost:8002/mcp` when using the default client config.
+
+Example (server on port 8002, no OAuth/AS required):
+
+```bash
+MCP_SERVER_URL=http://localhost:8002/mcp MCP_API_KEY=demo-api-key-12345 uv run mcp-simple-auth-multiprotocol-client
+```
+
+**One-command test** from repo root:  
+`./examples/clients/simple-auth-multiprotocol-client/run_multiprotocol_test.sh`  
+starts the resource server and this client with API Key; at `mcp>` run `list`, `call get_time {}`, `quit`.
+
+## Running with OAuth + DPoP
+
+When the server has DPoP enabled (`--dpop-enabled`), use OAuth and DPoP together:
+
+- **`MCP_USE_OAUTH=1`** – enable OAuth (required for DPoP).
+- **`MCP_DPOP_ENABLED=1`** – send DPoP-bound access tokens (DPoP proof in each request).
+
+Example (server on port 8002 with DPoP, AS on 9000):
+
+```bash
+MCP_SERVER_URL=http://localhost:8002/mcp MCP_USE_OAUTH=1 MCP_DPOP_ENABLED=1 uv run mcp-simple-auth-multiprotocol-client
+```
+
+Complete OAuth in the browser; then at `mcp>` run `list`, `call get_time {}`, `quit`. Server logs should show "Authentication successful with DPoP".
+
+**One-command test** from repo root:  
+`./examples/clients/simple-auth-multiprotocol-client/run_dpop_test.sh` — starts AS and RS with DPoP, then runs this client (OAuth+DPoP). Use `MCP_SKIP_OAUTH=1` to run only the automated curl tests and skip the manual client step.
+
+## Running with Mutual TLS (placeholder)
+
+Mutual TLS is a **placeholder** in this example: the client registers the `mutual_tls` protocol but does **not** perform client certificate authentication. Selecting mTLS will show a "not implemented" style message.
+
+- **`MCP_AUTH_PROTOCOL=mutual_tls`** runs this client in mTLS mode; the client will start but mTLS auth is not implemented.
+
+**One-command test** from repo root:  
+`MCP_AUTH_PROTOCOL=mutual_tls ./examples/clients/simple-auth-multiprotocol-client/run_multiprotocol_test.sh`
+
+## Commands
+
+- `list` – list tools  
+- `call get_time` – call `get_time`  
+- `quit` – exit  

examples/clients/simple-auth-multiprotocol-client/mcp_simple_auth_multiprotocol_client/__init__.py

@@ -0,0 +1 @@
+"""Multi-protocol auth client example (API Key + mTLS placeholder)."""

examples/clients/simple-auth-multiprotocol-client/mcp_simple_auth_multiprotocol_client/__main__.py

@@ -0,0 +1,6 @@
+"""Run as python -m mcp_simple_auth_multiprotocol_client."""
+
+from mcp_simple_auth_multiprotocol_client.main import cli
+
+if __name__ == "__main__":
+    cli()