Support multi-protocol authentication with spec-aligned discovery and OAuth fallback #2024

Motivation

In real-world deployments (especially enterprise applications), OAuth-only support is often not sufficient.

Production environments commonly require multiple authentication protocols working in parallel, for example:

• OAuth2 (and extensions like DPoP) for interactive user flows
• API keys / bearer-like tokens for service-to-service access or legacy integrations
• Potential future protocols (e.g. mTLS, enterprise-managed authorization, etc.)

To make these deployments practical, clients need a unified way to discover which authentication protocol(s) a server supports and select an appropriate protocol without hardcoding assumptions per server.

At the same time, we must remain consistent with the MCP specification:

• If multi-protocol discovery is not supported (or not advertised), clients must be able to fall back to OAuth seamlessly.
• OAuth behavior, implementation, and public interfaces must not change as a consequence of introducing multi-protocol discovery.
• The OAuth fallback path should preserve current semantics to avoid breaking existing deployments.

Goal

Define and implement a spec-aligned mechanism for unified authentication protocol discovery that:

1. Enables multi-protocol deployments (discover + select protocol)
2. Preserves backwards compatibility via OAuth fallback
3. Does not modify OAuth behavior/implementation/API surface when used in OAuth-only mode

Non-goals

• Changing the MCP JSON-RPC protocol or breaking compatibility.
• Redefining existing OAuth flows or requiring server changes for OAuth-only deployments.

Related issues (background)

• Tool/server auth context needs:
  • how to get http request headers in mcp tools logic when i use streamable http mode to run mcp server ? #750 (access request headers in tool logic)
  • FastMCP Auth Context in tools #638 (auth context in tools/resources)
• Enterprise ergonomics / future evolution:
  • Support Per-Request HTTP Headers in call_tool() #1509 (per-request headers on call_tool())
  • Support for Parameter Passing in MCP Configuration and Runtime Context #1023 (server-visible but model-hidden runtime context channel)
  • auth specification in ClientSessionGroup #1723 (ClientSessionGroup auth configuration)
  • User-Agent header in sHTTP transport is not forwarded to auth flow #1664 (consistent propagation of transport headers into auth flows)
• API key usage signal:
  • 怎么实现类似https://open.bigmodel.cn/api/mcp/web_search/sse?Authorization= YOUR API Key 这样的授权功能 #1282 (API key authorization question)

Suggested acceptance criteria (high level)

• When a server advertises multi-protocol auth capabilities, the client can discover supported protocols and select one deterministically.
• When no multi-protocol capabilities are available, the client behaves exactly as today (OAuth-only), with no API changes required.
• OAuth-only deployments are unaffected (same flows, same inputs/outputs, same interfaces).