FastMCP или MCP Python SDK: какие пакет и импорт выбрать

FastMCP или MCP Python SDK: какие пакет и импорт выбрать — вопрос решается двумя строками. Самостоятельный фреймворк ставится как fastmcp==4.1.8 и импортируется from fastmcp import FastMCP. Официальный SDK v2 ставится как mcp==2.3.0 и импортируется from mcp.server import MCPServer. Старый путь from mcp.server.fastmcp import FastMCP относится к SDK v1.

Текущие пакеты и импорты

Снимок на 13 ноября 2026 года даёт три различимые сущности. Самостоятельный фреймворк fastmcp==4.1.8 живёт в пакете fastmcp, его класс называется FastMCP, документация размещена на gofastmcp.com/docs. Официальный SDK v2 в версии mcp==2.3.0 экспортирует класс MCPServer из модуля mcp.server, документация — на py.sdk.modelcontextprotocol.io. Историческая ветка mcp<2 сохраняет прежний импорт from mcp.server.fastmcp import FastMCP и описана в разделе /v1/.

Практический порядок для читателя: создайте отдельное чистое виртуальное окружение под каждый вариант и установите только его прямую зависимость. Самостоятельный FastMCP может подтянуть SDK транзитивно, и это не превращает два API в один. Команды ниже предназначены читателю; редакция их не выполняла.

# Окружение standalone:
python -m pip install "fastmcp==4.1.8"
python standalone_server.py

# Другое окружение sdk:
python -m pip install "mcp==2.3.0"
python sdk_server.py

В раздельных окружениях проверяйте прямую зависимость выбранного варианта. Для SDK используйте python -c "import mcp; print(mcp.__file__)", для самостоятельного фреймворка — python -c "import fastmcp; print(fastmcp.__file__)". Классы текущих API называются MCPServer и FastMCP. Не требуйте наличия fastmcp в чистом окружении, где установлен только mcp.

Почему старый импорт SDK перестал работать

Документация официального SDK v2 на странице «What’s new in v2» описывает переименование высокоуровневого серверного класса вместе с его модулем. Источник сообщает об удалении старого пути импорта. Это первое, с чем сталкивается каждый сервер, написанный по руководствам v1.

Практическое следствие: при mcp==2.3.0 строка from mcp.server.fastmcp import FastMCP приводит к ModuleNotFoundError. Текущий SDK предлагает from mcp.server import MCPServer и конструктор MCPServer("add-demo"). Альтернативный самостоятельный пакет имеет собственный импорт FastMCP, и это другой продукт с другой документацией.

Закрепление mcp<2 остаётся допустимым для осознанного сохранения исторического API. Такой шаг фиксирует версию ради совместимости с существующим кодом. Скрытой починкой текущего примера он не становится: код продолжает жить на старом контракте, а новая документация описывает новый класс. При обновлении проекта полезно сначала определить, какой импорт используется в каждом файле, затем выбрать целевую ветку и только после этого править сигнатуры.

Страница «What’s new in v2» называет себя объяснением причин, а точный список правок вынесен в отдельный документ миграции. Этот порядок чтения экономит время: сначала причина переименования, затем построчный перечень замен. Для команды, которая ведёт несколько серверов, полезно зафиксировать целевую версию в файле зависимостей и пройти по импортам механически.

Два учебных файла с одинаковым инструментом

Ниже два самостоятельных файла. Каждый полон: импорт, объект сервера, декоратор, функция и запуск. Оба описывают один и тот же инструмент add с двумя целочисленными аргументами. Пакеты редакцией не запускались, это учебный текст по текущей документации.

# Учебный пример для fastmcp==4.1.8. Пакет редакцией не запускался.
from fastmcp import FastMCP

server = FastMCP("add-demo")

@server.tool
def add(a: int, b: int) -> int:
    """Сложить два целых числа."""
    return a + b

if __name__ == "__main__":
    server.run(transport="stdio")

# Учебный пример для mcp==2.3.0. Пакет редакцией не запускался.
from mcp.server import MCPServer

server = MCPServer("add-demo")

@server.tool()
def add(a: int, b: int) -> int:
    """Сложить два целых числа."""
    return a + b

if __name__ == "__main__":
    server.run(transport="stdio")

В приведённых минимальных файлах при переносе меняют импорт, имя конструктора FastMCP или MCPServer и запись декоратора. Самостоятельный FastMCP принимает @server.tool и @server.tool(), официальный SDK требует @server.tool(). Имя объекта server и имя инструмента add можно сохранить.

