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

Паттерны MCP-серверов Code Mode

MCP-сервер Code Mode позволяет любому клиенту Model Context Protocol (MCP) использовать написанный моделью код без необходимости предоставлять собственную sandbox. MCP-сервер предоставляет выполнение кода в качестве интерфейса инструмента и запускает сгенерированный JavaScript в изолированном Worker.

MCP-серверы Code Mode следуют двум паттернам:

Оба паттерна позволяют сгенерированному коду комбинировать операции и держать промежуточные результаты вне контекста модели. Различаются они тем, как модель узнаёт о доступных операциях.

Паттерн single-tool оборачивает существующий MCP-сервер с помощью codeMcpServer(). Вместо того чтобы объявлять каждый upstream-инструмент отдельно, сервер объявляет один code инструмент.

code описание инструмента содержит сгенерированные определения TypeScript для каждого вышестоящего инструмента. Модель пишет JavaScript на основе codemode пространство имён:

async () => {
	const projects = await codemode.list_projects({ status: "active" });
	const tasks = [];

	for (const project of projects) {
		tasks.push(...(await codemode.list_tasks({ projectId: project.id })));
	}

	return tasks.filter((task) => task.status === "blocked");
};

MCP-клиент выполняет только один внешний вызов инструмента. Внутри песочницы код может делать собственные зависимые вызовы вышестоящих систем, отфильтровывать промежуточные данные и возвращать только итоговый результат.

Этот паттерн хорошо работает, когда сгенерированные объявления типов свободно помещаются в code описания инструмента. Модель получает эти декларации при загрузке инструмента MCP.

Чтобы реализовать этот паттерн, см. Создайте MCP-сервер Code Mode с одним инструментом.

Крупный API может содержать тысячи операций. Включение каждой операции в одно описание инструмента всё равно занимало бы значительную часть контекста. Паттерн search-and-execute отделяет обнаружение возможностей от аутентифицированных вызовов API.

Сервер предоставляет два инструмента MCP:

• search выполняет сгенерированный код на основе документа OpenAPI. Возвращает только те operations, parameters или schemas, которые нужны для задачи.
• execute выполняет сгенерированный код с аутентифицированной функцией запроса. Может вызывать выбранные operations, формировать ответы и возвращать целевой результат.

Сначала модель вызывает search с помощью такого кода:

async () => {
	const spec = await codemode.spec();
	return Object.entries(spec.paths)
		.filter(([path]) => path.includes("/rulesets"))
		.map(([path, operations]) => ({
			path,
			methods: Object.keys(operations),
		}));
};

Полный документ OpenAPI остаётся внутри песочницы. В контекст модели попадает только возвращённое подмножество.

После выбора операции модель вызывает execute:

async () => {
	const response = await codemode.request({
		method: "GET",
		path: `/zones/${zoneId}/rulesets`,
	});

	return response.result.map(({ id, name, phase }) => ({ id, name, phase }));
};

Аутентификация остаётся в колбэке host-запроса. Сгенерированный код получает функцию запроса, а не сами учётные данные.

Cloudflare API MCP server использует этот паттерн, чтобы предоставить доступ к API Cloudflare через search и execute. Для обоснования дизайна и экономии контекста см. Code Mode: дайте агентам целый API за 1,000 токенов ↗.

Чтобы реализовать этот паттерн, см. Создайте MCP-сервер типа найди и выполни.

Код, написанный моделью, выполняется в изолированном Worker. Прямой исходящий сетевой доступ по умолчанию заблокирован. Сгенерированный код обращается к внешним системам только через вышестоящие MCP-инструменты или колбэк запроса, предоставленный хостом.

Выполнение кода не заменяет авторизацию. Применяйте разрешения и любые необходимые подтверждения внутри обработчиков вышестоящих инструментов или колбэка запроса хоста, прежде чем применять побочные эффекты. Не раскрывайте учётные данные через результаты инструментов или документы OpenAPI.

Используйте codeMcpServer() когда существующий MCP-сервер уже определяет операции и схемы, нужные модели. Используйте openApiMcpServer() когда большому каталогу OpenAPI требуется постепенное обнаружение и фиксированный объём контекста модели.