Add MCP client documentation

The Agent class provides public APIs for connecting to MCP servers
but these were completely undocumented. This adds API reference
documentation, a tutorial for first connection, and a guide for
handling OAuth flows with MCP servers.

Author: ghostwriternr

src/content/docs/agents/api-reference/agents-api.mdx

@@ -580,6 +580,40 @@ Visit the [state management API documentation](/agents/api-reference/store-and-s
 
 :::
 
+### MCP Client API
+
+The Agents SDK allows your Agent to act as an MCP (Model Context Protocol) client, connecting to remote MCP servers and using their tools, resources, and prompts.
+
+<TypeScriptExample>
+
+```ts
+class Agent<Env, State = unknown> {
+  // Connect to an MCP server
+  async addMcpServer(
+    serverName: string,
+    url: string,
+    callbackHost?: string,
+    agentsPrefix?: string,
+    options?: MCPClientOptions
+  ): Promise<{ id: string; authUrl: string | undefined }>;
+
+  // Disconnect from an MCP server
+  async removeMcpServer(id: string): Promise<void>;
+
+  // Get state of all connected MCP servers
+  getMcpServers(): MCPServersState;
+}
+```
+
+</TypeScriptExample>
+
+When your Agent connects to MCP servers, it can dynamically discover and use tools provided by those servers, enabling powerful integrations with external services.
+
+:::note
+
+For complete MCP client API documentation, including OAuth configuration and advanced usage, refer to the [Agent — MCP Client API](/agents/model-context-protocol/mcp-client-api/).
+
+:::
 
 ### Client API
 

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

@@ -0,0 +1,212 @@
+---
+title: Connect to an MCP server
+pcx_content_type: tutorial
+tags:
+  - MCP
+sidebar:
+  order: 5
+---
+
+import { Render, TypeScriptExample, PackageManagers } from "~/components";
+
+Your Agent can connect to external [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers to access their tools and extend your Agent's capabilities. In this tutorial, you'll create an Agent that connects to an MCP server and uses one of its tools.
+
+## What you will build
+
+An Agent with endpoints to:
+- Connect to an MCP server
+- List available tools from connected servers
+- Get the connection status
+
+## Prerequisites
+
+An MCP server to connect to (or use the public example in this tutorial).
+
+## 1. Create a basic Agent
+
+Create a new Agent project using the hello-world template:
+
+<PackageManagers
+	type="create"
+	pkg="cloudflare@latest"
+	args={"my-mcp-client --template=cloudflare/ai/demos/hello-world"}
+/>
+
+Move into the project directory:
+
+```sh
+cd my-mcp-client
+```
+
+Your Agent is ready! The template includes a minimal Agent in `src/index.ts`:
+
+<TypeScriptExample>
+
+```ts title="src/index.ts"
+import { Agent, type AgentNamespace, routeAgentRequest } from "agents";
+
+type Env = {
+	HelloAgent: AgentNamespace<HelloAgent>;
+};
+
+export class HelloAgent extends Agent<Env, never> {
+	async onRequest(request: Request): Promise<Response> {
+		return new Response("Hello, Agent!", { status: 200 });
+	}
+}
+
+export default {
+	async fetch(request: Request, env: Env) {
+		return (
+			(await routeAgentRequest(request, env, { cors: true })) ||
+			new Response("Not found", { status: 404 })
+		);
+	},
+} satisfies ExportedHandler<Env>;
+```
+
+</TypeScriptExample>
+
+## 2. Add MCP connection endpoint
+
+Add an endpoint to connect to MCP servers. Update your Agent class in `src/index.ts`:
+
+<TypeScriptExample>
+
+```ts title="src/index.ts"
+export class HelloAgent extends Agent<Env, never> {
+	async onRequest(request: Request): Promise<Response> {
+		const url = new URL(request.url);
+
+		// Connect to an MCP server
+		if (url.pathname.endsWith("add-mcp") && request.method === "POST") {
+			const { serverUrl, name } = (await request.json()) as {
+				serverUrl: string;
+				name: string;
+			};
+
+			const { id, authUrl } = await this.addMcpServer(name, serverUrl);
+
+			if (authUrl) {
+				// OAuth required - return auth URL
+				return new Response(
+					JSON.stringify({ serverId: id, authUrl }),
+					{ headers: { "Content-Type": "application/json" } },
+				);
+			}
+
+			return new Response(
+				JSON.stringify({ serverId: id, status: "connected" }),
+				{ headers: { "Content-Type": "application/json" } },
+			);
+		}
+
+		return new Response("Not found", { status: 404 });
+	}
+}
+```
+
+</TypeScriptExample>
+
+The `addMcpServer()` method connects to an MCP server. If the server requires OAuth authentication, it returns an `authUrl` that users must visit to complete authorization.
+
+## 3. Test the connection
+
+Start your development server:
+
+```sh
+npm start
+```
+
+In a new terminal, connect to an MCP server (using a public example):
+
+```sh
+curl -X POST http://localhost:8788/agents/hello-agent/default/add-mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "serverUrl": "https://docs.mcp.cloudflare.com/mcp",
+    "name": "Example Server"
+  }'
+```
+
+You should see a response with the server ID:
+
+```json
+{
+	"serverId": "example-server-id",
+	"status": "connected"
+}
+```
+
+## 4. List available tools
+
+Add an endpoint to see which tools are available from connected servers:
+
+<TypeScriptExample>
+
+```ts title="src/index.ts"
+export class HelloAgent extends Agent<Env, never> {
+	async onRequest(request: Request): Promise<Response> {
+		const url = new URL(request.url);
+
+		// ... previous add-mcp endpoint ...
+
+		// List MCP state (servers, tools, etc)
+		if (url.pathname.endsWith("mcp-state") && request.method === "GET") {
+			const mcpState = this.getMcpServers();
+
+			return new Response(JSON.stringify(mcpState, null, 2), {
+				headers: { "Content-Type": "application/json" },
+			});
+		}
+
+		return new Response("Not found", { status: 404 });
+	}
+}
+```
+
+</TypeScriptExample>
+
+Test it:
+
+```sh
+curl http://localhost:8788/agents/hello-agent/default/mcp-state
+```
+
+You'll see all connected servers, their connection states, and available tools:
+
+```json
+{
+	"servers": {
+		"example-server-id": {
+			"name": "Example Server",
+			"state": "ready",
+			"server_url": "https://docs.mcp.cloudflare.com/mcp",
+			...
+		}
+	},
+	"tools": [
+		{
+			"name": "add",
+			"description": "Add two numbers",
+			"serverId": "example-server-id",
+			...
+		}
+	]
+}
+```
+
+## What you built
+
+You created an Agent that can:
+- Connect to external MCP servers dynamically
+- Handle OAuth authentication flows when required
+- List all available tools from connected servers
+- Monitor connection status
+
+Connections persist in the Agent's [SQL storage](/agents/api-reference/store-and-sync-state/), so they remain active across requests.
+
+## Next steps
+
+- [Handle OAuth flows](/agents/guides/oauth-mcp-client) — Configure OAuth callbacks and error handling
+- [McpClient — API reference](/agents/model-context-protocol/mcp-client-api/) — Complete API documentation