docs: update MCP connection states and error handling

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 <[email protected]>

Author: github-actions[bot]

src/content/docs/agents/model-context-protocol/mcp-client-api.mdx

@@ -245,6 +245,37 @@ The `state` field indicates the current connection status and follows a state ma
 
 Use this method to monitor connection status, list available tools, or build UI for connected servers.
 
+## Connection State Machine
+
+MCP client connections follow a state machine that ensures proper initialization and capability discovery. The connection states are defined in the `MCPConnectionState` enum:
+
+<TypeScriptExample>
+
+```ts title="src/index.ts"
+import { MCPConnectionState } from "agents/mcp";
+
+// Access state constants
+MCPConnectionState.AUTHENTICATING // "authenticating"
+MCPConnectionState.CONNECTING     // "connecting"
+MCPConnectionState.CONNECTED      // "connected"
+MCPConnectionState.DISCOVERING    // "discovering"
+MCPConnectionState.READY          // "ready"
+MCPConnectionState.FAILED         // "failed"
+```
+
+</TypeScriptExample>
+
+Use these constants when comparing connection states to ensure type safety and avoid string typos.
+
+### Connected vs Ready
+
+The `connected` state was introduced to distinguish between:
+
+- **`connected`** — Transport connection is established, but server capabilities (tools, resources, prompts) have not been discovered yet
+- **`ready`** — Transport connection is established AND all capabilities have been discovered and registered
+
+This separation allows for better error handling during the discovery phase and provides visibility into the connection lifecycle.
+
 ## OAuth Configuration
 
 Customize OAuth callback behavior using `this.mcp.configureOAuthCallback()`:
@@ -266,31 +297,9 @@ export class MyAgent extends Agent<Env, never> {
 
 You can also provide a `customHandler` function for full control over the callback response. Refer to the [OAuth handling guide](/agents/guides/oauth-mcp-client) for details.
 
-## Connection States
-
-The `MCPConnectionState` enum defines all possible connection states:
-
-<TypeScriptExample>
-
-```ts title="src/index.ts"
-import { MCPConnectionState } from "agents/mcp";
-
-// Access state constants
-MCPConnectionState.AUTHENTICATING // "authenticating"
-MCPConnectionState.CONNECTING     // "connecting"
-MCPConnectionState.CONNECTED      // "connected"
-MCPConnectionState.DISCOVERING    // "discovering"
-MCPConnectionState.READY          // "ready"
-MCPConnectionState.FAILED         // "failed"
-```
-
-</TypeScriptExample>
-
-Use these constants when comparing connection states to ensure type safety and avoid string typos.
-
 ## Error Handling
 
-Use error detection utilities to handle connection errors:
+MCP client connections now fail fast with immediate error propagation. If server capability discovery fails, an error is thrown immediately rather than continuing with empty arrays. Use error detection utilities to handle connection errors:
 
 <TypeScriptExample>
 
@@ -307,6 +316,7 @@ export class MyAgent extends Agent<Env, never> {
 			} else if (isTransportNotImplemented(error)) {
 				return new Response("Transport not supported", { status: 400 });
 			}
+			// Discovery failures will also throw errors
 			throw error;
 		}
 	}
@@ -315,6 +325,12 @@ export class MyAgent extends Agent<Env, never> {
 
 </TypeScriptExample>
 
+Common error scenarios:
+
+- **Connection failures** — Network issues or invalid URLs will throw errors during the `connecting` state
+- **Discovery failures** — If the server fails to return capabilities, an error is thrown immediately during the `discovering` state (uses `Promise.all` for fail-fast behavior)
+- **Transport not supported** — If the specified transport type is not implemented by the server, `isTransportNotImplemented()` will return `true`
+
 :::note[Discovery error handling]
 
 Starting with the latest release, MCP client discovery failures now throw errors immediately instead of silently continuing with empty tool arrays. This ensures connection issues are caught early and handled explicitly. Monitor the connection `state` field to detect `failed` states.