Рекомендации по проектированию MCP-инструментов

Ниже приведены рекомендации (best practices), направленные на повышение совместимости с различными MCP-клиентами и улучшение качества выбора инструментов AI-агентом. Данные рекомендации не являются особенностью реализации MCP-сервера в Loginom и отражают общие подходы к проектированию MCP-инструментов, сложившиеся на текущем этапе развития данной технологии.

Рекомендации по имени инструмента (tool.name)

Имя публикуемого узла используется в качестве имени инструмента.

Рекомендуется придерживаться следующих правил:

• Допустимые символы. Для максимальной совместимости рекомендуется использовать диапазон символов ^[A-Za-z0-9_-]+$.

  В Loginom эта рекомендация выполняется автоматически, поскольку для имён узлов действует более строгое ограничение: ^[A-Za-z_][A-Za-z0-9_]*$.

• Длина имени. Рекомендуемая длина — не более 64 символов.

• Регистр. tool.name является регистрозависимым (case-sensitive). Рекомендуется придерживаться единого стиля именования, например, lower_snake_case:

  • все буквы строчные
  • слова разделяются подчёркиванием _.

• Семантика имени. Имя инструмента рекомендуется формировать по принципу глагол + объект, например:

  search_tickets, normalize_address, export_to_postgres, ticket_search_v2

  Следует избегать слишком похожих имён инструментов в пределах одного MCP-сервера.

Рекомендации по описанию инструмента (tool.description)

Описание инструмента (задается в комментарии к публикуемому узлу) является основным сигналом для AI-агента при выборе подходящего инструмента.

Рекомендуется:

• использовать краткое описание (1–3 предложения);
• не включать подробное описание параметров (они должны описываться в schema);
• указывать назначение инструмента и условия его применения;
• при необходимости обозначать ограничения использования (например, если инструмент ресурсоёмкий, медленный или явно не предназначен для решения определенных задач).

Обычно полезно, чтобы из описания было понятно:

• что делает инструмент;
• в каких случаях его следует использовать;
• какие ограничения важно учитывать (если они есть).

Например: Ищет заявки по тексту и атрибутам. Используй, когда нужно найти набор подходящих заявок. Не подходит для получения заявки по точному идентификатору.

Рекомендации по описанию входных переменных

Для переменных порта рекомендуется при необходимости заполнять поле Описание, так как оно включается в inputSchema инструмента как description параметра и может использоваться MCP-клиентом и AI-агентом при формировании вызова инструмента.

Описание особенно полезно, если без него назначение параметра или правила его заполнения могут быть неочевидны.

В описании переменной при необходимости рекомендуется указывать:

• назначение параметра;
• допустимые значения или формат;
• важные ограничения и требования к заполнению;
• связь с другими параметрами, если она есть;
• значение по умолчанию, если оно предполагается логикой инструмента;
• пример использования, если без него смысл параметра может быть неочевиден.

Примеры описаний:

• Идентификатор региона. Указывается номер региона в справочнике ФИАС.
• Начало периода отбора. Допустимые значения — не ранее 1970-01-01. Используется совместно с параметром «Дата окончания периода». Значение не должно быть больше даты окончания периода.

Примечание: Описание входных параметров не заменяет описание инструмента в целом: комментарий к публикуемому узлу используется для tool.description, а поле Описание у переменной — для документирования отдельного параметра.

Уникальность функциональности инструментов

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

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

Рекомендуется:

• проектировать инструменты с чётко различимой областью применения;
• давать инструментам разные и однозначные описания;
• при необходимости указывать в tool.description, в каких ситуациях следует использовать именно данный инструмент.

Например, вместо нескольких инструментов с похожими функциями:

• search_tickets
• find_tickets
• lookup_ticket_data

предпочтительно использовать:

• search_tickets — поиск тикетов по тексту и атрибутам;
• get_ticket_by_id — получение информации о тикете по идентификатору.

Стабильность имен инструментов

Рекомендуется обеспечивать стабильность имен инструментов (tool.name) после их публикации.

AI-агенты и внешние приложения могут сохранять информацию о доступных инструментах или строить логику работы на основе их имен. Изменение имени инструмента может привести к некорректной работе таких интеграций.

Если требуется изменить функциональность инструмента, предпочтительно:

• сохранить существующее имя инструмента;
• либо создать новый инструмент с новым именем, оставив предыдущий для обратной совместимости.

Например:

• ticket_search_v1
• ticket_search_v2

Примечание: Имена вида ..._v1, ..._v2 уместны прежде всего в сценариях обратной совместимости, когда необходимо сохранить работоспособность существующих клиентов при изменении инструмента. Однако постоянного сосуществования нескольких почти одинаковых инструментов лучше избегать, чтобы не усложнять выбор инструмента AI-агентом.

Длительное выполнение инструментов и таймауты

В Loginom Integrator вызов MCP-инструмента выполняется синхронно: MCP-сервер возвращает ответ только после завершения выполнения соответствующего сценария в Loginom Server.

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

Рекомендации:

• при проектировании MCP-инструментов учитывать, что синхронные вызовы должны укладываться в разумное время выполнения;
• обязательно тестировать фактическую длительность выполнения каждого инструмента в условиях, близких к рабочим (с учётом инфраструктуры и настроек таймаутов);

• если сценарий потенциально выполняется долго, рассмотреть один из подходов:

  • разделение на более короткие инструменты;
  • асинхронную схему (запуск задачи → получение статуса/результата отдельными вызовами);
  • согласованную настройку таймаутов по всей цепочке (клиент → прокси → Integrator).