The WWW-Authenticate: MCP header is the HTTP header that an MCP server returns alongside a 401 Unauthorized response, telling the MCP client where to find the authorization metadata it needs to start an OAuth flow. The header contains a resource_metadata parameter pointing to the server’s Protected Resource Metadata (RFC 9728) document. When an MCP client makes an unauthenticated request to a remote MCP server, the server responds with this header instead of a generic 401. The client reads the header, fetches the PRM document, discovers the authorization server, and starts authentication. The header is the entry point for the entire MCP authorization flow.
How the WWW-Authenticate: MCP Header Works in Practice
The client parses the header, extracts the resource_metadata URL, and fetches the JSON document at that URL. The document lists the authorization server (or servers) that protect this MCP resource. The client then registers itself (via CIMD or DCR), runs the OAuth 2.1 authorization code flow with PKCE, and obtains an access token. From that point forward, every request to the MCP server includes the token in the Authorization: Bearer header.
Certified MCP Security Expert
Attack, defend, and pen test MCP servers in 30+ hands-on labs. Get certified.
Why This Header Matters for MCP Discovery and Security
Before the WWW-Authenticate: MCP header standardized discovery, MCP clients had to hard-code authorization server URLs or guess at well-known paths. That created fragile installations and made it nearly impossible to rotate authorization servers without breaking every client. The header solves this cleanly: the server controls discovery, the client follows the pointer. Security-wise, it also enables clean separation between the resource server (the MCP server itself) and the authorization server. The MCP server doesn’t need to issue tokens or handle OAuth flows. It just points clients at the right place.
How to Implement the WWW-Authenticate: MCP Header Correctly
Return the header on every 401 response, not just the first one. Use HTTPS for the resource_metadata URL, never plain HTTP. Make sure the URL is stable and cacheable so clients aren’t refetching constantly. Include a clear error parameter if you want to communicate why the request failed beyond a generic 401. Log every 401 response with the requesting client identity for audit trails.