docs: update OAuth error handling for MCP clients

Updates documentation to reflect security improvements in OAuth error handling:

- Remove MCPClientOAuthResult from customHandler signature (no longer receives error info)
- Document new `error` field in MCPServer type that stores connection errors
- Update examples to display errors from connection state instead of script alerts
- Add note that error messages are automatically escaped to prevent XSS attacks
- Simplify customHandler examples to only close popup (errors handled separately)

Related to cloudflare/agents#841

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 the popup after OAuth completes
+				return new Response("<script>window.close();</script>", {
+					headers: { "content-type": "text/html" },
+				});
 			},
 		});
 	}
@@ -122,7 +113,7 @@ export class MyAgent extends Agent<Env, never> {
 
 </TypeScriptExample>
 
-Your main application can detect the popup closing and refresh the connection status.
+Your main application can detect the popup closing and refresh the connection status. If OAuth fails, the connection state becomes `"failed"` and the error message is stored in `server.error` for display in your UI.
 
 ## Monitor connection status
 
@@ -163,6 +154,9 @@ function App() {
 							Authorize
 						</button>
 					)}
+					{server.state === "failed" && server.error && (
+						<p className="error">{server.error}</p>
+					)}
 				</div>
 			))}
 		</div>
@@ -216,7 +210,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"` and the error message is stored in the `server.error` field. Display this error in your UI and allow users to retry:
 
 <TypeScriptExample>
 
@@ -262,7 +256,7 @@ function App() {
 
 					{server.state === "failed" && (
 						<div>
-							<p>Connection failed. Please try again.</p>
+							{server.error && <p className="error">{server.error}</p>}
 							<button onClick={() => handleRetry(id, server.server_url, server.name)}>
 								Retry Connection
 							</button>
@@ -284,17 +278,16 @@ Common failure reasons:
 - **Permission denied**: User lacks required permissions
 - **Expired session**: OAuth session timed out
 
-Failed connections remain in state until removed with `removeMcpServer(serverId)`.
+Failed connections remain in state until removed with `removeMcpServer(serverId)`. The error message is automatically escaped to prevent XSS attacks, so it is safe to display directly in your UI.
 
 ## Complete example
 
-This example demonstrates a complete OAuth integration with Cloudflare Observability. Users connect, authorize in a popup window, and the connection becomes available.
+This example demonstrates a complete OAuth integration with Cloudflare Observability. Users connect, authorize in a popup window, and the connection becomes available. Errors are automatically stored in the connection state for display in your UI.
 
 <TypeScriptExample>
 
 ```ts title="src/index.ts"
 import { Agent, routeAgentRequest } from "agents";
-import type { MCPClientOAuthResult } from "agents/mcp";
 
 type Env = {
 	MyAgent: DurableObjectNamespace<MyAgent>;
@@ -303,17 +296,11 @@ 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: () => {
+				// Close popup after OAuth completes (success or failure)
+				return new Response("<script>window.close();</script>", {
+					headers: { "content-type": "text/html" },
+				});
 			},
 		});
 	}

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

@@ -208,6 +208,7 @@ An `MCPServersState` object containing:
 				| "failed";
 			capabilities: ServerCapabilities | null;
 			instructions: string | null;
+			error: string | null;
 		}
 	>;
 	tools: Array<Tool & { serverId: string }>;
@@ -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 (see `error` field for details)
+
+The `error` field contains an error message when `state` is `"failed"`. Error messages from external OAuth providers are automatically escaped to prevent XSS attacks, making them safe to display directly in your UI.
 
 Use this method to monitor connection status, list available tools, or build UI for connected servers.