В этой статье рассмотрим 7 распространенных ошибок, которые разработчики допускают при создании MCP‑серверов на FastMCP: от отсутствующих аннотаций инструментов и слабой обработки ошибок до ответов, расходующих слишком много токенов, и пробелов в безопасности. Поговорим о конкретных способах исправления каждой ошибки.

Model Context Protocol переживает взрывной рост популярности: за первый год было создано более 10 000 репозиториев серверов, а в официальном реестре уже насчитывается более 518 серверов. Многие из них построены на FastMCP — Python‑фреймворке, который упрощает предоставление инструментов LLM‑агентам. Но «упрощает» не значит «защищает от ошибок». 

После изучения десятков реализаций MCP‑серверов, включая собственный MCP‑сервер Google Ads от Google, снова и снова всплывают одни и те же проблемы. 

Ниже — семь самых распространенных ошибок и способы их исправить.

1. Не помечать изменяющие операции

Любой вызов MCP‑инструмента остается для клиента «черным ящиком», пока вы явно не сообщите, что именно он делает. Без аннотаций у клиентов вроде Claude Code и ChatGPT остаются два плохих варианта: запрашивать подтверждение у пользователя при каждом вызове, создавая лишнее трение, или автоматически одобрять всё, что опасно. 

В редакции спецификации MCP от 2025–03-26 появились ToolAnnotations (PR #185), которые решают эту проблему:

from mcp.types import ToolAnnotations

READ_ONLY = ToolAnnotations(readOnlyHint=True)
MUTATING = ToolAnnotations(readOnlyHint=False, destructiveHint=True)

@mcp.tool(annotations=READ_ONLY)
def get_campaigns(...): ...

@mcp.tool(annotations=MUTATING)
def create_campaign(...): ...

Эти аннотации — подсказки, а не гарантии: в спецификации прямо указано, что клиенты не должны доверять им, если сервер ненадежный. Но для доверенных серверов они позволяют клиентам пропускать запросы подтверждения для инструментов только для чтения и помечать разрушительные операции как требующие явного одобрения. В спецификации также предусмотрены idempotentHint и openWorldHint для более точной сигнализации. Помечайте каждый инструмент. Это одна строка, которая помогает предотвратить случайную потерю данных.

2. Выставлять наружу сырые API‑примитивы вместо инструментов, ориентированных на результат

Распространенный шаблон: завернуть язык запросов API в инструмент search() и считать задачу закрытой. В итоге LLM приходится с нуля составлять GAQL‑запросы, мутации GraphQL или словари protobuf. Она будет ошибаться. Снова и снова.

MCP‑сервер Google Ads — показательный пример того, как делать не стоит. Он предоставляет ровно три инструмента: низкоуровневый инструмент поиска, который принимает GAQL‑запросы, инструмент list_accessible_customers и инструмент get_resource_metadata. И всё. Чтобы создать кампанию, LLM должна с нуля составить GAQL‑мутации. Чтобы получить показатели эффективности кампании, ей нужно знать, какие поля GAQL выбрать, как форматировать диапазоны дат и как задавать условия. 

Это ловушка API‑примитивов на практике: сервер повторяет поверхность Google Ads API, вместо того чтобы оборачивать ее в инструменты, ориентированные на результат (outcome‑oriented tools), например get_campaigns или create_campaign, которые сами строят запросы внутри.

Проектируйте инструменты вокруг того, чего агент хочет добиться, а не вокруг низкоуровневых конечных точек API. Хорошо спроектированный MCP‑сервер Google Ads предлагал бы get_campaigns, который заранее выбирает нужные поля GAQL и обрабатывает фильтрацию по датам, или create_campaign, который собирает полную цепочку мутаций: бюджет, кампанию, группу объявлений — с разумными значениями по умолчанию. 

Низкоуровневый search‑инструмент всё еще может существовать для опытных пользователей, которым нужна полная гибкость, но удобные инструменты должны закрывать типовые сценарии, не заставляя LLM изучать язык запросов.

Как сказано в руководстве Docker по лучшим практикам MCP, конечный пользователь инструмента — это агент или LLM, а не человек. Проектируйте с учетом этого.

3. Не задавать безопасные значения по умолчанию

MCP‑инструмент, который по умолчанию создает кампанию Google Ads со статусом ENABLED, начнет тратить реальные деньги в тот момент, когда LLM его вызовет. Любой инструмент для создания кампаний должен по умолчанию выставлять статус PAUSED: агент или пользователь должны включить кампанию явно. Это исправляется одной строкой и предотвращает потенциально дорогие ошибки:

@mcp.tool(annotations=MUTATING)
def create_campaign(name: str, budget_amount: float, ...):
      """Создает новую кампанию. По умолчанию присваивает статус PAUSED."""
    campaign.status = client.enums.CampaignStatusEnum.PAUSED
    ...

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

4. Слабая документация инструментов

LLM читают схемы ваших инструментов. Имя каждого параметра, описание и ограничение типа становятся частью промпта, с которым работает агент. Параметр с названием enable_slow_ramp без описания для LLM — почти подбрасывание монетки. Документация FastMCP рекомендует использовать Annotated вместе с Pydantic Field, чтобы получать самодокументируемые схемы (self‑documenting schemas):

from typing import Annotated
from pydantic import Field

CustomerId = Annotated[str, Field(
    description="Google Ads customer ID, numeric string without dashes",
    pattern=r"^\d{10}$",
    examples=["1234567890"]
)]

DateRange = Annotated[str, Field(
    description="Date in YYYY-MM-DD format",
    pattern=r"^\d{4}-\d{2}-\d{2}$"
)]

Помимо параметров, строки документации (docstrings) инструментов должны описывать, как выглядит ответ, а не только то, что делает инструмент. Добавьте раздел ## Формат ответа с примером вывода. Без него LLM будет вызывать инструмент наугад и может неверно интерпретировать структуру ответа.

Для статических справочных материалов — списков полей API, значений перечислений, синтаксиса языка запросов — используйте MCP Resources, а не пытайтесь втиснуть всё в описания инструментов. Resources управляются приложением: хост запрашивает их только при необходимости, сохраняя окно контекста чистым.

5. Проглатывать сообщения об ошибках

Многие API возвращают общие ошибки вроде «Bad Request» или «Internal Server Error» без подробностей. Когда MCP‑сервер передает их дальше без изменений, LLM не получает информации, с которой можно работать. Она попадает в цикл самокоррекции: повторяет запросы с небольшими изменениями, расходует токены и часто исчерпывает бюджет API‑запросов, так и не исправив реальную проблему.

Исправление состоит из двух частей. Во‑первых, когда вы обнаруживаете общее сообщение об ошибке — типичные варианты: «bad request», «internal server error», «not found» — добавляйте к нему полное тело ответа. Необработанный ответ обычно содержит ошибки валидации на уровне полей или диагностическую информацию, на которую LLM может опереться. 

Во‑вторых, не обрезайте ответы с ошибками слишком агрессивно. Ограничение ошибки в 50 символов имело смысл для пользовательских интерфейсов, рассчитанных на людей; LLM нужен полный контекст, чтобы исправить себя.

6. Неэкономно расходовать токены в ответах

Каждый ответ инструмента занимает место в окне контекста. JSON‑ответы с табличными данными особенно расточительны: имена ключей повторяются в каждой строке:

[{"campaign.name": "Brand", "campaign.id": 123, "metrics.clicks": 500}, ...]

Те же данные в CSV:

campaign.name,campaign.id,metrics.clicks
Brand,123,500

CSV убирает повторяющиеся ключи, фигурные и квадратные скобки, кавычки и обычно экономит 40–60% токенов на табличных данных. Подумайте о том, чтобы добавить в инструменты только для чтения параметр response_type: по умолчанию — «csv», а JSON оставить доступным для случаев, когда структурированные данные нужны для программной обработки. 

Реализация простая: служебная функция format_rows_as_csv(), которая преобразует list[dict] в CSV‑строки, а вложенные значения — списки и словари — сериализует в JSON внутри ячеек.

7. Игнорировать основы безопасности

Исследование Endor Labs, охватившее 2 614 реализаций MCP, показало: 82% из них используют операции с файловой системой, уязвимые к обходу путей, 67% используют API, подверженные внедрению кода, а 34% уязвимы к внедрению команд. Это не теоретические риски:

Поверхность атаки здесь широкая: инъекция промпта встраивает вредоносные инструкции в контент, который обрабатывает LLM; отравление инструментов подменяет или искажает метаданные инструментов; а усталость от подтверждений эксплуатирует пользователей, которые начинают автоматически одобрять запросы после десятков безобидных подтверждений. 

Проверяйте все входные данные на границе системы. Никогда не храните учетные данные в открытом виде и не передавайте их в URL. Относитесь к каждой строке, полученной от LLM, как к недоверенному пользовательскому вводу, потому что именно этим она и является.

Ключевые выводы

• Аннотируйте каждый инструмент с помощью ToolAnnotations из спецификации MCP от 2025–03-26. Одна строка на инструмент помогает предотвратить случайные изменения состояния.

• Проектируйте инструменты, ориентированные на результат, которые оборачивают низкоуровневые API‑примитивы. LLM лучше работает с get_campaigns, чем с универсальным конструктором запросов.

• По умолчанию используйте безопасные состояния: кампании в статусе PAUSED, черновики ресурсов, консервативные ограничения.

• Подробно документируйте параметры с помощью Annotated + Field. Включайте примеры формата ответа в строки документации.

• Передавайте LLM полные сообщения об ошибках. Общие ошибки запускают дорогостоящие циклы повторных попыток.

• Для табличных данных по умолчанию возвращайте CSV. Это сокращает расход токенов на 40–60% без потери информации.

• Проверяйте все входные данные, не храните секреты в открытом виде и относитесь к строкам, сгенерированным LLM, как к недоверенным. За первый год MCP получил более 30 CVE — не пополняйте этот список.

Когда MCP‑сервер становится частью рабочего AI‑агента, ошибки в схемах инструментов, обработке ответов, безопасности и расходе токенов быстро превращаются из «технических деталей» в реальные продуктовые риски. Если хотите глубже разобраться, как LLM работают с контекстом, почему AI‑системам нужны критерии качества и как агенту правильно давать навыки через MCP, приходите на открытые уроки OTUS:

➊ 19 мая, 20:00. «Критерии качества и безопасности AI-систем в продукте». Записаться
_{Поможет понять, как оценивать AI-систему не по демо, а по надежности, безопасности и предсказуемости.}

➋ 20 мая, 20:00. «Что надо знать про работу LLM моделей». Записаться
_{Поможет разобраться, почему агент ошибается, расходует лишние токены и неверно интерпретирует ответы инструментов.}

➌ 15 июня, 20:00. «Интеграция ИИ-агентов в рабочую разработку: обвязка агента навыками и MCP». Записаться
_{Даст практический взгляд на то, как подключать MCP и навыки к агенту без типовых архитектурных ошибок.}

На занятиях разберем похожие инженерные задачи: как проектировать AI‑системы так, чтобы агент не тратил лишние токены, не ломался на плохих ответах инструментов и не превращал удобную автоматизацию в новую поверхность атаки.