fix: escape html in external oauth error message

[agents-git-bot]

Summary

This PR syncs documentation changes from cloudflare/agents#841 which fixed an XSS vulnerability in OAuth error handling for MCP clients.

Changes

• OAuth callback handler simplified: The customHandler no longer receives MCPClientOAuthResult with error information. It now simply closes the popup window, and errors are handled automatically by the SDK.
• New error field: Added documentation for the error field in MCPServer type, which stores connection errors for UI display.
• Security improvement: Error messages from external OAuth providers are automatically escaped to prevent XSS attacks, making them safe to display directly in UIs.
• Updated examples: All OAuth integration examples now demonstrate the correct pattern of displaying errors from connection state instead of handling them in script alerts.

Files Changed

• /agents/guides/oauth-mcp-client/ - Updated OAuth integration guide with new error handling patterns
• /agents/model-context-protocol/mcp-client-api/ - Added error field to MCPServer type documentation

Related

• Original PR: fix: escape html in external oauth error message agents#841
• Security fix: Escapes HTML in external OAuth error messages to prevent XSS attacks

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/agents/	@irvinebroque, @rita3ko, @elithrar, @thomasgauvin, @threepointone, @whoiskatrin, @cloudflare/pcx-technical-writing, @cloudflare/ai-agents, @cloudflare/dev-plat-leads

[github-actions]

Preview URL: https://5fdb2675.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-841.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/agents/guides/oauth-mcp-client/	https://sync-docs-pr-841.preview.developers.cloudflare.com/agents/guides/oauth-mcp-client/
https://developers.cloudflare.com/agents/model-context-protocol/mcp-client-api/	https://sync-docs-pr-841.preview.developers.cloudflare.com/agents/model-context-protocol/mcp-client-api/

[mattzcarey]

looks good to me. @threepointone to go with the PR

[elithrar]

/bonk review

[ask-bonk]

Here's my review:

Review Summary

This PR correctly documents the security fix from cloudflare/agents#841, which eliminates an XSS vulnerability where error messages from external OAuth providers were interpolated directly into <script> tags via template literals.

Changes look good

1. oauth-mcp-client.mdx — The customHandler callback is simplified to no longer receive MCPClientOAuthResult. The old pattern of alert('Authorization failed: ${result.authError}') was the XSS vector. Now the handler just closes the popup unconditionally, and errors are surfaced through server.error in the connection state. The React examples are updated accordingly to display server.error when state === "failed".

2. mcp-client-api.mdx — The error field is added to the MCPServer type definition, and the failed state description now references it. The XSS safety note is clear and accurate.

Issue: Inconsistent customHandler example in mcp-client-api.mdx

The "Custom OAuth callback handling" example at src/content/docs/agents/model-context-protocol/mcp-client-api.mdx:210-218 still uses the old API pattern:

customHandler: (result) => {
    if (result.authSuccess) {
        return new Response("<script>window.close();</script>", {
            headers: { "content-type": "text/html" },
        });
    }
    return new Response("Auth failed", { status: 400 });
},

This is inconsistent with the updated examples in oauth-mcp-client.mdx, where customHandler no longer receives a result parameter. If the SDK change removed MCPClientOAuthResult from the callback signature, this example is now incorrect and should be updated to match the new pattern:

customHandler: () => {
    return new Response("<script>window.close();</script>", {
        headers: { "content-type": "text/html" },
    });
},

This should be fixed before merging to avoid documenting a broken API pattern in the reference page.

Minor note

The import type { MCPClientOAuthResult } from "agents/mcp" removal in the guide is correct — it's no longer used. But the MCP client API page never imported it explicitly in its examples, so no change needed there beyond fixing the customHandler signature.

github run

[elithrar]

/bonk resolve merge conflicts and review

[ask-bonk]

Summary

Merge Conflicts

No real merge conflicts on the two files changed by this PR. The branch has an "unrelated histories" issue with production (likely from how the sync bot created the branch), but the two commits since the last merge (ab4254b, a64f431) don't touch the same files as this PR.

Fixes Applied

Three issues were found and fixed in a single commit:

1. mcp-client-api.mdx:210-218 — customHandler example used the old API pattern (result) => { if (result.authSuccess) ... }. Updated to the new no-arg () => { ... } signature, matching the pattern in oauth-mcp-client.mdx. This was the issue flagged in the previous /bonk review.

2. mcp-client-api.mdx:373 — Client-side React example used server.connectionState which doesn't exist on the MCPServersState type. Fixed to server.state.

3. oauth-mcp-client.mdx:132,224 — Two React examples used useState without importing it. Added import { useState } from "react" to both code blocks.

Review Notes

• The core documentation changes (simplified customHandler, new error field, XSS safety notes) are correct and consistent
• The error: string | null field is properly documented in the MCPServersState type at mcp-client-api.mdx:480
• The XSS safety note at mcp-client-api.mdx:499 is accurate
• Minor nit (not fixed): useState<MCPServersState> initial values are missing resourceTemplates — this is a type completeness issue but wouldn't cause runtime errors and is common in doc examples

github run