Add basic MCP client documentation (#26276)

* 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.

* Use Cloudflare Observability MCP as example

* PCX edit

---------

Co-authored-by: Jun Lee <[email protected]>

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,223 @@
+---
+title: Connect to an MCP server
+pcx_content_type: tutorial
+tags:
+  - MCP
+sidebar:
+  order: 5
+---
+
+import { Render, TypeScriptExample, PackageManagers, Steps } 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
+
+<Steps>
+
+1. 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"}
+	/>
+
+2. 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>
+</Steps>
+
+## 2. Add MCP connection endpoint
+
+<Steps>
+
+1. 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>
+</Steps>
+
+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
+
+<Steps>
+
+1. Start your development server:
+
+	```sh
+	npm start
+	```
+
+2. 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"
+	}
+	```
+
+</Steps>
+
+## 4. List available tools
+
+<Steps>
+
+1. 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>
+
+2. 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",
+				...
+			}
+		]
+	}
+	```
+</Steps>
+
+## Summary
+
+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