Fix MCP OAuth callback URL leaking instance name

[agents-git-bot]

Summary

Document the new callbackPath option for addMcpServer() that prevents instance name leakage in MCP OAuth callback URLs when using sendIdentityOnConnect: false.

Changes

• Add callbackPath parameter to addMcpServer() API reference
• Document security requirement: callbackPath is required when sendIdentityOnConnect is false
• Add dedicated security section with example showing how to route custom callback paths
• Explain that callback matching uses the state parameter, not URL path matching

Context

This documentation sync corresponds to cloudflare/agents#868, which fixes a security issue where the default OAuth callback URL exposed sensitive instance names even when developers opted out of identity disclosure via sendIdentityOnConnect: false.

The new callbackPath parameter allows developers to specify a custom callback path that does not include the instance name, and route it to the correct agent instance using getAgentByName().

Test plan

• Review documentation for accuracy and clarity
• Verify examples follow Cloudflare docs style guide
• Confirm TypeScript examples are properly formatted
• Check links and cross-references

🤖 Generated with Claude Code

[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

[elithrar]

/bonk review/fix

[ask-bonk]

Review Summary

The PR documents the new callbackPath option for addMcpServer() that prevents MCP OAuth callback URLs from leaking sensitive instance names. The content and structure are good. I found and fixed two issues in the code example:

Fixes Applied

1. Missing export on SecureAgent class (mcp-client-api.mdx:202): Agent classes must be exported as named exports to work as Durable Object bindings. Changed class SecureAgent to export class SecureAgent, consistent with the pattern used in webhooks.mdx, cross-domain-authentication.mdx, and other docs showing full module examples.

2. Missing await on routeAgentRequest (mcp-client-api.mdx:239): routeAgentRequest() returns Promise<Response>, so without await the || fallback would never trigger (a Promise object is always truthy). Changed to (await routeAgentRequest(request, env)) ?? which is the correct pattern used throughout the routing docs (routing.mdx, webhooks.mdx, quick-start.mdx).

Items That Look Correct

• getAgentByName(env.SecureAgent, instanceName) — correct signature matching all other docs usage
• await on getAgentByName — correctly present
• getInstanceNameFromSession — clearly marked as a placeholder with an explanatory comment
• Agent import — correctly included in the import statement
• API reference additions (callbackPath parameter, updated agentsPrefix description) — accurate and well-written
• The :::note[How callback matching works] admonition — helpful context about state parameter-based matching

github run

[github-actions]

Preview URL: https://57ac3f18.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-868.preview.developers.cloudflare.com

Files with changes (up to 15)

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