docs: Update MCP OAuth security documentation

Update OAuth documentation to reflect security improvements from PR #841:
- Remove vulnerable pattern of displaying errors via script tags
- Document new error field on MCPServer type for safe error display
- Update custom OAuth handler examples to use secure pattern
- Add note about XSS prevention in popup OAuth flows

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: github-actions[bot]

src/content/docs/agents/guides/oauth-mcp-client.mdx

@@ -96,24 +96,15 @@ If you opened OAuth in a popup, close it automatically when complete:
 
 ```ts title="src/index.ts"
 import { Agent } from "agents";
-import type { MCPClientOAuthResult } from "agents/mcp";
 
 export class MyAgent extends Agent<Env, never> {
 	onStart() {
 		this.mcp.configureOAuthCallback({
-			customHandler: (result: MCPClientOAuthResult) => {
-				if (result.authSuccess) {
-					// Success - close the popup
-					return new Response("<script>window.close();</script>", {
-						headers: { "content-type": "text/html" },
-					});
-				} else {
-					// Error - show message, then close
-					return new Response(
-						`<script>alert('Authorization failed: ${result.authError}'); window.close();</script>`,
-						{ headers: { "content-type": "text/html" } },
-					);
-				}
+			customHandler: () => {
+				// Close popup on both success and failure
+				return new Response("<script>window.close();</script>", {
+					headers: { "content-type": "text/html" },
+				});
 			},
 		});
 	}
@@ -124,6 +115,12 @@ export class MyAgent extends Agent<Env, never> {
 
 Your main application can detect the popup closing and refresh the connection status.
 
+:::note[Error handling in popup flow]
+
+When using the popup approach, authentication errors are automatically stored in the connection state with the `error` field on the `MCPServer` object. Display these errors in your main application UI rather than in the popup window. This approach prevents XSS vulnerabilities and provides better user experience.
+
+:::
+
 ## Monitor connection status
 
 ### React applications
@@ -216,7 +213,7 @@ Connection states flow: `authenticating` (needs OAuth) → `connecting` (complet
 
 ## Handle failures
 
-When OAuth fails, the connection state becomes `"failed"`. Detect this in your UI and allow users to retry:
+When OAuth fails, the connection state becomes `"failed"`. The `error` field on the server object contains details about the failure. Detect this in your UI and allow users to retry:
 
 <TypeScriptExample>
 
@@ -262,7 +259,7 @@ function App() {
 
 					{server.state === "failed" && (
 						<div>
-							<p>Connection failed. Please try again.</p>
+							<p>Connection failed: {server.error || "Unknown error"}</p>
 							<button onClick={() => handleRetry(id, server.server_url, server.name)}>
 								Retry Connection
 							</button>
@@ -294,7 +291,6 @@ This example demonstrates a complete OAuth integration with Cloudflare Observabi
 
 ```ts title="src/index.ts"
 import { Agent, routeAgentRequest } from "agents";
-import type { MCPClientOAuthResult } from "agents/mcp";
 
 type Env = {
 	MyAgent: DurableObjectNamespace<MyAgent>;
@@ -303,17 +299,10 @@ type Env = {
 export class MyAgent extends Agent<Env, never> {
 	onStart() {
 		this.mcp.configureOAuthCallback({
-			customHandler: (result: MCPClientOAuthResult) => {
-				if (result.authSuccess) {
-					return new Response("<script>window.close();</script>", {
-						headers: { "content-type": "text/html" },
-					});
-				} else {
-					return new Response(
-						`<script>alert('Authorization failed: ${result.authError}'); window.close();</script>`,
-						{ headers: { "content-type": "text/html" } },
-					);
-				}
+			customHandler: () => {
+				return new Response("<script>window.close();</script>", {
+					headers: { "content-type": "text/html" },
+				});
 			},
 		});
 	}
@@ -348,6 +337,7 @@ export class MyAgent extends Agent<Env, never> {
 					name: server.name,
 					state: server.state,
 					authUrl: server.auth_url,
+					error: server.error,
 				}),
 			);
 			return Response.json(connections);

src/content/docs/agents/model-context-protocol/mcp-client-api.mdx

@@ -206,6 +206,7 @@ An `MCPServersState` object containing:
 				| "discovering"
 				| "ready"
 				| "failed";
+			error: string | null;
 			capabilities: ServerCapabilities | null;
 			instructions: string | null;
 		}
@@ -245,7 +246,9 @@ The `state` field indicates the connection lifecycle:
 - `connected` — Transport connection established
 - `discovering` — Discovering server capabilities (tools, resources, prompts)
 - `ready` — Fully connected and operational
-- `failed` — Connection failed
+- `failed` — Connection failed (check `error` field for details)
+
+The `error` field contains a human-readable error message when `state` is `"failed"`. Error messages are automatically sanitized to prevent XSS vulnerabilities. This field is `null` for all other states.
 
 Use this method to monitor connection status, list available tools, or build UI for connected servers.