--- description: Create a Cloudflare Agent that connects to an external MCP server and uses its tools. title: Connect to an MCP server image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt > Use this file to discover all available pages before exploring further. # Connect to an MCP server Last updated Aug 24, 2026|Copy as Markdown|[View as Markdown](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/agents/model-context-protocol/guides/connect-mcp-client/index.md)|[Agent setup](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/agent-setup/) 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 1. Create a new Agent project using the `hello-world` template: npmyarnpnpm ``` npm create cloudflare@latest -- my-mcp-client --template=cloudflare/ai/demos/hello-world ``` ``` yarn create cloudflare my-mcp-client --template=cloudflare/ai/demos/hello-world ``` ``` pnpm create cloudflare@latest 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`: ```js import { Agent, routeAgentRequest } from "agents"; export class HelloAgent extends Agent { async onRequest(request) { return new Response("Hello, Agent!", { status: 200 }); } } export default { async fetch(request, env) { return ( (await routeAgentRequest(request, env, { cors: true })) || new Response("Not found", { status: 404 }) ); }, }; ``` ```ts import { Agent, routeAgentRequest } from "agents"; type Env = { HelloAgent: DurableObjectNamespace; }; export class HelloAgent extends Agent { async onRequest(request: Request): Promise { 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; ``` ## 2\. Add MCP connection endpoint 1. Add an endpoint to connect to MCP servers. Update your Agent class in `src/index.ts`: ```js export class HelloAgent extends Agent { async onRequest(request) { 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(); 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 }); } } ``` ```ts export class HelloAgent extends Agent { async onRequest(request: Request): Promise { 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 }); } } ``` 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 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" } ``` ## 4\. List available tools 1. Add an endpoint to see which tools are available from connected servers: ```js export class HelloAgent extends Agent { async onRequest(request) { 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 Response.json(mcpState); } return new Response("Not found", { status: 404 }); } } ``` ```ts export class HelloAgent extends Agent { async onRequest(request: Request): Promise { 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 Response.json(mcpState); } return new Response("Not found", { status: 404 }); } } ``` 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", ... } ] } ``` ## 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](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/agents/runtime/lifecycle/state/), so they remain active across requests. ## Next steps ### [Handle OAuth flows](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/agents/model-context-protocol/guides/oauth-mcp-client/) Configure OAuth callbacks and error handling. ### [MCP Client API](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/agents/model-context-protocol/apis/client-api/) Complete API documentation for MCP clients. Was this helpful? YesNo ## On this page [![](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/agents/model-context-protocol/guides/connect-mcp-client/#page","headline":"Connect to an MCP server · Cloudflare Agents docs","description":"Create a Cloudflare Agent that connects to an external MCP server and uses its tools.","url":"https://developers.cloudflare.com/agents/model-context-protocol/guides/connect-mcp-client/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-24","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["MCP"]} ```