Держите оба файла в одном репозитории под разными именами, например standalone_server.py и sdk_server.py. Для переключения выберите нужное окружение и запустите соответствующий файл. Такой приём полезен при оценке выбора: вы запускаете один и тот же инструмент в двух конфигурациях и сравниваете удобство работы с документацией.

Декораторы, аннотации и контракт tools/list

Аннотации типов формируют входную схему инструмента. Документация официального SDK v2 прямо указывает: входная схема по-прежнему выводится из ваших type hints. Это значит, что a: int и b: int в сигнатуре дают два целочисленных поля в описании инструмента, а возвращаемый тип -> int документирует результат.

Ожидаемый контракт обоих файлов одинаков. Ответ сервера на tools/list должен содержать инструмент add с двумя целочисленными аргументами a и b. Вызов add с аргументами {"a": 2, "b": 3} имеет математический результат 5. Это описание ожидаемого контракта; результат вызова MCP-клиентом редакция не получала.

Проверка контракта идёт в два шага. Сначала клиент запрашивает список инструментов и сверяет имена и типы аргументов. Затем отправляет вызов с конкретными значениями и сверяет результат. Чтение участка return a + b в исходнике даёт представление о логике, а протокольную проверку заменяет только фактический обмен сообщениями.

Документация gofastmcp.com в разделе Quickstart описывает сервер как набор инструментов, ресурсов и других компонентов MCP, а добавление инструмента — как функцию с декоратором. Этот же принцип действует в официальном SDK. Различие лежит в деталях записи, которые и создают основной источник ошибок при копировании примеров из разных руководств.

Stdio как локальный транспорт

Документация gofastmcp.com называет stdio традиционным способом подключения MCP-серверов к клиентам, а HTTP-транспорт — способом удалённых подключений. Официальный SDK v2 в описании изменений упоминает stdio-подпроцесс среди вариантов подключения клиента, наряду с URL для Streamable HTTP и объектом сервера в памяти для тестов.

Ключевое следствие для проверки: запуск stdio-сервера ожидает сообщения клиента. Отсутствие печати «5» при старте файла не свидетельствует об ошибке. Сервер открыл канал и ждёт запроса; результат появится после того, как клиент отправит tools/call. Пустой терминал после команды запуска — нормальное состояние ожидания.

Для протокольной проверки настройте MCP-клиент на запуск выбранного файла сервера как stdio-подпроцесса. Клиент управляет stdin и stdout этого процесса. Затем он запрашивает tools/list, сверяет описание add и отправляет tools/call с аргументами. Так проверяются импорт, транспорт, схема и вызов; отдельный процесс, запущенный вручную в терминале, не создаёт подключение клиента.

Официальный SDK v2 поддерживает подключение к объекту сервера в памяти для тестов, и это описано в его документации. Такой режим полезен для быстрой проверки схемы без запуска подпроцесса. Для локальной разработки stdio остаётся основным вариантом, поскольку клиенты подключаются к нему напрямую.

Выбор по требованиям проекта

Развилка решается требованиями учебной задачи. Команде, которая использует официальную документацию и создаёт один инструмент add, подойдёт MCPServer из mcp==2.3.0. Для объединения серверов и подключения OpenAPI через готовые надстройки можно рассмотреть самостоятельный FastMCP и проверить соответствующие разделы его документации. Это выбор по требованиям; скорость и надёжность здесь не измерялись.

Тестирование в памяти присутствует в текущем SDK v2, поэтому объявлять его исключительным преимуществом самостоятельного FastMCP некорректно. Таблица не гарантирует готовую аутентификацию или автоматическую защиту удалённого сервера: эти свойства требуют отдельной проверки в документации выбранного пакета.

При выборе полезно выписать требования списком и напротив каждого поставить ссылку на раздел документации, который его закрывает. Если требование не находит раздела, оно остаётся открытым вопросом проекта. Такой подход даёт проверяемое решение вместо вкусового предпочтения.

Проверка миграции

Миграция проверяется по шагам, без обещаний производительности. Первый шаг: зафиксировать текущую версию пакета и список импортов во всех файлах. Второй шаг: определить целевую ветку — mcp==2.3.0 с MCPServer или fastmcp==4.1.8 с FastMCP. Третий шаг: заменить импорт, имя конструктора и, если требуется, запись декоратора. Четвёртый шаг: запросить tools/list и сверить схему инструментов. Пятый шаг: отправить tools/call с реальными аргументами и сверить результат.

