docs: Add MCPConnectionState enum and update MCP documentation

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

Author: github-actions[bot]

src/content/changelog/agents/2025-11-21-mcp-connection-state-enum.mdx

@@ -0,0 +1,68 @@
+---
+title: MCPConnectionState enum for improved type safety
+description: MCP connection states are now defined using an enum for better type safety and reliability, with improved error handling and fail-fast behavior
+products:
+  - agents
+  - workers
+date: 2025-11-21
+---
+
+The Agents SDK now exports an `MCPConnectionState` enum that provides better type safety and consistency when working with MCP server connection states.
+
+### MCPConnectionState enum
+
+Connection states are now available as enum constants instead of string literals:
+
+```ts
+import { MCPConnectionState } from "agents";
+
+// Check connection states using enum constants
+if (server.state === MCPConnectionState.READY) {
+	console.log("Server is ready to use");
+}
+```
+
+Available states:
+
+- `MCPConnectionState.AUTHENTICATING` - Waiting for OAuth authorization to complete
+- `MCPConnectionState.CONNECTING` - Establishing transport connection to MCP server
+- `MCPConnectionState.DISCOVERING` - Discovering server capabilities (tools, resources, prompts)
+- `MCPConnectionState.READY` - Fully connected and ready to use
+- `MCPConnectionState.FAILED` - Connection failed at some point
+
+### Migration from string literals
+
+If you were using string literals to check connection states, update your code:
+
+```ts title="Before"
+if (server.state === "ready") {
+	// Do something
+}
+```
+
+```ts title="After"
+import { MCPConnectionState } from "agents";
+
+if (server.state === MCPConnectionState.READY) {
+	// Do something
+}
+```
+
+### Improved error handling
+
+MCP client connections now use fail-fast behavior with `Promise.all` instead of `Promise.allSettled`, providing quicker feedback when server capability discovery fails. The SDK also now only attempts to register capabilities that the server advertises, improving reliability and reducing unnecessary errors.
+
+### Updated connection flow
+
+The connection state machine has been refined:
+
+- **Non-OAuth servers**: `CONNECTING` → `DISCOVERING` → `READY`
+- **OAuth servers**: `AUTHENTICATING` → (callback) → `CONNECTING` → `DISCOVERING` → `READY`
+- **Errors**: Any state can transition to `FAILED` on error
+
+### Additional improvements
+
+- MCP server state broadcasts now occur before and after OAuth connection establishment, providing better real-time updates to connected clients
+- Connection state is set to `FAILED` before throwing errors during capability discovery, ensuring proper state management
+
+For more information, refer to the [McpClient API reference](/agents/model-context-protocol/mcp-client-api/).

src/content/docs/agents/guides/oauth-mcp-client.mdx

@@ -140,7 +140,7 @@ Use the `useAgent` hook for automatic state updates:
 
 ```tsx title="src/App.tsx"
 import { useAgent } from "agents/react";
-import type { MCPServersState } from "agents";
+import { MCPConnectionState, type MCPServersState } from "agents";
 
 function App() {
 	const [mcpState, setMcpState] = useState<MCPServersState>({
@@ -164,7 +164,7 @@ function App() {
 			{Object.entries(mcpState.servers).map(([id, server]) => (
 				<div key={id}>
 					<strong>{server.name}</strong>: {server.state}
-					{server.state === "authenticating" && server.auth_url && (
+					{server.state === MCPConnectionState.AUTHENTICATING && server.auth_url && (
 						<button onClick={() => window.open(server.auth_url, "_blank")}>
 							Authorize
 						</button>
@@ -187,6 +187,8 @@ If you're not using React, poll the connection status:
 <TypeScriptExample>
 
 ```ts title="src/index.ts"
