From a85e174bb89eb24732378458ca7293af6c28c4a8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 6 Feb 2026 17:03:21 +0000 Subject: [PATCH 1/2] docs: update MCP OAuth error handling documentation Updates documentation to reflect improved OAuth error handling from cloudflare/agents#850. Changes: - Update customHandler examples to properly check result.authSuccess - Document MCPClientOAuthResult type with authSuccess and authError fields - Add configureOAuthCallback() API reference documentation - Document default error page behavior when no callback config is provided - Add error field to MCPServersState type for failed connections - Add examples showing proper error handling in React applications Co-Authored-By: Claude Sonnet 4.5 --- .../docs/agents/guides/oauth-mcp-client.mdx | 63 +++++++--- .../model-context-protocol/mcp-client-api.mdx | 109 ++++++++++++++++-- 2 files changed, 149 insertions(+), 23 deletions(-) diff --git a/src/content/docs/agents/guides/oauth-mcp-client.mdx b/src/content/docs/agents/guides/oauth-mcp-client.mdx index d6da6398e11..6ee6dcc5742 100644 --- a/src/content/docs/agents/guides/oauth-mcp-client.mdx +++ b/src/content/docs/agents/guides/oauth-mcp-client.mdx @@ -70,7 +70,7 @@ Instead of an automatic redirect, you can present the `authUrl` to your user as ## Configure callback behavior -After OAuth completes, the provider redirects back to your Agent's callback URL. Configure what happens next. +After OAuth completes, the provider redirects back to your Agent's callback URL. By default, successful authentication redirects to your application origin, while failed authentication displays an HTML error page with the error message. ### Redirect to your application @@ -93,9 +93,9 @@ export class MyAgent extends Agent { Users return to `/dashboard` on success or `/auth-error?error=` on failure. -### Close popup window +### Custom handler for popup windows -If you opened OAuth in a popup, close it automatically when complete: +If you opened OAuth in a popup, use a custom handler to close it automatically. The handler receives an `MCPClientOAuthResult` object and must check `authSuccess` to handle both success and error cases: @@ -112,13 +112,25 @@ export class MyAgent extends Agent { return new Response("", { headers: { "content-type": "text/html" }, }); - } else { - // Error - show message, then close - return new Response( - ``, - { headers: { "content-type": "text/html" } }, - ); } + // Error - show message briefly, then close + const error = result.authError || "Unknown error"; + return new Response( + ` + +Authentication Failed + +

Authentication Failed

+

${error}

+

This window will close automatically...

+ + +`, + { + headers: { "content-type": "text/html" }, + status: 400, + }, + ); }, }); } @@ -127,6 +139,12 @@ export class MyAgent extends Agent { +:::note[Important] + +Always check `result.authSuccess` in your custom handler. The handler is called for both successful and failed authentication attempts. Without this check, authentication errors will be ignored and users will not know why the connection failed. + +::: + Your main application can detect the popup closing and refresh the connection status. ## Monitor connection status @@ -221,7 +239,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` field contains the error message. Display the error to your users and allow them to retry: @@ -270,7 +288,7 @@ function App() { {server.name}: {server.state} {server.state === "failed" && (
-

Connection failed. Please try again.

+ {server.error &&

Error: {server.error}

}