MCP-Agent: Python-фреймворк для создания AI-агентов на MCP

MCP-Agent — это Python-фреймворк от lastmile-ai для создания AI-агентов на базе Model Context Protocol (MCP). Он предоставляет 7 готовых паттернов рабочих процессов (от простого агента до роя), встроенную поддержку durable execution через Temporal, декларативную YAML-конфигурацию и встроенные примитивы для интеграции с любыми MCP-серверами. На июль 2026 года — 8 411 звёзд на GitHub, Apache 2.0 лицензия, активная разработка.

Что такое MCP-Agent и чем он отличается от других фреймворков

MCP-Agent — это фреймворк для построения AI-агентов, целиком завязанный на протокол MCP (Model Context Protocol). Если FastMCP — это инструмент для создания MCP-серверов (вы пишете сервер, который предоставляет инструменты, ресурсы и промпты), то MCP-Agent — это инструмент для потребления этих серверов: вы описываете, к каким MCP-серверам подключаться и какие workflow-паттерны использовать, а фреймворк сам управляет подключением, вызовом инструментов и жизненным циклом агента.

Главное отличие MCP-Agent от LangGraph или CrewAI — в том, что он не привязывает вас к конкретной LLM или поставщику. Вы можете переключаться между OpenAI, Anthropic и локальными моделями (через Ollama или vLLM) простой сменой конфига. Второе важное отличие — встроенная поддержка durable execution через Temporal: агент может переживать падения, перезагрузки и работать часами без потери состояния.

На GitHub у проекта 8 411 звёзд — меньше, чем у LangChain (100K+), но для специализированного фреймворка с узкой нишей (MCP-агенты) это солидный показатель. За первый год с момента создания (декабрь 2024) проект прошёл путь от экспериментального инструмента до стабильного релиза 3.0 с семью паттернами, поддержкой Temporal и деплоем в облако через uvx mcp-agent deploy.

Архитектура: четыре слоя

MCP-Agent построен как четырёхуровневая система, где каждый слой решает свою задачу и может быть заменён независимо. Это не монолит, а модульный конструктор.

Слой 1: MCPApp (рантайм)

MCPApp — это runtime приложения. Он отвечает за чтение конфигурации из YAML, инициализацию логгера, подключение к execution-движку (по умолчанию asyncio, опционально Temporal). Все компоненты ниже живут внутри контекстного менеджера app.run(). Без MCPApp ни один агент не запустится — это входная точка фреймворка.

Слой 2: Agent

Агент — это сущность, которая связывает инструкцию (системный промпт) с набором MCP-серверов. Вы говорите: «я агент-аналитик, использую файловую систему и веб-доступ», и фреймворк автоматически подключается к указанным серверам, управляет их жизненным циклом (запуск, переподключение при ошибке, остановка). Агент сам решает, какой MCP-сервер вызвать для выполнения запроса пользователя.

Слой 3: AugmentedLLM

Это обёртка над LLM, которая добавляет поддержку инструментов (tools через MCP), структурированного вывода и памяти. В отличие от голого OpenAI SDK, где вы сами управляете функциональными вызовами, AugmentedLLM берёт на себя роутинг: получил запрос → определил, какой инструмент нужен → вызвал MCP-сервер → вернул результат модели. Для пользователя это выглядит как обычный чат с моделью, которая умеет делать практически что угодно.

Слой 4: Workflow-паттерны

Самый интересный слой. Вместо того чтобы писать цикл «вызвать LLM → обработать → вызвать снова» вручную, MCP-Agent предлагает фабричные функции для 7 паттернов из Anthropic Building Effective Agents: от простого агента до Swarm (OpenAI-совместимый рой). Каждый паттерн — это готовая функция, которую вы вызываете и получаете работающий агент.

Семь паттернов рабочих процессов

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

Simple Agent

Базовый цикл: LLM получает запрос, решает, какие инструменты вызвать, вызывает их, получает результат, формирует ответ. Если инструментов нет — работает как обычный чат. Это отправная точка для большинства сценариев. Реализуется парой строк кода.

Parallel (Map-Reduce)

Функция create_parallel_llm() запускает несколько LLM-вызовов одновременно, каждый со своим промптом и набором инструментов, а затем агрегирует результаты. Полезно, когда нужно проанализировать документ с разных точек зрения simultaneously: один агент ищет факты, второй — даты и цифры, третий — тональность. Результаты собираются в единый отчёт.

Router и Intent Classifier

create_router_llm() и create_router_embedding() направляют запрос к нужному обработчику на основе содержимого. Например, запрос «сколько стоит подписка?» направляется в агента-консультанта по ценам, а «как сбросить пароль» — в техподдержку. Классификатор интентов (create_intent_classifier_llm()) работает аналогично, но возвращает сласс лейбл вместо маршрута.

