docs: add MCP connection state standardization and improvements

Synced from cloudflare/agents PR #672

- Document new MCPConnectionState enum with type-safe constants
- Add new 'connected' state to connection state machine
- Update state transition documentation
- Document improved discovery error handling
- Add changelog entry for breaking changes and new features

Related PR: cloudflare/agents#672

🤖 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-25-mcp-connection-state-improvements.mdx

@@ -0,0 +1,79 @@
+---
+title: MCP connection state standardization and discovery improvements
+description: The Agents SDK now includes a formalized MCPConnectionState enum, a new 'connected' state for better connection lifecycle tracking, improved error handling for discovery failures, and the new discoverIfConnected() method for explicit capability discovery.
+products:
+  - agents
+  - workers
+date: 2025-11-25
+---
+
+This release standardizes MCP client connection states and improves error handling during server capability discovery.
+
+## MCPConnectionState enum
+
+The new `MCPConnectionState` enum formalizes all possible connection states, replacing string literals with type-safe constants:
+
+```ts
+import { MCPConnectionState } from "agents/mcp";
+
+// Use enum constants instead of strings
+if (connection.state === MCPConnectionState.READY) {
+  // Connection is ready
+}
+```
+
+Available states:
+- `AUTHENTICATING` — Waiting for OAuth authorization
+- `CONNECTING` — Establishing transport connection
+- `CONNECTED` — Transport connected, capabilities not yet discovered
+- `DISCOVERING` — Fetching server capabilities
+- `READY` — Fully connected with tools available
+- `FAILED` — Connection failed
+
+## New 'connected' state
+
+A new `connected` state has been added to distinguish between:
+- Transport connection established (`connected`)
+- Capabilities discovered and tools available (`ready`)
+
+This provides better visibility into the connection lifecycle, especially for debugging connection issues or building UI that shows connection progress.
+
+**State transitions:**
+- Non-OAuth: `connecting` → `connected` → `discovering` → `ready`
+- OAuth: `authenticating` → (callback) → `connecting` → `connected` → `discovering` → `ready`
+
+## Improved error handling
+
+Discovery failures now throw errors immediately instead of silently continuing with empty tool arrays. This ensures connection problems are caught early and handled explicitly.
+
+```ts
+try {
+  await agent.addMcpServer("Server", "https://mcp.example.com/mcp");
+} catch (error) {
+  // Discovery errors are now thrown immediately
+  console.error("MCP connection failed:", error);
+}
+```
+
+## discoverIfConnected() method
+
+The new `discoverIfConnected()` method on `MCPClientManager` allows explicit capability discovery for servers in the `connected` or `ready` state. This is useful for:
+- Refreshing server capabilities
+- Manual discovery after connection establishment
+- Building refresh buttons in user interfaces
+
+```ts
+// Discover capabilities for a connected server
+await mcpClientManager.discoverIfConnected(serverId);
+```
+
+## Breaking change
+
+`ClientConnection.init()` no longer automatically performs discovery. Discovery should now be initiated explicitly using `discoverIfConnected()` from the `MCPClientManager`. This change improves control over the connection lifecycle and makes the discovery step more explicit.
+
+For most users using the `Agent` class methods like `addMcpServer()`, this change is handled automatically and requires no action.
+
+## Resources
+
+- [McpClient — API reference](/agents/model-context-protocol/mcp-client-api/)
+- [Connect to an MCP server](/agents/guides/connect-mcp-client/)

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

@@ -193,8 +193,9 @@ An `MCPServersState` object containing:
 			state:
 				| "authenticating"
 				| "connecting"
-				| "ready"
+				| "connected"
 				| "discovering"
+				| "ready"
 				| "failed";
 			capabilities: ServerCapabilities | null;
 			instructions: string | null;
@@ -228,7 +229,21 @@ 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 indicates the current connection status and follows a state machine:
+
+- **`authenticating`** — Waiting for OAuth authorization to complete
+- **`connecting`** — Establishing transport connection to the MCP server
+- **`connected`** — Transport connection established, but capabilities not yet discovered
+- **`discovering`** — Fetching server capabilities (tools, resources, prompts)
+- **`ready`** — Fully connected with capabilities available
+- **`failed`** — Connection failed at some point
+
+**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
+
+Use this method to monitor connection status, list available tools, or build UI for connected servers.
 
 ## OAuth Configuration
 
@@ -251,6 +266,28 @@ 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:
@@ -278,6 +315,12 @@ export class MyAgent extends Agent<Env, never> {
 
 </TypeScriptExample>
 
+:::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.
+
+:::
+
 ## Next Steps
 
 - [Connect your first MCP server](/agents/guides/connect-mcp-client) — Tutorial to get started