Проектирование MCP-инструментов: как избежать провалов и перегрузки контекста LLM

Представьте: вы собрали MCP-сервер, навешали туда 30 инструментов, каждый с подробным описанием и десятком параметров. Запускаете агента на Claude Code — и через два-три вызова LLM начинает тупить, отвечать невпопад, а навигация по проекту превращается в лотерею. Знакомо? Поздравляю, вы попали в ловушку перегрузки контекста, которая сегодня валит каждый второй MCP-проект в продакшене.

Разработчики агентов в 2026 году массово осознали: MCP-инструменты — не просто способ расширить возможности LLM, а прямой канал, по которому модель потребляет контекст. Каждый tool — это десятки, а то и сотни токенов в системном промпте. Когда их становится слишком много, LLM теряет фокус, начинает игнорировать важные инструкции, а время первого токена (TTFT) растёт из-за раздутого KV-кеша. Если вы не хотите, чтобы ваш агент напоминал бабушку, которая переспрашивает по десять раз — читайте дальше.

Золотая лихорадка MCP: почему каждый ваш инструмент — это контекстная бомба

В начале 2025 года MCP начал взрывной рост — каждый второй стартап лепил десятки инструментов для своего AI-помощника.LM Studio и OpenWebUI боролись за совместимость, а разработчики плодили MCP-серверы сотнями. Проблема в том, что ни протокол, ни бенчмарки не учили главному: как спроектировать инструменты так, чтобы LLM могла ими эффективно пользоваться.

Суть проста: каждый MCP-инструмент добавляет в системный промпт имя, описание, схему параметров (часто с примерами). LLM вынуждена держать в активном контексте все эти сигнатуры. Если инструментов больше десяти-пятнадцати, модель начинает путаться — какой tool для какой задачи, какие параметры обязательны, а какие опциональны. Результат: hallucination, неправильные вызовы, потеря производительности.

Типичный портрет жертвы: MCP-сервер с 25+ инструментами, где половина — «getFoodItems», «getFoodItemById», «searchFoodItems», «filterFoodItemsByCategory»... Каждый занимает 100–200 токенов. Итого 5000+ токенов только на описание тулзов. А если добавить ещё инструкции для агента — контекстное окно в 128K токенов заполняется на треть уже на старте. Откуда брать память на историю диалога?

Первыми тревогу забили инженеры, которые начали замерять реальное потребление контекста. Появились инструменты вроде MCP Slim — решение, которое сокращает расход контекста на 96% с помощью локального семантического поиска. Идея: не грузить все инструменты сразу, а подгружать только релевантные по запросу. Но это паллиатив. Корень проблемы — в архитектуре самих инструментов.

Анатомия перегрузки: как LLM тонет в море сигнатур

Давайте разберём, что конкретно ломает контекст. Есть три главных фактора:

• Количество инструментов. LLM с трудом удерживает в фокусе более 10–12 тулзов. Каждый новый tool — шум, который отвлекает от основного задания.
• Длина описаний. Писать «Этот инструмент используется для получения списка заказов, где можно фильтровать по дате, статусу, сумме, покупателю, и сортировать по различным полям...» — значит тратить токены впустую. LLM нужно краткое, однозначное описание, желательно в одну строку.
• Избыточные параметры. Если у инструмента 10 параметров, из которых 8 опциональны — LLM придётся анализировать все комбинации. Это ведёт к росту времени инференса и деградации качества.

Вспомните как MCP отвечают как бабушки в очереди — та же проблема, только на стороне ответов. Когда инструмент возвращает гору данных, LLM тратит контекст на бесполезную информацию. Решение — mcp-context-proxy, который режет болтовню. Но на стороне описаний нужна аналогичная гигиена.

Ещё один важный аспект — контекстная зависимость инструментов. Если у вас есть tool getUser, который требует userId, и другой — getOrdersByUser, который тоже требует userId, то LLM вынуждена хранить userId в контексте между вызовами. Это усиливает давление на окно. Лучше передавать userId через параметры вызова, а не через состояние.

5 принципов проектирования MCP-инструментов для 2026 года

Я собрал практические правила, которые проверены на десятках проектов — от внутренних ассистентов до продакшен-систем с тысячами запросов в день.

1 Один инструмент — одна ответственность (Single Responsibility Principle)

Никаких «супертулзов», которые ищут, создают, обновляют и удаляют. Разделите на отдельные CRUD-операции. Но не перебарщивайте — если у вас 10 разных инструментов для одной сущности, задумайтесь об объединении с action-параметром (см. принцип 4).

2 Описание — только суть, без воды

Используйте шаблон: «Get users by optional filters: name, email, role. Returns list with ids.» — 15 слов. Не пишите «Retrieves a collection of user entities from the database with optional filtering...». LLM понимает короткие описания не хуже (а часто лучше) длинных.

Если нужно добавить контекст для модели — используйте скрытые подсказки в параметрах (например, description самого параметра). Это помогает LLM понять, что передавать, но не засоряет общее описание инструмента.

3 Минимум параметров — только обязательные

Каждый опциональный параметр добавляет модели работу: «а может передать, а может не передать?». Если параметр используется в 10% случаев — вынесите его в отдельный инструмент: getUserDetailed вместо getUser с флагами. Это звучит как антипаттерн, но на практике снижает количество ошибок вызова.

4 Объединяй родственные, но с умом