Отдельного внимания требует поведение валидаторов. Руководство FastMCP «Upgrading from MCP SDK v2» в разделе Stricter Arguments описывает различие: MCPServer связывает известные аргументы и игнорирует остальные, поэтому вызов с неожиданным ключом проходит. FastMCP объявляет additionalProperties: false в каждой сгенерированной схеме и проверяет это условие, поэтому такой же вызов завершается отказом. Конкретный класс ошибки, wire-код и форму сообщения мы не приводим: они в этом разборе не проверялись.

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

Проверку удобно вести на копии сервера в отдельном окружении. Сначала прогоните оба варианта tools/call — с чистым payload и с лишним полем — и зафиксируйте наблюдаемое поведение. Затем примите решение по каждому клиенту: убрать лишнее поле или расширить сигнатуру. Такой порядок отделяет проверку контракта от правки кода.

Разбор лишнего request_id

Предположим, клиент передаёт идентификатор для своего учёта рядом с аргументами. Это дополнительное условие учебного примера. Сервис для этого разбора не запускался. Исходный payload tools/call выглядит так:

{"name": "add", "arguments": {"a": 2, "b": 3, "request_id": "r-17"}}

В обеих первоначальных сигнатурах есть только a и b. Поведение валидаторов расходится по документации: MCPServer игнорирует лишний ключ, FastMCP отклоняет его до получения полезного результата. Ниже таблица учебных случаев с ожидаемым поведением по сохранённой первичке.

Исправление первое — убрать клиентское служебное поле из arguments. Готовый исправленный payload:

{"name": "add", "arguments": {"a": 2, "b": 3}}

Идентификатор r-17 остаётся во внутренней записи клиента, вне аргументов инструмента. Переносить его в произвольное поле протокола без отдельной проверки спецификации не стоит.

Исправление второе — если идентификатор действительно нужен инструменту, принять его явно. Полная функция для standalone-файла; импорт, объект и запуск остаются из файла выше:

@server.tool
def add(a: int, b: int, request_id: str | None = None) -> int:
    """Сложить два числа; request_id — необязательный идентификатор клиента."""
    return a + b

Для SDK та же сигнатура с его формой декоратора:

@server.tool()
def add(a: int, b: int, request_id: str | None = None) -> int:
    """Сложить два числа; request_id — необязательный идентификатор клиента."""
    return a + b

Здесь request_id намеренно не влияет на сумму и не записывается в журнал. Приём поля не доказывает сохранение идентификатора: аудит реализуется отдельно. Добавление параметра меняет сгенерированную схему инструмента, и это другое решение по сравнению с игнорированием лишнего поля. Для учебного клиента, где r-17 нужен только локальному учёту, принято первое исправление: очищенный payload и неизменные два серверных файла.

Частые вопросы

FastMCP и MCP Python SDK — это одно и то же?

Это два разных продукта. Самостоятельный фреймворк устанавливается как fastmcp==4.1.8 и импортируется from fastmcp import FastMCP. Официальный SDK v2 устанавливается как mcp==2.3.0 и импортируется from mcp.server import MCPServer. Текущие классы называются FastMCP и MCPServer; имя FastMCP внутри официального SDK относится к исторической ветке v1.

Почему старый импорт from mcp.server.fastmcp import FastMCP больше не работает?

Документация официального SDK v2 на странице «What’s new in v2» описывает переименование высокоуровневого серверного класса вместе с модулем. Старый путь импорта исчез, поэтому при mcp==2.3.0 строка приводит к ModuleNotFoundError. Текущий SDK предлагает импорт MCPServer из модуля mcp.server.

Как проверить, что инструмент зарегистрирован правильно?

Запросите у сервера tools/list и сверьте имя инструмента и типы аргументов с ожидаемой схемой. Затем отправьте tools/call с конкретными значениями и сверьте результат. Чтение исходного кода даёт представление о логике, а протокольную проверку заменяет только фактический обмен сообщениями.

Почему при запуске stdio-сервера ничего не печатается?

Stdio-сервер ожидает сообщения клиента и сам не печатает учебную сумму при запуске. Для протокольной проверки настройте MCP-клиент на запуск файла сервера как stdio-подпроцесса. Клиент управляет его вводом и выводом, запрашивает tools/list и получает результат tools/call.

Что делать, если клиент передаёт лишнее поле рядом с аргументами?

По руководству FastMCP «Upgrading from MCP SDK v2» MCPServer игнорирует незнакомые ключи, а FastMCP объявляет additionalProperties: false и отклоняет их. Уберите служебное поле из arguments, если оно нужно только локальному учёту клиента. Если поле действительно требуется инструменту, примите его явным необязательным параметром и согласуйте новую публичную схему.