Merge pull request #137 from auth0/update-mcp-auth-flow-spec-jun-25

Update mcp auth flow spec jun 25

Author: jtemporal

auth4genai/img/mcp_auth_flow.png

@@ -46,32 +46,25 @@ Here is the standard OAuth authorization code flow when an MCP server uses Auth0
 
 <Steps>
   <Step>
-    The MCP client initiates the OAuth flow by making a request to the MCP
-    server's authorization endpoint.
+    The MCP client sends a request to the protected MCP server and receives HTTP `401 Unauthorized` with a `WWW-Authenticate` header that indicates the protected resource metadata URL.
   </Step>
   <Step>
-    The MCP server redirects the user to the Auth0 authorization server.
+    The MCP client requests the [resource metadata](https://datatracker.ietf.org/doc/html/rfc9728/) from the MCP server at the `/.well-known/oauth-protected-resource` endpoint.
   </Step>
   <Step>
-    The user authenticates with Auth0 (using username/password, social login, or
-    MFA).
+    The MCP client parses the metadata, selects an authorization server (Auth0) from the list, and then fetches its OAuth 2.0 Authorization Server Metadata from the `/.well-known/oauth-authorization-server` endpoint. [Dynamic Client Registration (DCR)](https://auth0.com/docs/get-started/applications/dynamic-client-registration#enable-dynamic-client-registration) can happen after receiving the metadata response.
   </Step>
   <Step>
-    After successful authentication, Auth0 redirects the browser back to the MCP
-    server's callback URL with a single-use authorization code.
+    The client generates [PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) parameters and builds the authorization request, then opens the browser to the authorization endpoint.
   </Step>
   <Step>
-    The MCP server exchanges the authorization code for an access token directly
-    with the Auth0 token endpoint.
+    The user then authenticates with Auth0 (using username/password, social login, or MFA). Auth0 redirects the browser to the MCP client’s registered redirect URI with an authorization code.
   </Step>
   <Step>
-    The MCP server validates the token from Auth0 and generates its own session
-    or internal access token that is bound to the third-party session.
+    The MCP client exchanges the code at the token endpoint and Auth0 returns the access token completing the original OAuth flow.
   </Step>
   <Step>
-    The MCP server completes the original OAuth flow, returning its own token to
-    the MCP client, which can then be used to make authenticated calls to the
-    server's tools.
+    After receiving an access token (and refresh token), the MCP client will use the access token to make authenticated calls to the MCP server's tools.
   </Step>
 </Steps>