Orchestrator-Workers

Оркестратор разбивает сложную задачу на подзадачи, распределяет их между рабочими агентами и собирает результаты. Подходит для сценариев вроде «проанализируй годовой отчёт компании»: оркестратор сам решает, какие разделы отчёта отдать специализированным агентам (финансы, операционные метрики, HR), а затем синтезирует единый вывод. Реализуется через create_orchestrator().

Deep Research

create_deep_orchestrator() — улучшенная версия оркестратора с рекурсивным исследованием. Агент может углубляться в найденные источники, переходить по ссылкам и строить дерево знаний. Полезно для анализа рынка, конкурентов или технических документаций, где нужно не просто собрать данные, а построить связную картину.

Evaluator-Optimizer

Два агента: генератор и оценщик. Генератор создаёт ответ, оценщик проверяет его качество и возвращает обратную связь. Цикл повторяется, пока ответ не пройдёт порог качества. create_evaluator_optimizer_llm() реализует этот паттерн. Полезно для задач, где качество важнее скорости: генерация кода с самопроверкой, написание сложных документов, переводы с пост-редактурой.

Swarm

create_swarm() — реализация OpenAI Swarm, совместимая с MCP. Несколько агентов могут передавать друг другу управление (handoff), работая как единая система. Каждый агент имеет свою специализацию и набор инструментов. Пользователь взаимодействует с «front-агентом», который перенаправляет запросы нужному специалисту внутри роя.

Установка и первый запуск за 5 минут

MCP-Agent ставится через pip или uv. Минимальные требования: Python 3.11+ и любая LLM с API — OpenAI, Anthropic или локальная через Ollama.

uv add "mcp-agent[openai, anthropic]"

После установки создайте конфигурационный файл mcp_agent.config.yaml в корне проекта. В этом файле описываются MCP-серверы, с которыми будет работать агент, и модели LLM:

execution_engine: asyncio
mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
openai:
  default_model: "gpt-4o"
anthropic:
  default_model: claude-sonnet-4-20250514

Теперь напишем простейшего агента, который умеет читать файлы и ходить в интернет:

import asyncio
from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="hello_world")

async def main():
    async with app.run():
        agent = Agent(
            name="finder",
            instruction="Используй файловую систему и веб-доступ для поиска информации.",
            server_names=["fetch", "filesystem"],
        )
        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            result = await llm.generate_str(
                "Найди на GitHub последнюю версию лицензии MIT и сохрани в файл license.txt"
            )
            print(result)

asyncio.run(main())

Агент запускает fetch для поиска ссылки на GitHub, затем filesystem для сохранения результата в файл. При этом фреймворк сам управляет подключением к MCP-серверам, перезапускает их в случае ошибки и корректно завершает при выходе из контекстного менеджера.

Для реальных проектов используйте execution_engine: temporal — это добавит durable execution. После перезапуска сервера агент продолжит работу с того же места, не теряя контекст и состояние вызовов.

Durable execution через Temporal: зачем это нужно

Обычный asyncio-агент живёт, пока жив процесс. Если сервер перезагрузился, соединение с LLM оборвалось или вышел таймаут — состояние агента теряется. Для коротких задач (ответить на вопрос, сгенерировать текст) это приемлемо. Но для длительных процессов — мониторинг цен, обработка входящих документов, координация нескольких агентов — потеря состояния критична.

Temporal — это платформа durable execution, которая сохраняет состояние каждого шага рабочего процесса. MCP-Agent интегрируется с Temporal через конфигурационный флаг: переключаете execution_engine: temporal — и все вызовы LLM, MCP-инструментов и промежуточные результаты автоматически логируются и восстанавливаются при перезапуске.

Это не «ещё одна база данных для состояний», а полноценный движок оркестрации, который гарантирует, что рабочий процесс будет выполнен ровно один раз (exactly-once execution), даже если сервер падал между шагами. Для production-систем с длительными цепочками вызовов — это must have.

Сравнение: MCP-Agent vs MCP Python SDK vs MCP-Use vs LangChain

Все эти инструменты решают разные задачи, но новички часто путают их. Вот ключевые различия.

Если вам нужно просто создать MCP-сервер — берите FastMCP. Если работаете с протоколом на низком уровне — берите официальный Python SDK. Если строите AI-агента, который должен подключаться к MCP-серверам и выполнять многошаговые сценарии — MCP-Agent ваш выбор.

Когда MCP-Agent действительно нужен