+import { MCPConnectionState } from "agents";
+
 export class MyAgent extends Agent<Env, never> {
 	async onRequest(request: Request): Promise<Response> {
 		const url = new URL(request.url);
@@ -201,9 +203,9 @@ export class MyAgent extends Agent<Env, never> {
 				([id, server]) => ({
 					serverId: id,
 					name: server.name,
-					state: server.state, // "authenticating" | "connecting" | "ready" | "failed"
-					isReady: server.state === "ready",
-					needsAuth: server.state === "authenticating",
+					state: server.state,
+					isReady: server.state === MCPConnectionState.READY,
+					needsAuth: server.state === MCPConnectionState.AUTHENTICATING,
 					authUrl: server.auth_url,
 				}),
 			);
@@ -220,17 +222,17 @@ export class MyAgent extends Agent<Env, never> {
 
 </TypeScriptExample>
 
-Connection states: `authenticating` (needs OAuth) > `connecting` (completing setup) > `ready` (available for use)
+Connection states follow this progression: `AUTHENTICATING` (needs OAuth) → `CONNECTING` (completing setup) → `DISCOVERING` (fetching capabilities) → `READY` (available for use)
 
 ## Handle authentication failures
 
-When OAuth fails, the connection `state` becomes `"failed"`. Detect this in your UI and allow users to retry or clean up:
+When OAuth fails, the connection `state` becomes `MCPConnectionState.FAILED`. Detect this in your UI and allow users to retry or clean up:
 
 <TypeScriptExample>
 
 ```tsx title="src/App.tsx"
 import { useAgent } from "agents/react";
-import type { MCPServersState } from "agents";
+import { MCPConnectionState, type MCPServersState } from "agents";
 
 function App() {
 	const [mcpState, setMcpState] = useState<MCPServersState>({
@@ -270,7 +272,7 @@ function App() {
 				<div key={id}>
 					<strong>{server.name}</strong>: {server.state}
 
-					{server.state === "failed" && (
+					{server.state === MCPConnectionState.FAILED && (
 						<div>
 							<p>Connection failed. Please try again.</p>
 							<button onClick={() => handleRetry(id, server.server_url, server.name)}>

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

@@ -9,7 +9,55 @@ 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.
+
+## MCPConnectionState Enum
+
+The `MCPConnectionState` enum defines the possible states of an MCP server connection:
+
+```ts
+import { MCPConnectionState } from "agents";
+
+MCPConnectionState.AUTHENTICATING // "authenticating" - Waiting for OAuth authorization
+MCPConnectionState.CONNECTING     // "connecting" - Establishing transport connection
+MCPConnectionState.DISCOVERING    // "discovering" - Discovering server capabilities
+MCPConnectionState.READY          // "ready" - Fully connected and ready to use
+MCPConnectionState.FAILED         // "failed" - Connection failed
+```
+
+The connection state machine follows these transitions:
+
+- **Non-OAuth flow**: `CONNECTING` → `DISCOVERING` → `READY`
+- **OAuth flow**: `AUTHENTICATING` → (callback) → `CONNECTING` → `DISCOVERING` → `READY`
+- **Error**: Any state can transition to `FAILED` on error
+
+Use these constants instead of string literals when checking connection states.
+
+### Migration from String Literals
+
+If you were previously using string literals to check connection states, update your code to use the enum:
+
+<TypeScriptExample>
+
+```ts title="Before"
+// Old approach with string literals
+if (server.state === "ready") {
+	console.log("Server is ready");
+}
+```
+
+```ts title="After"
+// New approach with MCPConnectionState enum
+import { MCPConnectionState } from "agents";
+
+if (server.state === MCPConnectionState.READY) {
+	console.log("Server is ready");
+}
+```
+
+</TypeScriptExample>
+
+## Agent MCP Client Methods Example
 
 <TypeScriptExample>
 
@@ -183,19 +231,16 @@ None.
 An `MCPServersState` object containing:
 
 ```ts
+import { 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;
 		}
@@ -228,7 +273,31 @@ 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.
+Use this method to monitor connection status, list available tools, or build UI for connected servers. Check the connection state using the `MCPConnectionState` enum:
+
+<TypeScriptExample>
+
+```ts title="src/index.ts"
+import { MCPConnectionState } from "agents";
+
+export class MyAgent extends Agent<Env, never> {
+	async onRequest(request: Request): Promise<Response> {
+		const mcpState = this.getMcpServers();
+
+		for (const [id, server] of Object.entries(mcpState.servers)) {
+			if (server.state === MCPConnectionState.READY) {
+				console.log(`Server ${id} is ready`);
+			} else if (server.state === MCPConnectionState.AUTHENTICATING) {
+				console.log(`Server ${id} needs authentication`);
+			}
+		}
+
+		return new Response("OK");
+	}
+}
+```
+
+</TypeScriptExample>
 
 ## OAuth Configuration