Connect to an MCP server

Connect to an MCP server

Last updated Jun 3, 2026 Your Agent can connect to external Model Context Protocol (MCP) ↗︎ 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: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

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 }) ); }, }; ```

src/index.tsts

```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

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 });
}

} ```

src/index.tsts

```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

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:

```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 });
}

} ```

src/index.tsts

```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 });
}

} ```

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, so they remain active across requests.

Next steps

Handle OAuth flows

Configure OAuth callbacks and error handling.

MCP Client API

Complete API documentation for MCP clients.

Was this helpful?

YesNo

{"@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","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/agents/model-context-protocol/guides/connect-mcp-client/og.png?v=f54fa99677cda3d9","dateModified":"2026-06-03","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"]}

description: Migrate Agents SDK MCP servers and clients to the split MCP TypeScript SDK v2 packages while retaining legacy compatibility. title: Migrate to MCP SDK v2 image: https://developers.cloudflare.com/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2/og.png?v=6d00c9de2a63b5f1

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

Connect to an MCP server

What you will build

Prerequisites

1. Create a basic Agent

2. Add MCP connection endpoint

3. Test the connection

4. List available tools

Summary

Next steps

Handle OAuth flows

MCP Client API

On this page