PCX edit

Oxyjun · Oxyjun · commit ffbc9f591324 · 2025-11-04T18:05:09.000Z
diff --git a/src/content/docs/agents/guides/connect-mcp-client.mdx b/src/content/docs/agents/guides/connect-mcp-client.mdx
@@ -7,7 +7,7 @@ sidebar:
   order: 5
 ---
 
-import { Render, TypeScriptExample, PackageManagers } from "~/components";
+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.
 
@@ -24,179 +24,190 @@ 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:
+<Steps>
 
-<PackageManagers
-	type="create"
-	pkg="cloudflare@latest"
-	args={"my-mcp-client --template=cloudflare/ai/demos/hello-world"}
-/>
+1. Create a new Agent project using the `hello-world` template:
 
-Move into the project directory:
+	<PackageManagers
+		type="create"
+		pkg="cloudflare@latest"
+		args={"my-mcp-client --template=cloudflare/ai/demos/hello-world"}
+	/>
 
-```sh
-cd my-mcp-client
-```
+2. Move into the project directory:
 
-Your Agent is ready! The template includes a minimal Agent in `src/index.ts`:
+	```sh
+	cd my-mcp-client
+	```
 
-<TypeScriptExample>
+	Your Agent is ready! The template includes a minimal Agent in `src/index.ts`:
 
-```ts title="src/index.ts"
-import { Agent, type AgentNamespace, routeAgentRequest } from "agents";
+	<TypeScriptExample>
 
-type Env = {
-	HelloAgent: AgentNamespace<HelloAgent>;
-};
+	```ts title="src/index.ts"
+	import { Agent, type AgentNamespace, routeAgentRequest } from "agents";
 
-export class HelloAgent extends Agent<Env, never> {
-	async onRequest(request: Request): Promise<Response> {
-		return new Response("Hello, Agent!", { status: 200 });
-	}
-}
+	type Env = {
+		HelloAgent: AgentNamespace<HelloAgent>;
+	};
 
-export default {
-	async fetch(request: Request, env: Env) {
-		return (
-			(await routeAgentRequest(request, env, { cors: true })) ||
-			new Response("Not found", { status: 404 })
-		);
-	},
-} satisfies ExportedHandler<Env>;
-```
+	export class HelloAgent extends Agent<Env, never> {
+		async onRequest(request: Request): Promise<Response> {
+			return new Response("Hello, Agent!", { status: 200 });
+		}
+	}
 
-</TypeScriptExample>
+	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
 
-Add an endpoint to connect to MCP servers. Update your Agent class in `src/index.ts`:
+<Steps>
+
+1. Add an endpoint to connect to MCP servers. Update your Agent class in `src/index.ts`:
+
+	<TypeScriptExample>
 
-<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);
 
-```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;
+				};
 
-		// 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);
 
-			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" } },
+					);
+				}
 
-			if (authUrl) {
-				// OAuth required - return auth URL
 				return new Response(
-					JSON.stringify({ serverId: id, authUrl }),
+					JSON.stringify({ serverId: id, status: "connected" }),
 					{ 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 });
 		}
-
-		return new Response("Not found", { status: 404 });
 	}
-}
-```
+	```
 
-</TypeScriptExample>
+	</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
 
-Start your development server:
+<Steps>
+
+1. Start your development server:
 
-```sh
-npm start
-```
+	```sh
+	npm start
+	```
 
-In a new terminal, connect to an MCP server (using a public example):
+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"
-  }'
-```
+	```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:
+	You should see a response with the server ID:
+
+	```json
+	{
+		"serverId": "example-server-id",
+		"status": "connected"
+	}
+	```
 
-```json
-{
-	"serverId": "example-server-id",
-	"status": "connected"
-}
-```
+</Steps>
 
 ## 4. List available tools
 
-Add an endpoint to see which tools are available from connected servers:
+<Steps>
 
-<TypeScriptExample>
+1. Add an endpoint to see which tools are available from connected servers:
 
