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

[nypdmax]

Motivation and Context

This PR adds multi-protocol authentication support to the MCP Python SDK, centered around unified authorization
server discovery so clients can discover, select, and apply one of multiple supported auth protocols consistently.

Key capabilities:

• Unified auth protocol discovery via /.well-known/authorization_servers plus RFC 9728 PRM fallback.
  • Allows servers to advertise multiple protocols (e.g. oauth2, api_key) with optional default protocol and
    preferences.
  • Allows clients to select an injected protocol instance based on server hints and preferences, with safe fallbacks.
• Extensible protocol metadata (MCP extension fields) to represent protocol endpoints/capabilities consistently.
• DPoP support (RFC 9449):
  • Client-side proof generation and header injection (opt-in).
  • Server-side proof verification integrated into verification flow (opt-in).
• Streamable HTTP server maintainability: refactors request handling to reduce complexity while preserving behavior.
• Examples support: adds a small FastMCP compatibility wrapper used by examples and updates multiprotocol examples.
• Documentation updates covering protocol discovery and multiprotocol usage.

How Has This Been Tested?

• Unit/integration tests:

  • PYTEST_DISABLE_PLUGIN_AUTOLOAD="" uv run --frozen pytest

• Lint / typecheck:

  • uv run --frozen ruff format --check .
  • uv run --frozen ruff check .
  • uv run --frozen pyright

• E2E examples (manual OAuth flow):

  • ./examples/clients/simple-auth-multiprotocol-client/run_multiprotocol_test.sh
  • ./examples/clients/simple-auth-multiprotocol-client/run_dpop_test.sh
  • ./examples/clients/simple-auth-multiprotocol-client/run_oauth2_test.sh

Spec compliance notes (additive extensions)

This PR keeps MCP Authorization (2025-06-18) OAuth behavior intact (RFC 9728 PRM + RFC 8414 metadata + RFC 8707
resource indicators). It also adds optional extensions to support multi-protocol auth and stronger token binding:

• Multi-protocol selection (extension):

  • Optional /.well-known/authorization_servers endpoint (best-effort; client falls back if missing).
  • Optional PRM extension fields: mcp_auth_protocols, mcp_default_auth_protocol, mcp_auth_protocol_preferences.
  • Optional WWW-Authenticate: Bearer ... hint params: auth_protocols, default_protocol, protocol_preferences
    (ignored by spec-only clients).

• DPoP (RFC 9449) (optional extension): adds opt-in DPoP proof generation/verification; standard Bearer flow remains
  supported when disabled.

Interoperability: spec-only servers/clients can ignore these extensions and continue using the standard OAuth discovery
and Bearer token flow.

Breaking Changes

None expected. Changes are additive and aim to preserve existing behavior and public APIs.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Suggested review order (commit-by-commit):

1. Streamable HTTP server refactor
2. Auth server token handling + verifiers (and tests)
3. Multi-protocol client/provider behavior + test coverage
4. DPoP client/server pieces + tests
5. FastMCP wrapper + updated examples
6. Documentation updates

resolves #2024

[maxisbey]

Thanks for the effort here, but this is a very large PR introducing spec extensions without prior maintainer approval. Per our contributing guidelines, please open an issue first and get maintainer buy-in before submitting PRs of this scope. Features that touch the protocol (like new auth discovery mechanisms and DPoP) would also need a SEP.

_{AI Disclaimer}