feat: enums connection state and standardise tool discovery

[agents-git-bot]

Summary

Documentation sync for cloudflare/agents PR #672: feat: enums connection state and standardise tool discovery

This update documents breaking API changes and new features related to MCP connection state management and discovery improvements.

Breaking Changes

addMcpServer() Return Type Changed

• Before: Returns { id: string; authUrl: string | undefined }
• After: Returns discriminated union based on connection state:
  • { id: string; state: MCPConnectionState.AUTHENTICATING; authUrl: string }
  • { id: string; state: MCPConnectionState.READY; authUrl?: undefined }

Error Handling Now Required

• addMcpServer() now throws errors on connection/discovery failures
• Previously would silently continue with empty capabilities
• All examples updated with try-catch blocks
• Added prominent breaking change callout with migration guidance

ClientConnection.init() Behavior Changed

• No longer automatically performs discovery
• Discovery must be explicitly triggered via MCPClientManager

New Features

MCPConnectionState Enum

• Changed from type to enum for better type safety
• Exported from main package: import { MCPConnectionState } from "agents"
• Standardizes connection state values across the codebase

New Connection State: connected

• Separates transport connection from capability discovery
• Provides finer-grained visibility into connection progress
• Allows for explicit discovery control

New Method: discoverIfConnected()

• Added to MCPClientManager
• Simplifies discovery of capabilities per server
• Allows retry of discovery without reconnecting

Documentation Updates

Connection States Section

• New comprehensive section explaining the MCPConnectionState enum
• Documents all six states with detailed descriptions
• Shows state transition flows for OAuth and non-OAuth servers
• Includes code examples using the enum

Updated Examples

• All code examples now import and use MCPConnectionState enum
• Proper error handling with try-catch blocks
• Migration guidance for checking result.state vs result.authUrl
• Updated to use enum values instead of string literals

Type Signatures

• Updated addMcpServer() signature to show discriminated union
• Return type now uses typeof MCPConnectionState.AUTHENTICATING
• Added comprehensive "Throws" documentation
• Documented error persistence in storage

getMcpServers() Updates

• Added connected state to state field documentation
• Detailed descriptions for all six connection states
• Clarified state meanings and transitions

Test Plan

• Verify all code examples are syntactically correct
• Ensure enum imports are properly shown
• Confirm breaking change callouts are prominent
• Check all state values match the enum

Related PR

cloudflare/agents#672

🤖 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/changelog/	@cloudflare/pm-changelogs, @cloudflare/pcx-technical-writing
/src/content/docs/agents/	@irvinebroque, @rita3ko, @elithrar, @thomasgauvin, @threepointone, @cloudflare/pcx-technical-writing

[github-actions]

Preview URL: https://3a95eefb.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-672.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/changelog/2025-11-26-mcp-connection-state-improvements/	https://sync-docs-pr-672.preview.developers.cloudflare.com/changelog/2025-11-26-mcp-connection-state-improvements/
https://developers.cloudflare.com/agents/model-context-protocol/mcp-client-api/	https://sync-docs-pr-672.preview.developers.cloudflare.com/agents/model-context-protocol/mcp-client-api/

[agents-git-bot]

Added additional enhancements to the documentation:

• ✅ Added comprehensive changelog entry for MCP connection state improvements (new file: 2025-11-24-mcp-connection-state-improvements.mdx)
• ✅ Enhanced connection state descriptions with clearer explanations
• ✅ Added version note about v0.0.24 changes
• ✅ Improved formatting with "Connection States" subsection header

The documentation now includes:

• All 6 connection states with detailed descriptions
• Clear explanation of the new connected state
• Version-specific notes for developers upgrading
• Changelog documenting breaking changes and improvements

[agents-git-bot]

Updated Documentation

This PR has been updated with comprehensive documentation for the MCP connection state improvements:

Changes Made

1. Updated addMcpServer() API documentation

   • New discriminated union return type with explicit states
   • Updated examples showing proper error handling
   • Added throws documentation for connection/discovery failures

2. Added Connection State Lifecycle section

   • Documented new MCPConnectionState enum
   • State transition diagrams for OAuth and non-OAuth flows
   • Key behavior changes from previous version

3. Updated getMcpServers() documentation

   • Added new "connected" state to type definitions
   • Comprehensive state descriptions

4. Created comprehensive changelog (2025-11-26-mcp-connection-state-improvements.mdx)

   • All new features documented
   • Bug fixes highlighted
   • Migration guide for breaking changes
   • Before/after code examples

Migration Guide Highlights

The changelog includes detailed migration guidance for:

• MCPClientConnection.init() no longer auto-discovering
• Updated addMcpServer() return type
• New "connected" state in lifecycle

All documentation follows Cloudflare's style guide and uses appropriate components.

🤖 Generated with Claude Code