feat: enums connection state and standardise tool discovery by mattzcarey · Pull Request #672 · cloudflare/agents

mattzcarey · 2025-11-21T18:44:06Z

also fail fast with promise.all

Deployed to: https://workers-ai-playground.mattzcarey.workers.dev/

changeset-bot · 2025-11-21T18:44:10Z

🦋 Changeset detected

Latest commit: d6c1796

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2025-11-21T18:45:50Z

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@672

commit: d6c1796

claude · 2025-11-21T18:46:08Z

Claude Code Review

Issues Found:

Race condition in discoverAndRegister() (client-connection.ts:306-382): Uses Promise.all() which fails fast on first error, but the parallel operations may still complete after the function returns failure. This could leave partial state (e.g., tools registered but resources failed). Consider using Promise.allSettled() if you want to collect partial results, or document that this is intentional fail-fast behavior.
Missing error message in init() failure path (client-connection.ts:177): When res.state === MCPConnectionState.FAILED but res.error is undefined, the code returns undefined instead of an error message. Add a fallback: return errorMessage || "Connection failed with unknown error".
Timeout cleanup not guaranteed (client-connection.ts:272-283): If abortPromise rejects before timeoutPromise, the timeout may not be cleared. Move clearTimeout to a finally block or ensure it runs in all error paths.
Type inconsistency in tryConnect (client-connection.ts:614-661): Returns MCPClientConnectionResult with state: MCPConnectionState.FAILED on the final fallthrough, but this should be impossible if transports array is non-empty. Consider throwing an error instead or adding a comment explaining why this is defensive programming.
Redundant capability checks (client-connection.ts:489, 506, 525): registerTools(), registerPrompts(), and registerResources() are only called when serverCapabilities.tools/prompts/resources exist (checked in discoverAndRegister), but they re-check with optional chaining. Remove the redundant checks since they create dead code paths.

Testing: Comprehensive test coverage for the connection lifecycle, OAuth flows, discovery timeout/cancellation, and edge cases. Good focus on state machine transitions.

The PR successfully addresses the discovery hanging issue and crash-looping DO problem. The separation of init/discover is architecturally sound.

Synchronizes documentation with cloudflare/agents PR #672 which introduces enum-based connection state management. Changes: - Document new MCPConnectionState enum export with usage examples - Update getMcpServers() return type to use MCPConnectionState enum - Add examples showing type-safe state checking with enum constants - Document fail-fast behavior during capability discovery Related PR: cloudflare/agents#672 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

This documentation sync corresponds to PR #672 in cloudflare/agents: cloudflare/agents#672 Changes: - Document new MCPConnectionState enum for type-safe connection states - Update all code examples to use enum constants instead of string literals - Add migration guide for transitioning from string literals - Document improved error handling with fail-fast behavior - Create changelog entry for the release - Update OAuth flow documentation with enum usage The MCPConnectionState enum provides better type safety when working with MCP server connection states (AUTHENTICATING, CONNECTING, DISCOVERING, READY, FAILED). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

mattzcarey · 2025-11-23T13:27:32Z

needs changeset.

Updates documentation for PR #672 (feat: enums connection state) ## Changes - Added new "connected" state to MCPConnectionState enum - Documented new discoverIfConnected() method for manual capability discovery - Updated connection state machine documentation with detailed descriptions - Added note about discovery failures now throwing errors immediately - Updated getMcpServers() return type to include "connected" state ## API Changes - New connection state "connected" for servers with transport connected but capabilities not yet discovered - New method discoverIfConnected(serverId) for refreshing server capabilities - Discovery failures now throw errors immediately instead of continuing with empty arrays Related PR: cloudflare/agents#672 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Adds comprehensive documentation for MCP connection state improvements: - Add changelog entry for MCP connection state improvements - Enhance connection state descriptions with better explanations - Add version note about new 'connected' state (v0.0.24) - Document fail-fast error handling behavior Builds on existing discoverIfConnected() documentation already in the branch. Related PR: cloudflare/agents#672

threepointone

bit confusing to follow, but stamping to unblock