MCP-Agent не универсальная отвёртка — у него есть чёткая ниша. Вот сценарии, где он показывает себя лучше альтернатив.

Автоматизация работы с документами. Агент подключается к MCP-серверу файловой системы (чтение, запись, поиск по папкам) и к серверу веб-доступа, чтобы искать актуальную информацию. Сценарий: «найди все PDF-контракты за июнь, сверь их условия с текущим прайс-листом на сайте и подготовь отчёт о расхождениях». Без durable execution такой сценарий рискован: на большом количестве файлов агент может упасть по таймауту. С Temporal — гарантированно выполнит.

Интеграция с корпоративными системами. Если у вас есть 1С, CRM или ERP, и они выставлены через MCP-серверы (смотрите статью MCP-серверы для 1С), MCP-Agent может стать связующим звеном: агент получает запрос от пользователя, сам определяет, в какой системе искать данные, вызывает нужный MCP-сервер, агрегирует ответ. Не нужно писать коннекторы к каждой системе отдельно.

Customer support с роутингом. Orchestrator-Workers + Router — комбинация для поддержки: роутер определяет тему обращения (цены, техподдержка, жалоба), оркестратор распределяет подзадачи (проверить статус заказа, найти ответ в базе знаний, подготовить ответ), а evaluator-optimizer проверяет качество ответа перед отправкой. И всё это через MCP-серверы, подключённые к реальным системам компании.

Эксперименты с разными LLM. MCP-Agent не привязывает к вендору. Вы можете в конфиге указать и OpenAI, и Anthropic, и локальную модель — и переключаться между ними без изменения кода агента. Это полезно, когда нужно сравнить качество работы агента на разных моделях перед выбором для продакшена.

Деплой в облако: uvx mcp-agent deploy

В MCP-Agent 3.0 появилась команда деплоя — uvx mcp-agent deploy my-agent (beta). Она упаковывает агента со всеми зависимостями и конфигом в изолированный образ и разворачивает его в облачной среде. Это значит, что можно написать агента локально, а запустить на сервере одной командой, без ручной настройки Docker, systemd или Kubernetes.

На текущий момент (июль 2026) команда всё ещё в beta, но уже работает для базовых сценариев. Для продакшена с Temporal лучше разворачивать агента через стандартный Temporal Worker — это даёт больше контроля над мониторингом и масштабированием.

Ограничения и подводные камни

MCP-Agent — молодой фреймворк (первый релиз декабрь 2024), и у него есть ограничения, о которых стоит знать до того, как вы выберете его для продакшена.

Привязка к asyncio. Весь фреймворк построен на asyncio. Если ваш стек синхронный (Flask, Django ORM без async) — придётся использовать asyncio.run() как мост. Это работает, но добавляет оверхед на переключение контекста. Для синхронных проектов с большим количеством блокирующих операций MCP-Agent не самый оптимальный выбор.

Документация ещё догоняет код. Фреймворк развивается быстро, и документация не всегда успевает за релизами. Например, функция create_swarm() появилась в 3.0, но её документация в docs.mcp-agent.com появилась только через 2 недели после релиза. Для сложных кейсов приходится читать исходники — благо код написан чисто и с type hints.

Temporal требует инфраструктуры. Для durable execution нужно поднимать Temporal Server — это отдельный компонент в вашей инфраструктуре. Temporal Cloud — платная альтернатива (от $10/мес). Если ваш проект маленький и короткие сессии (<1 минута), asyncio-режима достаточно.

Сообщество. 8,4K звёзд — это солидно для нишевого инструмента, но не сравнится с LangChain (100K+) или даже CrewAI (25K+). Вопросов на Stack Overflow мало, основное обсуждение — в GitHub Issues. Если вы привыкли находить ответы на любую проблему через 5 минут гугления — с MCP-Agent так не получится.

Коротко

MCP-Agent — это фреймворк, который закрывает конкретную нишу: нужно построить AI-агента, который работает через MCP-протокол, поддерживает сложные сценарии (распараллеливание, роутинг, оркестрацию) и может работать надёжно в production через Temporal. Он не пытается быть «ещё одним LangChain» — он точечно решает задачу MCP-агентов и решает её хорошо.

Для старта достаточно 15 минут: поставить через uv add, создать YAML-конфиг с парой MCP-серверов и написать 20 строк кода. Для серьёзного продакшена — подключить Temporal и продумать инфраструктуру. Выбор между MCP-Agent и альтернативами — это не вопрос «кто лучше», а вопрос архитектуры: если вам нужен durable MCP-агент с готовыми паттернами — MCP-Agent лучший вариант на Python в 2026 году.

Что ещё важно знать