Если у вас 5 инструментов для работы с заказами (получить, создать, обновить статус, отменить, удалить) — объедините их в один tool с параметром action (enum). Это сокращает количество инструментов, но не перегружает описание. Главное — дать понятные значения enum и по одному описанию для каждого действия.

5 Динамическая загрузка — ваш друг

Не давайте LLM все инструменты сразу. Используйте подход MCP Slim или семантический поиск: на основе запроса пользователя загружайте только релевантные тулзы. Это снижает потребление контекста на 90%+.

Практика: рефакторинг MCP-сервера на Python — как НЕ надо

Допустим, у вас есть сервер для управления задачами (todos). Типичная ошибка — сделать 6 микро-инструментов.

# ❌ ПЛОХО: 6 инструментов, много дублирования в описаниях
@mcp.tool()
def get_all_todos(limit: int = 20, offset: int = 0) -> list:
    """Get all todo items with pagination."""
    ...

@mcp.tool()
def create_todo(title: str, description: str = "", priority: str = "medium") -> dict:
    """Create a new todo with optional description and priority."""
    ...

@mcp.tool()
def update_todo_status(todo_id: int, status: str) -> dict:
    """Update status of a todo (pending/in_progress/done)."""
    ...

@mcp.tool()
def delete_todo(todo_id: int) -> bool:
    """Delete a todo by id."""
    ...

# ... и так далее

Теперь исправляем: объединяем всё в один инструмент с action-параметром.

# ✅ ХОРОШО: один инструмент с action enum, описания действий в параметрах
from enum import Enum

class TodoAction(str, Enum):
    list = "list"
    create = "create"
    update_status = "update_status"
    delete = "delete"

@mcp.tool()
def manage_todo(
    action: TodoAction,
    todo_id: int | None = None,
    title: str | None = None,
    description: str | None = None,
    status: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> dict | list | bool:
    """
    Unified tool for todo operations. Use 'action' to specify operation.
    - list: returns paginated todos
    - create: creates new todo (requires title)
    - update_status: updates status (requires todo_id and status)
    - delete: deletes todo (requires todo_id)
    """
    if action == TodoAction.list:
        return get_all_todos(limit, offset)
    elif action == TodoAction.create:
        return create_todo(title, description)
    elif action == TodoAction.update_status:
        return update_todo_status(todo_id, status)
    elif action == TodoAction.delete:
        return delete_todo(todo_id)

Зачем это? Мы сократили количество инструментов с 6 до 1. Экономия токенов на описании — примерно 200–400 токенов. LLM теперь нужно запомнить только один tool, а не шесть. При этом каждое действие описано кратко внутри параметров, что не создаёт лишнего шума.

Метрики и диагностика: как понять, что ваш MCP-инструмент перегружает контекст?

Недостаточно просто спроектировать инструменты — нужно измерять их влияние. Я рекомендую следить за тремя показателями:

• Размер системного промпта (system prompt size). Замеряйте количество токенов, которые занимает описание всех инструментов. Если оно превышает 10% от контекстного окна — пора чистить.
• Время первого токена (TTFT). Раздутый KV-кеш из-за длинного описания инструментов напрямую влияет на TTFT. Подробнее об этом — в статье по оптимизации инференса LLM.
• Точность выбора инструмента. Можно логировать, какой инструмент был вызван, и считать процент корректных вызовов. Если LLM часто ошибается — инструментов слишком много или описания нечёткие.

Эти метрики должны входить в ваш мониторинг продакшена. Я рекомендую использовать Langfuse для трекинга вызовов MCP — он показывает, сколько токенов уходит на каждый инструмент.

Ошибки, которые я видел в продакшене (и их цена)

Расскажу пару случаев из реальной практики (без имён, но всё честно).

Случай 1: Инструмент-монстр с 20 параметрами. Один стартап сделал tool для генерации отчётов, у которого было 20 опциональных параметров: от дат и фильтров до цветовой схемы и шрифта. LLM тратила по 3000 токенов на каждый вызов, чтобы разобрать параметры. TTFT вырос с 200 мс до 1.5 секунд. После рефакторинга — разбили на 4 инструмента по типам отчётов, каждый с 3–5 обязательными параметрами. TTFT упал до 300 мс, а точность вызова выросла с 65% до 93%.

Случай 2: Зоопарк из 50+ инструментов. Другая команда подключила к агенту 50 инструментов для разных внутренних сервисов. LLM постоянно путалась: вместо вызова «getCustomerOrders» вызывала «getOrderCustomer». После внедрения mcpx и экономии 40K токенов контекста — они добавили семантический поиск и сократили активный набор до 5–7 инструментов. Проблема исчезла.

Ещё одна распространённая ошибка — возвращать слишком много данных. Инструмент, который отдаёт всю таблицу из БД, — убийца контекста. Заставьте себя возвращать только минимально необходимые поля. Если нужно больше — сделайте второй вызов с уточнением.

FAQ: частые вопросы про проектирование MCP-инструментов

Проектирование MCP-инструментов — это баланс между удобством для разработчика и эффективностью для LLM. Мы привыкли делать API для людей, где длинные описания и куча опциональных параметров — норма. Но модель — не человек, ей нужна чёткость и минимализм.

Мой прогноз: к концу 2026 года появятся стандарты (возможно, в MCP 2.0) для автоматической оптимизации описаний инструментов, но пока ответственность лежит на нас. Я советую начать с аудита ваших текущих серверов — замерьте, сколько токенов занимают тулзы, и попробуйте сократить это число вдвое с помощью описанных приёмов. Удачи.

Подписаться на канал