docs: update MCP client API for enum-based connection states

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

Author: github-actions[bot]

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

@@ -9,41 +9,48 @@ 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
+
+The Agents SDK exports an `MCPConnectionState` enum for type-safe connection state checking:
 
 <TypeScriptExample>
 
 ```ts title="src/index.ts"
-import { Agent, type AgentNamespace } from "agents";
-
-type Env = {
-	MyAgent: AgentNamespace<MyAgent>;
-};
+import { Agent, MCPConnectionState } from "agents";
 
 export class MyAgent extends Agent<Env, never> {
 	async onRequest(request: Request): Promise<Response> {
-		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",
-			);
+		const mcpState = this.getMcpServers();
 
-			if (authUrl) {
-				return new Response(JSON.stringify({ authUrl }), {
-					headers: { "Content-Type": "application/json" },
-				});
+		for (const [serverId, server] of Object.entries(mcpState.servers)) {
+			if (server.state === MCPConnectionState.READY) {
+				console.log(`Server ${serverId} is ready`);
+			} else if (server.state === MCPConnectionState.AUTHENTICATING) {
+				console.log(`Server ${serverId} needs authentication`);
 			}
-
-			return new Response(`Connected: ${id}`, { status: 200 });
 		}
+
+		return new Response("OK");
 	}
 }
 ```
 
 </TypeScriptExample>
 
+The `MCPConnectionState` enum includes these values:
+
+- **`MCPConnectionState.AUTHENTICATING`** (`"authenticating"`) — Waiting for OAuth authorization to complete
+- **`MCPConnectionState.CONNECTING`** (`"connecting"`) — Establishing transport connection to MCP server
+- **`MCPConnectionState.DISCOVERING`** (`"discovering"`) — Discovering server capabilities (tools, resources, prompts)
+- **`MCPConnectionState.READY`** (`"ready"`) — Fully connected and ready to use
+- **`MCPConnectionState.FAILED`** (`"failed"`) — Connection failed at some point
+
+### Connection Behavior
+
+When establishing connections, the MCP client follows a fail-fast approach during capability discovery. If any capability (tools, resources, or prompts) fails to load from the server, the entire connection will transition to the `FAILED` state immediately. This ensures that connections are only marked as `READY` when all advertised capabilities are successfully available.
+
 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.
 
 ## Agent MCP Client Methods
@@ -183,19 +190,16 @@ None.
 An `MCPServersState` object containing:
 
 ```ts
+import type { MCPConnectionState } from "agents";
+
 {
 	servers: Record<
 		string,
 		{
 			name: string;
 			server_url: string;
 			auth_url: string | null;
-			state:
-				| "authenticating"
-				| "connecting"
-				| "ready"
-				| "discovering"
-				| "failed";
+			state: MCPConnectionState;
 			capabilities: ServerCapabilities | null;
 			instructions: string | null;
 		}
@@ -211,24 +215,42 @@ An `MCPServersState` object containing:
 <TypeScriptExample>
 
 ```ts title="src/index.ts"
+import { Agent, MCPConnectionState } from "agents";
+
 export class MyAgent extends Agent<Env, never> {
 	async onRequest(request: Request): Promise<Response> {
 		const url = new URL(request.url);
 
 		if (url.pathname === "/mcp-state") {
 			const mcpState = this.getMcpServers();
 
-			return new Response(JSON.stringify(mcpState, null, 2), {
-				headers: { "Content-Type": "application/json" },
-			});
+			// Check connection states using the enum
+			const readyServers = Object.entries(mcpState.servers).filter(
+				([_, server]) => server.state === MCPConnectionState.READY,
+			);
+
+			return new Response(
+				JSON.stringify(
+					{
+						total: Object.keys(mcpState.servers).length,
+						ready: readyServers.length,
+						servers: mcpState,
+					},
+					null,
+					2,
+				),
+				{
+					headers: { "Content-Type": "application/json" },
+				},
+			);
 		}
 	}
 }
 ```
 
 </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 is of type `MCPConnectionState` and can be compared using the enum constants (for example, `MCPConnectionState.READY`, `MCPConnectionState.AUTHENTICATING`). Use this method to monitor connection status, list available tools, or build UI for connected servers.
 
 ## OAuth Configuration