docs: Update MCP client API for connection state improvements

Sync documentation for PR #672 which introduces:
- MCPConnectionState enum with standardized connection states
- Breaking change to addMcpServer() return type (now discriminated union)
- New error throwing behavior for connection/discovery failures
- New "connected" state between connection and discovery
- New discoverIfConnected() function for capability discovery

Updated mcp-client-api.mdx with:
- Connection state lifecycle documentation
- Updated addMcpServer() signature and examples with try-catch
- Error handling requirements and examples
- Updated getMcpServers() return type with new "connected" state
- Breaking change callouts for error handling requirements

Added comprehensive changelog entry documenting breaking changes and new features.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: github-actions[bot]

src/content/changelog/agents/2025-11-26-mcp-connection-state-improvements.mdx

@@ -0,0 +1,86 @@
+---
+title: MCP connection state improvements and standardized discovery
+description: Introduces MCPConnectionState enum, improved error handling, and separates connection from discovery phases
+products:
+  - agents
+  - workers
+date: 2025-11-26
+---
+
+The latest update to [@cloudflare/agents](https://github.com/cloudflare/agents) brings improvements to MCP client connection lifecycle management and error handling. This release standardizes connection states and makes discovery failures more visible.
+
+## Breaking changes
+
+### `addMcpServer()` return type changed
+
+The `addMcpServer()` method now returns a discriminated union that includes the connection state:
+
+```ts
+// Before
+const { id, authUrl } = await this.addMcpServer("Server", "https://...");
+if (authUrl) {
+  // Handle OAuth
+}
+
+// After
+const result = await this.addMcpServer("Server", "https://...");
+if (result.state === "authenticating") {
+  // Handle OAuth with result.authUrl
+}
+```
+
+### Error handling now required
+
+`addMcpServer()` now throws errors when connection or discovery fails. Previously, servers would silently enter the `failed` state. Update your code to handle errors:
+
+```ts
+try {
+  const result = await this.addMcpServer("Server", "https://...");
+  // Connection succeeded
+} catch (error) {
+  // Handle connection or discovery failure
+  console.error(`Failed to connect: ${error.message}`);
+}
+```
+
+### `ClientConnection.init()` no longer discovers automatically
+
+Tool discovery must now be explicitly triggered after initialization. The `MCPClientManager` handles this automatically, but if you are using `ClientConnection` directly, you need to call `discover()` after successful initialization.
+
+## New features
+
+### MCPConnectionState enum
+
+A new `MCPConnectionState` enum standardizes connection states:
+
+- `authenticating` — Waiting for OAuth authorization
+- `connecting` — Establishing transport connection
+- `connected` — Transport connected but tools not yet discovered
+- `discovering` — Discovering server capabilities
+- `ready` — Fully connected with all capabilities available
+- `failed` — Connection failed
+
+The new `connected` state separates transport connection from capability discovery, providing better visibility into the connection lifecycle.
+
+### `discoverIfConnected()` function
+
+A new convenience function on `MCPClientManager` simplifies capability discovery:
+
+```ts
+const result = await this.mcp.discoverIfConnected(serverId);
+if (!result.success) {
+  console.error(`Discovery failed: ${result.error}`);
+}
+```
+
+## Improvements
+
+### Immediate error reporting
+
+Discovery failures now throw errors immediately using `Promise.all()` instead of continuing with empty arrays. This makes issues visible immediately rather than silently degrading functionality.
+
+### Better connection state visibility
+
+The connection state machine is now formalized with explicit enum values, making it easier to understand and monitor connection lifecycle in `getMcpServers()`.
+
+Learn more in the [MCP Client API documentation](/agents/model-context-protocol/mcp-client-api/).

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

@@ -25,18 +25,22 @@ export class MyAgent extends Agent<Env, never> {
 		const url = new URL(request.url);
 
 		if (url.pathname === "/connect" && request.method === "POST") {
-			const { id, authUrl } = await this.addMcpServer(
-				"Weather API",
-				"https://weather-mcp.example.com/mcp",
-			);
-
-			if (authUrl) {
-				return new Response(JSON.stringify({ authUrl }), {
-					headers: { "Content-Type": "application/json" },
-				});
+			try {
+				const result = await this.addMcpServer(
+					"Weather API",
+					"https://weather-mcp.example.com/mcp",
+				);
+
+				if (result.state === "authenticating") {
+					return new Response(JSON.stringify({ authUrl: result.authUrl }), {
+						headers: { "Content-Type": "application/json" },
+					});
+				}
+
+				return new Response(`Connected: ${result.id}`, { status: 200 });
+			} catch (error) {
+				return new Response(`Connection failed: ${error}`, { status: 500 });
 			}
-
-			return new Response(`Connected: ${id}`, { status: 200 });
 		}
 	}
 }
@@ -46,6 +50,27 @@ export class MyAgent extends Agent<Env, never> {
 
 Connections persist in the Agent's [SQL storage](/agents/api-reference/store-and-sync-state), and when an Agent connects to an MCP server, all tools from that server become available automatically.
 
+## Connection States
+
+When connecting to an MCP server, the connection progresses through different states represented by the `MCPConnectionState` enum:
+
+- **`authenticating`** — Server requires OAuth; waiting for user authentication
+- **`connecting`** — Establishing connection to the server
+- **`connected`** — Transport connection established, awaiting initialization
+- **`discovering`** — Retrieving available tools, prompts, and resources
+- **`ready`** — Fully connected and all capabilities available
+- **`failed`** — Connection or discovery failed
+
+### Typical Connection Flow
+
+**For servers without OAuth:**
+`connecting` → `connected` → `discovering` → `ready`
+
+**For servers with OAuth:**
+`authenticating` → (user completes OAuth) → `connecting` → `connected` → `discovering` → `ready`
+
+If any step fails, the state transitions to `failed` and an error is thrown.
+
 ## Agent MCP Client Methods
 
 ### `addMcpServer()`
@@ -65,7 +90,10 @@ async addMcpServer(
       type?: "sse" | "streamable-http" | "auto";
     };
   }
-): Promise<{ id: string; authUrl: string | undefined }>
+): Promise<
+  | { id: string; state: "authenticating"; authUrl: string }
+  | { id: string; state: "ready"; authUrl?: undefined }
+>
 ```
 
 #### Parameters
@@ -82,10 +110,21 @@ async addMcpServer(
 
 #### Returns
 
-A Promise that resolves to an object containing:
+A Promise that resolves to a discriminated union based on the connection state:
 
+**When authentication is required:**
 - **`id`** (string) — Unique identifier for this server connection
-- **`authUrl`** (string | undefined) — OAuth authorization URL if authentication is required, otherwise `undefined`
+- **`state`** (`"authenticating"`) — Indicates OAuth authentication is needed
+- **`authUrl`** (string) — OAuth authorization URL for user authentication
+
+**When connection is ready:**
+- **`id`** (string) — Unique identifier for this server connection
+- **`state`** (`"ready"`) — Indicates the server is fully connected and ready
+- **`authUrl`** (undefined) — No authentication URL when ready
+
+#### Throws
+
+Throws an error if the connection or discovery process fails. Always wrap `addMcpServer()` calls in try-catch blocks to handle connection failures gracefully.
 
 #### Example
 
@@ -94,26 +133,36 @@ A Promise that resolves to an object containing:
 ```ts title="src/index.ts"
 export class MyAgent extends Agent<Env, never> {
 	async onRequest(request: Request): Promise<Response> {
-		const { id, authUrl } = await this.addMcpServer(
-			"Weather API",
-			"https://weather-mcp.example.com/mcp",
-		);
-
-		if (authUrl) {
-			// User needs to complete OAuth flow
-			return new Response(JSON.stringify({ serverId: id, authUrl }), {
-				headers: { "Content-Type": "application/json" },
-			});
-		}
+		try {
+			const result = await this.addMcpServer(
+				"Weather API",
+				"https://weather-mcp.example.com/mcp",
+			);
 
-		return new Response("Connected", { status: 200 });
+			if (result.state === "authenticating") {
+				// User needs to complete OAuth flow
+				return new Response(JSON.stringify({ serverId: result.id, authUrl: result.authUrl }), {
+					headers: { "Content-Type": "application/json" },
+				});
+			}
+
+			return new Response(`Connected: ${result.id}`, { status: 200 });
+		} catch (error) {
+			return new Response(`Connection failed: ${error}`, { status: 500 });
+		}
 	}
 }
 ```
 
 </TypeScriptExample>
 
-If the MCP server requires OAuth authentication, `authUrl` will be returned for user authentication. Connections persist across requests and the Agent will automatically reconnect if the connection is lost.
+If the MCP server requires OAuth authentication, the response will have `state: "authenticating"` with an `authUrl` for user authentication. Connections persist across requests and the Agent will automatically reconnect if the connection is lost.
+
+:::note[Breaking Change: Error Handling Required]
+
+As of the latest version, `addMcpServer()` now throws errors on connection or discovery failures instead of returning a failed state. Always wrap calls in try-catch blocks to handle errors gracefully. The return type is now a discriminated union based on the connection state.
+
+:::
 
 :::note[Default JSON Schema Validation]
 
@@ -193,6 +242,7 @@ An `MCPServersState` object containing:
 			state:
 				| "authenticating"
 				| "connecting"
+				| "connected"
 				| "ready"
 				| "discovering"
 				| "failed";
@@ -228,7 +278,7 @@ export class MyAgent extends Agent<Env, never> {
 
 </TypeScriptExample>
 
-The `state` field can be: `authenticating`, `connecting`, `ready`, `discovering`, or `failed`. Use this method to monitor connection status, list available tools, or build UI for connected servers.
+The `state` field can be: `authenticating`, `connecting`, `connected`, `ready`, `discovering`, or `failed`. Use this method to monitor connection status, list available tools, or build UI for connected servers.
 
 ## OAuth Configuration