docs: enhance CORS and authentication server metadata documentation with detailed explanations and examples

Author: kentcdodds

exercises/01.discovery/01.problem.cors/README.mdx

@@ -1 +1,88 @@
 # CORS
+
+👨‍💼 In our MCP server's case, users will always be accessing us from either a different domain or a desktop application. This means every single request is cross-origin by nature, making CORS headers absolutely essential for our server to function at all.
+
+If we can't handle cross-origin requests properly, users will encounter frustrating errors and won't be able to access the server's capabilities from their preferred applications or domains. The problem is: how do we enable secure cross-origin communication while maintaining the security standards that protect our users and server?
+
+```ts
+// Example: A user trying to access our MCP server from a different domain
+const response = await fetch('https://our-mcp-server.com/mcp', {
+	method: 'POST',
+	headers: {
+		'Content-Type': 'application/json',
+		'mcp-protocol-version': '2024-11-05',
+	},
+	body: JSON.stringify({
+		jsonrpc: '2.0',
+		id: 1,
+		method: 'tools/list',
+	}),
+})
+```
+
+Without proper CORS headers, this request would fail with a "CORS policy" error, leaving users unable to connect to our server from their applications. This breaks the fundamental promise of MCP - seamless integration across different tools and platforms.
+
+Whether users are connecting from a web application on a different domain or from a desktop application like VS Code, CORS headers are the gateway that allows these cross-origin requests to succeed.
+
+To solve this, we need to implement CORS support that allows legitimate cross-origin requests while maintaining security. The key is to add the right headers to our responses, especially for the `/.well-known` endpoint which needs to be publicly accessible.
+
+<callout-warning class="important">
+	CORS is not just about adding headers - it's about enabling secure
+	cross-origin communication while protecting against malicious requests. The
+	`/.well-known` endpoint is particularly important as it's used for service
+	discovery.
+</callout-warning>
+
+<callout-info>
+	🚀 The `withCors` utility function will handle the complexity of CORS headers,
+	preflight requests, and response modification, so you can focus on the
+	business logic.
+</callout-info>
+
+```mermaid
+sequenceDiagram
+    Client->>MCP Server: OPTIONS request (preflight)
+    MCP Server-->>Client: 204 with CORS headers
+    Client->>MCP Server: Actual request
+    MCP Server-->>Client: Response with CORS headers
+```
+
+<callout-muted>
+	📜 For more details on CORS and how it works, see the [MDN documentation on
+	CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
+</callout-muted>
+
+The goal is to make our MCP server accessible from any legitimate client while maintaining the security and reliability that users expect. Users should be able to discover and connect to our server without worrying about origin restrictions.
+
+🧝‍♀️ By the way, I've prepared a `withCors` utility function in <InlineFile file="src/utils.ts" /> that will handle all the CORS complexity for you. You just need to wrap your existing handler with it and configure the appropriate headers for the `/.well-known` endpoint.
+
+Here's a simple example of how to use it:
+
+```ts
+// Before: Basic handler
+export default {
+	fetch: async (request, env, ctx) => {
+		// Your existing logic here
+		return new Response('Hello World')
+	},
+}
+
+// After: Wrapped with CORS support
+export default {
+	fetch: withCors({
+		getCorsHeaders: (request) => {
+			// Return CORS headers based on the request
+			// 💰 check the request.url property
+			// Return null/undefined for no CORS headers
+		},
+		handler: async (request, env, ctx) => {
+			// Your existing logic here
+			return new Response('Hello World')
+		},
+	}),
+}
+```
+
+👨‍💼 Thanks Kellie! Let's take a look at that.
+
+Now, start by understanding why CORS matters for MCP servers, implement the solution using the provided utility, and test that cross-origin requests work properly.

exercises/01.discovery/01.solution.cors/README.mdx

@@ -1 +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.
+
+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.

exercises/01.discovery/02.problem.as/README.mdx

@@ -1 +1,56 @@
 # Auth Server Metadata
+
+👨‍💼 Now that users can connect to our MCP server from any domain, they need to be able to discover how to authenticate with our system. When users want to access protected resources or perform actions that require authentication, they need to know where to go and what methods are available.
+
+The problem is: how do we provide users with the information they need to authenticate with our OAuth server? Without this metadata, users' clients will be stuck because they can't figure out authentication endpoints and supported features.
+
+```ts
+// Example: A user trying to discover our OAuth server capabilities
+const response = await fetch(
+	'https://our-mcp-server.com/.well-known/oauth-authorization-server',
+)
+const metadata = await response.json()
+// metadata includes things like:
+// - registration_endpoint - how to register a new client for dynamic client registration
+// - authorization_endpoint - where to send users to confirm the connection
+// - token_endpoint - where to request a token once they have a auth code
+// plus more things necessary for the client to set up the connection for the user
+```
+
+This metadata endpoint is the gateway that tells users everything they need to know about our authentication system.
+
+To do this, we need to implement the `/.well-known/oauth-authorization-server` endpoint that returns the OAuth server's metadata. This endpoint will fetch the metadata from our actual OAuth server and relay it to users, making our MCP server a complete authentication discovery hub.
+
+<callout-warning class="important">
+	The OAuth metadata endpoint is a standard that clients expect to find. Without
+	it, clients won't be able to properly integrate authentication into their
+	applications.
+</callout-warning>
+
+<callout-info>
+	🔍 Doing this from our resource server is useful because some clients do not
+	distinguish between the resource server and the auth server and will treat our
+	resource server as the auth server. So we simply proxy to the auth server to
+	get the metadata.
+</callout-info>
+
+```mermaid
+sequenceDiagram
+    Client->>MCP Server: GET /.well-known/oauth-authorization-server
+    MCP Server->>OAuth Server: Fetch metadata from localhost:7788
+    OAuth Server-->>MCP Server: Returns OAuth metadata
+    MCP Server-->>Client: Returns metadata with CORS headers
+```
+
+<callout-muted>
+	📜 For more details on OAuth authorization server metadata, see the [RFC 8414
+	specification](https://tools.ietf.org/html/rfc8414).
+</callout-muted>
+
+The goal is to make authentication discovery seamless and standards-compliant, so users can easily integrate our OAuth system into their applications without any guesswork.
+
+🧝‍♀️ By the way, I've set up the OAuth server to run on localhost:7788, and you'll need to create a new `auth.ts` file to handle the metadata request. The endpoint should fetch from `http://localhost:7788/.well-known/oauth-authorization-server` and return the response.
+
+👨‍💼 Thanks Kellie!
+
+Now, please implement the metadata endpoint.