refactor: update scope hints and improve README clarity across exercises

Author: kentcdodds

exercises/05.scopes/01.problem.check-scopes/README.mdx

@@ -38,3 +38,10 @@ Once you have the scope validation utilities in place, you'll also need to add a
 This approach means users will only see the tools and features they're actually authorized to use, creating a smooth and intuitive experience that matches their permission level.
 
 📜 For more details on OAuth scopes and how they work in MCP servers, see the [OAuth 2.0 Scopes RFC](https://tools.ietf.org/html/rfc6749#section-3.3) and the [MCP Authentication Specification](https://modelcontextprotocol.io/specification/2025-06-18/server/auth).
+
+<callout-danger>
+	At the time of this writing, there is a bug in the Cloudflare `McpAgent` that
+	prevents client capabilities from being provided properly, as a result,
+	sampling requests will not be made. Add `console.log`s to check if your logic
+	is working.
+</callout-danger>

exercises/05.scopes/03.problem.scope-hints/README.mdx

@@ -2,25 +2,11 @@
 
 👨‍💼 When users try to access our EpicMe journaling app without proper permissions, they need clear guidance on what scopes are available and required. Without this information, clients can't know what to request during the OAuth authorization flow, leading to failed authentication attempts and frustrated users.
 
-The solution is to provide **scope hints** in our OAuth responses. These hints tell clients exactly what scopes are supported and help them understand what permissions they need to request from the authorization server.
+The solution is to provide a **scope hint** (called `scopes_supported`) in our OAuth protected resource metadata. This metadata tells clients exactly what scopes are supported and help them understand what permissions they could request from the authorization server.
 
 Here's how this works in practice. Imagine a smart home app that controls different devices:
 
-```ts lines=8,20-25
-// When a client gets a 401 Unauthorized response, we include scope hints
-function handleUnauthorized(request: Request) {
-	return new Response('Unauthorized', {
-		status: 401,
-		headers: {
-			'WWW-Authenticate': [
-				'Bearer realm="SmartHome"',
-				'scope="lights:read lights:write thermostat:read security:admin"',
-				'resource_metadata=https://smarthome.example.com/.well-known/oauth-protected-resource',
-			].join(', '),
-		},
-	})
-}
-
+```ts lines=6-11
 // The protected resource metadata also lists supported scopes
 function handleOAuthProtectedResourceRequest(request: Request) {
 	return Response.json({
@@ -36,25 +22,8 @@ function handleOAuthProtectedResourceRequest(request: Request) {
 }
 ```
 
-The `scope` parameter in the `WWW-Authenticate` header tells the client what scopes are available for this specific resource. The `scopes_supported` in the protected resource metadata provides a complete list of all supported scopes across the entire system.
-
-<callout-info>
-	The `scope` parameter in OAuth error responses helps clients understand what
-	permissions they can request, while `scopes_supported` in the metadata
-	endpoint gives them the complete picture of available scopes.
-</callout-info>
-
-<callout-warning>
-	Note the difference between 401 and 403 responses: In a **401 Unauthorized**
-	response, the `scope` parameter lists **all available scopes** for discovery
-	("here's what you can request"). In a **403 Forbidden** response, the `scopes`
-	parameter would list **required scopes** for that specific request ("here's
-	what you need"). We can't use `scopes` in our 403 response because we have
-	multiple valid scope combinations rather than a single required set.
-</callout-warning>
-
-This approach ensures that when users encounter permission issues, their client apps can automatically request the right scopes and guide users through a smooth authorization flow.
+The `scopes_supported` in the protected resource metadata provides a complete list of all supported scopes across the entire system.
 
 📜 For more details on OAuth scope parameters, see the [OAuth 2.0 Authorization Framework RFC](https://tools.ietf.org/html/rfc6749#section-3.3).
 
-Now, add the missing scope hints to help clients understand what permissions are available for our EpicMe journaling app.
+Now, add the missing `scopes_supported` to help clients understand what permissions are available for our EpicMe journaling app.

exercises/05.scopes/03.problem.scope-hints/src/auth.ts

@@ -112,7 +112,7 @@ export function handleUnauthorized(request: Request) {
 					? `error_description="The access token is invalid or expired"`
 					: null,
 				`resource_metadata=${url.toString()}`,
-				// 🐨 add a scope hint for the supported scopes (join the supported scopes with a space)
+				// No scope hint here for the same reason as above
 			]
 				.filter(Boolean)
 				.join(', '),

exercises/05.scopes/03.solution.scope-hints/src/auth.ts

@@ -112,7 +112,7 @@ export function handleUnauthorized(request: Request) {
 					? `error_description="The access token is invalid or expired"`
 					: null,
 				`resource_metadata=${url.toString()}`,
-				`scope=${supportedScopes.join(' ')}`,
+				// No scope hint here for the same reason as above
 			]
 				.filter(Boolean)
 				.join(', '),

exercises/05.scopes/README.mdx

@@ -45,20 +45,20 @@ Here's a sequence diagram showing how scope validation works in an MCP server:
 ```mermaid
 sequenceDiagram
     participant Client
-    participant MCP_Server
-    participant Auth_Server
+    participant MCP Server
+    participant Auth Server
     participant Database
 
-    Client->>MCP_Server: Request with access token
-    MCP_Server->>Auth_Server: Introspect token
-    Auth_Server-->>MCP_Server: Token info + scopes
-    MCP_Server->>MCP_Server: Validate required scopes
+    Client->>MCP Server: Request with access token
+    MCP Server->>Auth Server: Introspect token
+    Auth Server-->>MCP Server: Token info + scopes
+    MCP Server->>MCP Server: Validate required scopes
     alt Sufficient scopes
-        MCP_Server->>Database: Execute requested operation
-        Database-->>MCP_Server: Return data
-        MCP_Server-->>Client: Success response
+        MCP Server->>Database: Execute requested operation
+        Database-->>MCP Server: Return data
+        MCP Server-->>Client: Success response
     else Insufficient scopes
-        MCP_Server-->>Client: 403 Forbidden with scope hints
+        MCP Server-->>Client: 403 Forbidden with scope hints
     end
 ```