-```ts title="src/index.ts"
-export class HelloAgent extends Agent<Env, never> {
-	async onRequest(request: Request): Promise<Response> {
-		const url = new URL(request.url);
+	<TypeScriptExample>
 
-		// ... previous add-mcp endpoint ...
+	```ts title="src/index.ts"
+	export class HelloAgent extends Agent<Env, never> {
+		async onRequest(request: Request): Promise<Response> {
+			const url = new URL(request.url);
 
-		// List MCP state (servers, tools, etc)
-		if (url.pathname.endsWith("mcp-state") && request.method === "GET") {
-			const mcpState = this.getMcpServers();
+			// ... previous add-mcp endpoint ...
 
-			return new Response(JSON.stringify(mcpState, null, 2), {
-				headers: { "Content-Type": "application/json" },
-			});
-		}
+			// List MCP state (servers, tools, etc)
+			if (url.pathname.endsWith("mcp-state") && request.method === "GET") {
+				const mcpState = this.getMcpServers();
 
-		return new Response("Not found", { status: 404 });
-	}
-}
-```
+				return new Response(JSON.stringify(mcpState, null, 2), {
+					headers: { "Content-Type": "application/json" },
+				});
+			}
 
-</TypeScriptExample>
+			return new Response("Not found", { status: 404 });
+		}
+	}
+	```
+	</TypeScriptExample>
 
-Test it:
+2. Test it:
 
-```sh
-curl http://localhost:8788/agents/hello-agent/default/mcp-state
-```
+	```sh
+	curl http://localhost:8788/agents/hello-agent/default/mcp-state
+	```
 
-You'll see all connected servers, their connection states, and available tools:
+	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",
-			...
-		}
-	]
-}
-```
+	```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>
 
-## What you built
+## Summary
 
 You created an Agent that can:
 - Connect to external MCP servers dynamically
diff --git a/src/content/docs/agents/guides/oauth-mcp-client.mdx b/src/content/docs/agents/guides/oauth-mcp-client.mdx
@@ -61,7 +61,10 @@ export class ObservabilityAgent extends Agent<Env, never> {
 
 Your user is automatically redirected to the provider's OAuth page to authorize access.
 
-**Alternative approaches**: Instead of automatic redirect, you can present the `authUrl` to your user as:
+### Alternative approaches
+
+Instead of an automatic redirect, you can also present the `authUrl` to your user as a:
+
 - **Popup window**: `window.open(authUrl, '_blank', 'width=600,height=700')` (for dashboard-style apps)
 - **Clickable link**: Display as a button or link (for API documentation or multi-step flows)
 - **Deep link**: Use custom URL schemes for mobile apps
@@ -217,7 +220,7 @@ export class MyAgent extends Agent<Env, never> {
 
 </TypeScriptExample>
 
-Connection states: `authenticating` (needs OAuth) → `connecting` (completing setup) → `ready` (available for use)
+Connection states: `authenticating` (needs OAuth) > `connecting` (completing setup) > `ready` (available for use)
 
 ## Handle authentication failures
 
diff --git a/src/content/docs/agents/model-context-protocol/mcp-client-api.mdx b/src/content/docs/agents/model-context-protocol/mcp-client-api.mdx
@@ -48,7 +48,7 @@ Connections persist in the Agent's [SQL storage](/agents/api-reference/store-and
 
 ## Agent MCP Client Methods
 
-### addMcpServer()
+### `addMcpServer()`
 
 Add a connection to an MCP server and make its tools available to your Agent.
 
@@ -121,7 +121,7 @@ If the MCP server requires OAuth authentication, `authUrl` will be returned for
 - [Transport options](/agents/model-context-protocol/transport)
 - [removeMcpServer()](#removemcpserver)
 
-### removeMcpServer()
+### `removeMcpServer()`
 
 Disconnect from an MCP server and clean up its resources.
 
@@ -160,7 +160,7 @@ export class MyAgent extends Agent<Env, never> {
 
 Disconnects from the MCP server, removes all related resources, and deletes the server record from storage.
 
-### getMcpServers()
+### `getMcpServers()`
 
 Get the current state of all MCP server connections.
 