Synced from cloudflare/agents PR #672 - Document new MCPConnectionState enum with type-safe constants - Add new 'connected' state to connection state machine - Update state transition documentation - Document improved discovery error handling - Add changelog entry for breaking changes and new features Related PR: cloudflare/agents#672 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

This sync updates the documentation to reflect changes from cloudflare/agents PR #672: - Documented new connection state machine with separate CONNECTED and READY states - ClientConnection.init() no longer automatically discovers capabilities - Added MCPConnectionState enum documentation with all possible states - Documented new CONNECTED state for transport connection without capabilities - Added detailed state transition flows for OAuth and non-OAuth connections - Updated error handling section to reflect fail-fast behavior with Promise.all - Added explanations for each connection state - Clarified the difference between CONNECTED and READY states Related PR: cloudflare/agents#672 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Updates documentation for PR cloudflare/agents#672 ## Changes - Updated addMcpServer() return type to discriminated union - Added MCPConnectionState enum documentation - Documented new "connected" state in connection lifecycle - Added connection state transition diagrams - Documented new discovery behavior with timeout and cancellation - Created comprehensive changelog with migration guide ## Breaking Changes - MCPClientConnection.init() no longer auto-discovers capabilities - addMcpServer() return type changed to discriminated union - New "connected" state added to connection lifecycle 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

mattzcarey added 2 commits November 21, 2025 18:05

use enums

2e01de5

move broadcast out of the finally block

1957cb9

use .then

bac8900

agents-git-bot bot mentioned this pull request Nov 21, 2025

feat: enums connection state and standardise tool discovery cloudflare/cloudflare-docs#26690

Closed

4 tasks

wip client connection refactor

3d1aa39

mattzcarey marked this pull request as draft November 23, 2025 13:27

mattzcarey added 2 commits November 24, 2025 13:46

feat: discoverIfConnected to refresh mcp tools.

695b850

changeset

5db3e6f

mattzcarey marked this pull request as ready for review November 24, 2025 13:58

mattzcarey changed the title ~~feat: enums connection state~~ feat: enums connection state and standardise tool discovery Nov 24, 2025

mattzcarey added 3 commits November 24, 2025 14:08

fix types on discover result

30fccd0

allow discovery on ready servers also

0a1c147

fix: allow for duplicate callbacks in connecting state

b0167a8

threepointone approved these changes Nov 25, 2025

View reviewed changes

don't block if failed to get tools

6803061

mattzcarey added 2 commits November 25, 2025 18:29

better error message here

c42eaaa

discover on restore

3dfcf54

mattzcarey added 3 commits November 26, 2025 11:40

discover result types

2c42bc5

use remove rather than closeConnections

2adf444

fix: discovery states

940b6b8

mattzcarey and others added 7 commits November 26, 2025 13:32

move discovery to client connection

efead04

fix: boot loop on slow mcp servers restored in on start

e6e248e

Merge branch 'main' into feat-enums-connection-state

59d338d

fix: merge artifacts

5970ed6

lil test fix.

0e46a53

fix: discover tests

c9cbfbf

update changeset

d6c1796

whoiskatrin merged commit 7c9f8b0 into main Nov 26, 2025
5 checks passed

whoiskatrin deleted the feat-enums-connection-state branch November 26, 2025 15:14

github-actions bot mentioned this pull request Nov 26, 2025

Version Packages #657

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: enums connection state and standardise tool discovery#672

feat: enums connection state and standardise tool discovery#672
whoiskatrin merged 22 commits intomainfrom
feat-enums-connection-state

mattzcarey commented Nov 21, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Nov 21, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Nov 21, 2025 •

edited

Loading

Uh oh!

claude bot commented Nov 21, 2025 •

edited

Loading

Uh oh!

mattzcarey commented Nov 23, 2025

Uh oh!

threepointone left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

mattzcarey commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Claude Code Review

Uh oh!

mattzcarey commented Nov 23, 2025

Uh oh!

threepointone left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mattzcarey commented Nov 21, 2025 •

edited

Loading

changeset-bot bot commented Nov 21, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 21, 2025 •

edited

Loading

claude bot commented Nov 21, 2025 •

edited

Loading