add instructions for 1 and 2

kentcdodds · kentcdodds · commit f130bbdff247 · 2025-09-10T17:20:23.000-06:00
diff --git a/.gitignore b/.gitignore
@@ -12,6 +12,8 @@ data.db
 # in a real app you'd want to not commit the .env
 # file as well, but since this is for a workshop
 # we're going to keep them around.
-# .env
+!**/.env
+
+/.env
 **/dist/**
 **/.wrangler/**
diff --git a/exercises/01.discovery/01.solution.cors/README.mdx b/exercises/01.discovery/01.solution.cors/README.mdx
@@ -1,5 +1,5 @@
 # CORS
 
-👨‍💼 Excellent work! We've successfully solved a critical problem for our MCP server users: now they can connect to our server from any domain without encountering frustrating CORS policy errors.
+👨‍💼 Excellent work! Now our users can connect to our server from any domain without encountering frustrating CORS policy errors.
 
 This improvement means users get seamless access to our MCP server's capabilities regardless of where they're connecting from. Whether they're using VS Code, a web application, or any other MCP client, the connection just works. This is exactly what users expect from a modern, accessible MCP server.
diff --git a/exercises/01.discovery/02.solution.as/README.mdx b/exercises/01.discovery/02.solution.as/README.mdx
@@ -1 +1,5 @@
 # Auth Server Metadata
+
+👨‍💼 Fantastic progress! Now, clients can seamlessly discover how to authenticate with our system by accessing the standardized `/.well-known/oauth-authorization-server` endpoint. This means any MCP-compliant client can automatically find out where to register, authorize, and obtain tokens—removing guesswork and enabling smooth, standards-based integration.
+
+By relaying the OAuth server's metadata, we've made our MCP server a true authentication discovery hub. This empowers users to connect their tools and applications with confidence, knowing they have all the information needed for secure authentication.
diff --git a/exercises/01.discovery/03.problem.pr/README.mdx b/exercises/01.discovery/03.problem.pr/README.mdx
@@ -1 +1,64 @@
 # Protected Resource
+
+👨‍💼 For our journaling app it's crucial that clients can discover how to interact with our resource server in a standards-compliant way. The Model Context Protocol (MCP) and OAuth require that we expose a public metadata endpoint so that any client can learn how to authenticate and what endpoints are available. This endpoint must be accessible to everyone, without requiring authentication, because it's the first step in the OAuth discovery process.
+
+But not all protected resources are the same! In a large system, you might have multiple APIs or services, each with its own protected data—think: user profiles, journal entries, or analytics. Each of these can be considered a separate "protected resource" in OAuth terms. To support this, the OAuth and MCP specifications allow for multiple resource metadata endpoints, each describing a different protected resource.
+
+That's why, for EpicMe, our endpoint is:
+
+```
+/.well-known/oauth-protected-resource/mcp
+```
+
+The `/mcp` at the end uniquely identifies our journaling MCP endpoint as a specific protected resource. This makes it possible for clients to discover metadata for just the resource they want to access, even if the server hosts several different APIs. It also helps with future extensibility—if we add more protected resources later, each can have its own metadata endpoint under `/.well-known/oauth-protected-resource/`.
+
+Here's how a client might discover resource server's metadata:
+
+```ts
+// Example: Discovering the MCP resource server's metadata
+const response = await fetch(
+	'https://api.example.com/.well-known/oauth-protected-resource/mcp',
+)
+if (response.ok) {
+	const metadata = await response.json()
+	// metadata.authorization_servers tells the client where to go next
+} else {
+	throw new Error('Could not discover resource server metadata.')
+}
+```
+
+Here's an example of what the metadata content looks like:
+
+```json
+{
+	"resource": "https://api.example.com/mcp",
+	"authorization_servers": ["https://auth.example.com"]
+}
+```
+
+There are [a some other fields you can supply](https://datatracker.ietf.org/doc/html/rfc9728#section-3.1), but these are the two most important for our purposes.
+
+Here's the overall flow for a client discovering the resource server and then the authorization server:
+
+```mermaid
+sequenceDiagram
+  Client->>EpicMe: GET /.well-known/oauth-protected-resource/mcp
+  EpicMe-->>Client: Resource metadata (includes authorization_servers)
+  Client->>Auth Server: GET /.well-known/oauth-authorization-server
+  Auth Server-->>Client: Authorization server metadata
+```
+
+<callout-info>
+	🚦 The `/.well-known/oauth-protected-resource/mcp` endpoint must be accessible
+	to all clients, without authentication. This is required by the OAuth and MCP
+	specifications.
+</callout-info>
+
+<callout-muted>
+	📜 For more details, see the [OAuth 2.0 Protected Resource Metadata
+	RFC](https://datatracker.ietf.org/doc/html/rfc9728).
+</callout-muted>
+
+The goal is to make EpicMe's resource server discoverable and easy to integrate with any standards-compliant client. Make sure your implementation exposes the correct metadata endpoint for the MCP resource, so clients can start the OAuth flow without any roadblocks.
+
+Now, check that your `/.well-known/oauth-protected-resource/mcp` endpoint is public, returns the correct metadata, and helps clients discover how to connect to EpicMe securely!
diff --git a/exercises/01.discovery/03.solution.pr/README.mdx b/exercises/01.discovery/03.solution.pr/README.mdx
@@ -1 +1,7 @@
 # Protected Resource
+
+👨‍💼 Outstanding achievement! Now, any client can discover how to interact with our journaling resource server in a standards-compliant way. By exposing the public `/.well-known/oauth-protected-resource/mcp` metadata endpoint, we've made it possible for clients to programmatically learn how to authenticate and which authorization servers to use—without any guesswork or manual configuration.
+
+This means that as our system grows, each protected resource (like user profiles, journal entries, or analytics) can have its own discoverable endpoint, making integration seamless for all clients. Users benefit from a smoother onboarding experience, and developers can confidently build on top of our platform knowing that discovery is simple and future-proof.
+
+But we're just focused on MCP. Let's keep going!
diff --git a/exercises/01.discovery/FINISHED.mdx b/exercises/01.discovery/FINISHED.mdx
@@ -1 +1,17 @@
 # Metadata Discovery
+
+Congratulations! You've completed the first step in making your MCP server discoverable and accessible to any standards-compliant client.
+
+In this exercise, you:
+
+- Implemented CORS support for your MCP server, ensuring that clients from any domain (including web apps and desktop tools like VS Code) can connect without running into CORS policy errors.
+- Used the provided `withCors` utility to handle the complexity of CORS headers, preflight requests, and response modification, so your business logic stays clean and focused.
+- Configured your server to expose the correct CORS headers for the `/.well-known` endpoints, which are essential for service discovery and integration.
+
+<callout-success>
+	By supporting CORS and the discovery endpoints, you've made it possible to use
+	OAuth to authorize your MCP server to access user data securely and
+	seamlessly.
+</callout-success>
+
+Let's keep building on this foundation to make your MCP server even more powerful and user-friendly!
diff --git a/exercises/01.discovery/README.mdx b/exercises/01.discovery/README.mdx
@@ -1,3 +1,72 @@
 # Metadata Discovery
 
-NOTE: Make sure to talk about the relationship between auth server and resource server.
+Modern applications need a way for clients to discover how to authenticate and interact with servers securely. In the Model Context Protocol (MCP), this is achieved through standardized metadata endpoints that describe both the resource server (your MCP server) and its associated authorization server.
+
+Without this discovery mechanism, clients would have to guess or hardcode authentication details, leading to brittle integrations and poor user experience.
+
+## Why does this matter?
+
+- **Seamless integration:** Clients (like VS Code, web apps, or other tools) can automatically discover how to authenticate and what endpoints to use.
+- **Security:** By following standards, you reduce the risk of misconfiguration and security vulnerabilities.
+- **Interoperability:** Any MCP-compliant client can connect to any MCP server, regardless of who built it.
+
+## The relationship: Auth Server vs. Resource Server
+
+- **Resource Server:** Your MCP server, which hosts protected resources and APIs.
+- **Authorization Server:** Issues access tokens and handles user authentication. It may be a separate service or co-located with the resource server.
+
+Clients first discover the resource server’s metadata, which points them to the authorization server’s metadata. This chain of discovery is what enables secure, standards-based authentication.
+
+<callout-info>
+	📜 See the [MCP Authorization
+	Spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
+	for details on discovery and metadata.
+</callout-info>
+
+## Example: Metadata Discovery Flow
+
+```mermaid
+sequenceDiagram
+	Client->>MCP Server: GET /.well-known/oauth-protected-resource
+	MCP Server-->>Client: Resource metadata (includes authorization_servers)
+	Client->>Authorization Server: GET /.well-known/oauth-authorization-server
+	Authorization Server-->>Client: Authorization server metadata
+	Client->>Authorization Server: OAuth flow (get token)
+	Client->>MCP Server: Authenticated request with token
+	MCP Server-->>Client: Protected resource
+```
+
+### Realistic Example
+
+```ts
+// Discover resource server metadata
+const resourceMeta = await fetch(
+	'https://our-mcp-server.com/.well-known/oauth-protected-resource',
+).then((r) => r.json())
+
+// Find the authorization server URL
+const authServerUrl = resourceMeta.authorization_servers[0]
+
+// Discover authorization server metadata
+const authMeta = await fetch(authServerUrl).then((r) => r.json())
+
+// Now the client knows how to authenticate!
+```
+
+<callout-success>
+	By implementing these endpoints, you make your MCP server discoverable and
+	easy to integrate with any standards-compliant client.
+</callout-success>
+
+## Recommended Practices
+
+- Always implement both resource and authorization server metadata endpoints.
+- Use CORS headers to allow cross-origin discovery.
+- Validate and document your endpoints for client developers.
+
+<callout-muted>
+	📜 For more, see [RFC 8414: OAuth 2.0 Authorization Server
+	Metadata](https://datatracker.ietf.org/doc/html/rfc8414) and [RFC 9728: OAuth
+	2.0 Protected Resource
+	Metadata](https://datatracker.ietf.org/doc/html/rfc9728).
+</callout-muted>
diff --git a/exercises/02.init/01.problem.authenticate/README.mdx b/exercises/02.init/01.problem.authenticate/README.mdx
@@ -1 +1,31 @@
 # Authenticate Header
+
+👨‍💼 In EpicMe, the `Authorization` header is the gatekeeper for every journal entry. Its job is simple but critical: make sure that only requests with valid credentials can access or change journal data. If a request doesn't include this header, it shouldn't get through—no exceptions. Once the client has an auth token, it'll send that token in the `Authorization` header. If that header doesn't exist, then we know they don't have a token and shouldn't be able to access our server.
+
+But we can help them out by telling them what they need to do to get access. This is where the `WWW-Authenticate` header comes in. It tells the client what kind of authentication is required.
+
+For example, if someone tries to fetch `/api/secret-sandwich-recipes` without authenticating, the server should respond with a clear message and a `WWW-Authenticate` header:
+
+```ts
+const hasToken = request.headers.get('authorization')
+if (!hasToken) {
+	return new Response('Unauthorized', {
+		status: 401,
+		headers: {
+			'WWW-Authenticate': 'Bearer',
+		},
+	})
+}
+```
+
+This check is the first and most basic requirement for a secure journal app. The `WWW-Authenticate` header in the response tells the client what kind of credentials are needed to try again.
+
+<callout-info>
+	If a request is missing the `Authorization` header, always include the
+	`WWW-Authenticate` header in your 401 response. This helps clients know how to
+	try again.
+</callout-info>
+
+Without this check, nothing else about security matters. Make sure every request is challenged at the door.
+
+📜 For more details, see the [MDN documentation on WWW-Authenticate](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate).
diff --git a/exercises/02.init/01.solution.authenticate/README.mdx b/exercises/02.init/01.solution.authenticate/README.mdx
@@ -1 +1,3 @@
 # Authenticate Header
+
+👨‍💼 Fantastic progress! We've just ensured that every request to our journal app is properly challenged for credentials. Now, if a client tries to access protected resources without an Authorization header, the server responds with a `401 Unauthorized` and a clear `WWW-Authenticate` header. This makes it obvious to clients what they need to do next, improving both security and user experience (while keeping us complient with the OAuth and MCP Authorization spec). Only authenticated users can move forward, keeping journal data safe and access predictable for everyone.
diff --git a/exercises/02.init/02.problem.params/README.mdx b/exercises/02.init/02.problem.params/README.mdx
@@ -1 +1,18 @@
 # Auth Params
+
+👨‍💼 In EpicMe, when a user tries to access a protected journal entry, it's not enough to simply block them. We need to let them know why. If a request is missing the right credentials, the server should respond with a `WWW-Authenticate` header that includes extra details, called auth params, so the client understands what went wrong and how to fix it.
+
+For example, if a robot tries to fetch `/api/lemonade` without the right credentials, the response should include a realm and a resource_metadata parameter:
+
+```
+WWW-Authenticate: Bearer realm="EpicMe", resource_metadata="https://lemonade-stand.com/.well-known/oauth-protected-resource/mcp"
+```
+
+- **realm**: Identifies the protected area (like a journal or a lemonade stand) so clients know which resource needs credentials.
+- **resource_metadata**: A URL pointing to metadata about the protected resource, helping clients discover more about what they're trying to access.
+
+This helps clients know not just that they're blocked, but also where to look for more information about the protected resource.
+
+For more details, see the [MDN documentation on WWW-Authenticate](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate).
+
+Let's make sure our API gives helpful feedback when things go wrong!
diff --git a/exercises/02.init/02.solution.params/README.mdx b/exercises/02.init/02.solution.params/README.mdx
@@ -1 +1,3 @@
 # Auth Params
+
+👨‍💼 Great job! We've just made our API much more helpful for clients by including detailed auth params in the `WWW-Authenticate` header when access is denied. Now, when a request is missing the right credentials, the response not only blocks access but also provides a `realm` and a `resource_metadata` URL. This gives clients clear guidance on what resource they're trying to access and where to find more information, making it easier for them to recover and try again. This improvement leads to a smoother integration experience and helps clients build smarter, more user-friendly apps.
diff --git a/exercises/02.init/FINISHED.mdx b/exercises/02.init/FINISHED.mdx
@@ -1 +1,3 @@
 # Initialize OAuth Flow
+
+Woo! You did it! You've secured our MCP server by requiring the `Authorization` header and returning a `WWW-Authenticate` header with helpful details. This blocks unauthorized access and guides clients on how to authenticate.
diff --git a/exercises/02.init/README.mdx b/exercises/02.init/README.mdx
@@ -1 +1,72 @@
 # Initialize OAuth Flow
+
+Modern web applications need a way to securely identify users and protect resources. The first step in this process is checking for an `Authorization` header on incoming requests. This is foundational for any OAuth flow.
+
+In this exercise, you'll:
+
+- Check for the presence of the `Authorization` header
+- Respond with a `401 Unauthorized` and a `WWW-Authenticate` header if it's missing
+
+<callout-info>
+	The `Authorization` header is how clients prove their identity. If it's
+	missing, your server must reject the request and tell the client how to
+	authenticate.
+</callout-info>
+
+## Why does this matter?
+
+Without this check, anyone could access protected endpoints on resource servers without credentials. By enforcing this, you ensure only authenticated clients can proceed.
+
+## Example: Checking the Authorization Header
+
+```ts
+const authHeader = request.headers.get('authorization')
+if (!authHeader) {
+	return new Response('Missing Authorization header', {
+		status: 401,
+		headers: {
+			'WWW-Authenticate': 'Bearer',
+		},
+	})
+}
+```
+
+<callout-warning>
+	Always include the `WWW-Authenticate` header in your 401 responses. This tells
+	clients what kind of authentication is required.
+</callout-warning>
+
+## About the WWW-Authenticate Header
+
+The `WWW-Authenticate` header tells the client what authentication scheme is required and can include additional parameters (called "auth params") that provide more details about how to authenticate.
+
+The simplest value is just the scheme:
+
+```
+WWW-Authenticate: Bearer
+```
+
+But you can also include auth params, such as `realm`, `error`, or `error_description`:
+
+```
+WWW-Authenticate: Bearer realm="example", error="invalid_token", error_description="The access token expired"
+```
+
+- **realm**: A string identifying the protected area (useful for clients to display to users)
+- **error**: A short error code (like `invalid_token` or `insufficient_scope`)
+- **error_description**: A human-readable explanation of the error
+
+These parameters help clients understand why authentication failed and what to do next. You can include as many or as few as make sense for your use case.
+
+For more details and a full list of possible parameters, see the [OAuth 2.0 RFC, section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) and [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate).
+
+## Recommended Practices
+
+- Always check for the `Authorization` header on protected endpoints
+- Use the `WWW-Authenticate` header in 401 responses
+- Return clear, actionable error messages
+
+## References
+
+- 📜 [OAuth 2.0 RFC](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1)
+- 📜 [MDN: WWW-Authenticate](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate)

Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
`1`	`1`	`# Authenticate Header`
	`2`	`+`
	`3`	+👨‍💼 Fantastic progress! We've just ensured that every request to our journal app is properly challenged for credentials. Now, if a client tries to access protected resources without an Authorization header, the server responds with a `401 Unauthorized` and a clear `WWW-Authenticate` header. This makes it obvious to clients what they need to do next, improving both security and user experience (while keeping us complient with the OAuth and MCP Authorization spec). Only authenticated users can move forward, keeping journal data safe and access predictable for everyone.