docs: Improve MCP connection state documentation with enum usage

Enhanced documentation to properly reference MCPConnectionState enum:
- Import and use MCPConnectionState enum in all examples
- Update return type signatures to use typeof MCPConnectionState
- Add comprehensive state transition documentation
- Include breaking change callouts with migration guidance
- Document all connection states with detailed descriptions

This provides clearer guidance for developers using the updated API
from PR #672.

Author: github-actions[bot]

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

@@ -9,12 +9,35 @@ sidebar:
 
 import { Render, TypeScriptExample } from "~/components";
 
-Your Agent can connect to external [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers to access tools, resources, and prompts. The `Agent` class provides three methods to manage MCP connections:
+Your Agent can connect to external [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers to access tools, resources, and prompts. The `Agent` class provides three methods to manage MCP connections.
+
+## Connection States
+
+MCP connections progress through several states, represented by the `MCPConnectionState` enum:
+
+```ts
+import { MCPConnectionState } from "agents";
+
+// Available states:
+MCPConnectionState.AUTHENTICATING // Waiting for OAuth authorization
+MCPConnectionState.CONNECTING     // Establishing transport connection
+MCPConnectionState.CONNECTED      // Transport connected, capabilities not yet discovered
+MCPConnectionState.DISCOVERING    // Discovering server capabilities
+MCPConnectionState.READY          // Fully connected and ready to use
+MCPConnectionState.FAILED         // Connection failed
+```
+
+**State transitions:**
+- **Non-OAuth servers**: CONNECTING → CONNECTED → DISCOVERING → READY
+- **OAuth servers**: AUTHENTICATING → (callback) → CONNECTING → CONNECTED → DISCOVERING → READY
+- Any state can transition to FAILED on error
+
+## Example Usage
 
 <TypeScriptExample>
 
 ```ts title="src/index.ts"
-import { Agent, type AgentNamespace } from "agents";
+import { Agent, type AgentNamespace, MCPConnectionState } from "agents";
 
 type Env = {
 	MyAgent: AgentNamespace<MyAgent>;
@@ -31,15 +54,17 @@ export class MyAgent extends Agent<Env, never> {
 					"https://weather-mcp.example.com/mcp",
 				);
 
-				if (result.state === "authenticating") {
+				if (result.state === MCPConnectionState.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(`Connection failed: ${error.message}`, {
+					status: 500,
+				});
 			}
 		}
 	}
@@ -50,27 +75,6 @@ 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()`
@@ -91,8 +95,8 @@ async addMcpServer(
     };
   }
 ): Promise<
-  | { id: string; state: "authenticating"; authUrl: string }
-  | { id: string; state: "ready"; authUrl?: undefined }
+  | { id: string; state: typeof MCPConnectionState.AUTHENTICATING; authUrl: string }
+  | { id: string; state: typeof MCPConnectionState.READY; authUrl?: undefined }
 >
 ```
 
@@ -112,25 +116,30 @@ async addMcpServer(
 
 A Promise that resolves to a discriminated union based on the connection state:
 
-**When authentication is required:**
+**When OAuth authentication is required:**
 - **`id`** (string) — Unique identifier for this server connection
-- **`state`** (`"authenticating"`) — Indicates OAuth authentication is needed
-- **`authUrl`** (string) — OAuth authorization URL for user authentication
+- **`state`** — `MCPConnectionState.AUTHENTICATING`
+- **`authUrl`** (string) — OAuth authorization URL where the user must authenticate
 
-**When connection is ready:**
+**When connection is successful:**
 - **`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
+- **`state`** — `MCPConnectionState.READY`
+- **`authUrl`** — `undefined`
 
 #### Throws
 
-Throws an error if the connection or discovery process fails. Always wrap `addMcpServer()` calls in try-catch blocks to handle connection failures gracefully.
+- Throws an error if connection fails
+- Throws an error if capability discovery fails
+
+The server stays in storage after errors, allowing retry via `connectToServer(id)`
 
 #### Example
 
 <TypeScriptExample>
 
 ```ts title="src/index.ts"
+import { MCPConnectionState } from "agents";
+
 export class MyAgent extends Agent<Env, never> {
 	async onRequest(request: Request): Promise<Response> {
 		try {
@@ -139,28 +148,42 @@ export class MyAgent extends Agent<Env, never> {
 				"https://weather-mcp.example.com/mcp",
 			);
 
-			if (result.state === "authenticating") {
+			if (result.state === MCPConnectionState.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(
+					JSON.stringify({ serverId: result.id, authUrl: result.authUrl }),
+					{
+						headers: { "Content-Type": "application/json" },
+					},
+				);
 			}
 
-			return new Response(`Connected: ${result.id}`, { status: 200 });
+			return new Response("Connected and ready", { status: 200 });
 		} catch (error) {
-			return new Response(`Connection failed: ${error}`, { status: 500 });
+			return new Response(`Failed to connect: ${error.message}`, {
+				status: 500,
+			});
 		}
 	}
 }
 ```
 
 </TypeScriptExample>
 
-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.
+If the MCP server requires OAuth authentication, the result will include `authUrl` for user authentication. When connection and discovery succeed, the server is immediately in the `READY` state with all capabilities loaded.
 
-:::note[Breaking Change: Error Handling Required]
+:::caution[Breaking Change]
 
-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.
+As of this version, `addMcpServer()` now throws errors on connection or discovery failures instead of silently continuing. The method also returns a discriminated union with a `state` field instead of a simple object with `authUrl`. Wrap calls in try-catch blocks to handle errors:
+
+```ts
+try {
+  const result = await this.addMcpServer(name, url);
+  // Check result.state instead of result.authUrl
+} catch (error) {
+  // Handle connection/discovery failures
+}
+```
 
 :::
 
@@ -278,7 +301,15 @@ export class MyAgent extends Agent<Env, never> {
 
 </TypeScriptExample>
 
-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.
+The `state` field follows the `MCPConnectionState` enum values:
+- `authenticating` — Waiting for OAuth authorization
+- `connecting` — Establishing transport connection
+- `connected` — Transport connected, capabilities not yet discovered
+- `discovering` — Discovering server capabilities (tools, resources, prompts)
+- `ready` — Fully connected with all capabilities loaded
+- `failed` — Connection failed
+
+Use this method to monitor connection status, list available tools, or build UI for connected servers.
 
 ## OAuth Configuration