INTEGRITY Документация

← Создание агентов на Cloudflare / agents / model-context-protocol / guides

Подключение к MCP-серверу

Ваш агент может подключаться к внешним Model Context Protocol (MCP) ↗ серверов, чтобы получить доступ к их инструментам и расширить возможности вашего Agent. В этом руководстве вы создадите Agent, который подключается к MCP-серверу и использует один из его инструментов.

Что вы создадите

Agent с эндпойнтами для:

Предварительные требования

MCP-сервер, к которому нужно подключиться (или используйте публичный пример из этого руководства).

1. Создайте базовый Agent

  1. Создайте новый проект Agent с помощью hello-world шаблон:

    npm create cloudflare@latest -- my-mcp-client --template=cloudflare/ai/demos/hello-world

  2. Перейдите в каталог проекта:

    cd my-mcp-client

    Ваш агент готов! Шаблон включает минимального агента в src/index.ts:

    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.ts
    import { Agent, routeAgentRequest } from "agents";

type Env = {
	HelloAgent: DurableObjectNamespace<HelloAgent>;
};

export class HelloAgent extends Agent<Env> {
	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>;

2. Добавьте конечную точку подключения MCP

  1. Добавьте эндпойнт для подключения к MCP-серверам. Обновите ваш класс Agent в src/index.ts:

    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.ts
    export class HelloAgent extends Agent<Env> {
	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 });
	}
}

addMcpServer() метод подключается к MCP-серверу. Если сервер требует OAuth-аутентификации, он возвращает authUrl которую пользователи должны посетить, чтобы завершить авторизацию.

3. Проверьте подключение

  1. Запустите сервер разработки:

    npm start

  2. В новом терминале подключитесь к серверу MCP (используя публичный пример):

    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"
	}'

    Вы должны увидеть ответ с идентификатором сервера:

    {
	"serverId": "example-server-id",
	"status": "connected"
}

4. Выведите список доступных инструментов

  1. Добавьте эндпойнт, чтобы видеть, какие инструменты доступны от подключённых серверов:

    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.ts
    export class HelloAgent extends Agent<Env> {
	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 Response.json(mcpState);
		}

		return new Response("Not found", { status: 404 });
	}
}

  2. Проверьте это:

    curl http://localhost:8788/agents/hello-agent/default/mcp-state

    Вы увидите все подключённые серверы, их состояния подключения и доступные инструменты:

    {
	"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",
			...
		}
	]
}

Сводка

Вы создали Agent, который умеет:

Подключения Agent сохраняются в Хранилище SQL, чтобы они оставались активными между запросами.

Следующие шаги

Обрабатывайте потоки OAuth

Настройка обратных вызовов OAuth и обработки ошибок.

API MCP-клиента

Полная документация по API для MCP-клиентов.