Перейти к основному содержимому

Использование инструментов MCP

После добавления и подключения MCP (Model Context Protocol) сервера предоставляемые им инструменты автоматически регистрируются в наборе доступных инструментов Agent. На этой странице описывается, как инструменты обнаруживаются, именуются и используются, а также как управлять ими в деталях.

Автоматическое обнаружение инструментов​

При успешном подключении MCP-сервера Elftia автоматически выполняет следующие действия:

  1. Получение списка инструментов — вызывает конечную точку listTools сервера для получения всех доступных инструментов
  2. Формат регистрации — регистрирует инструменты во внутренней системе инструментов
  3. Кэширование — список инструментов кэшируется на 5 минут во избежание частых запросов

Поведение кэша​

ПоведениеОписание
Длительность кэша5 минут (300 секунд)
Область кэшаКэшируется отдельно по идентификатору сервера
АвтообновлениеАвтоматически получает актуальный список при следующем запросе после истечения кэша
Ручное обновлениеНажмите кнопку Обнаружить в списке MCP-серверов для принудительного обновления
ПереподключениеОтключение и повторное подключение сервера очищает его кэш

Ручное обнаружение​

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

  • Инструменты (Tools) — функции, которые Agent может вызывать
  • Ресурсы (Resources) — ресурсы данных, предоставляемые сервером (файлы, таблицы баз данных и т. д.)
  • Промпты (Prompts) — шаблоны промптов, предопределённые сервером

Формат именования инструментов​

Идентификатор каждого MCP-инструмента в Agent имеет следующий формат:

mcp__<server-name>__<tool-name>

Правила именования:

  • Неалфавитно-цифровые символы в имени сервера и имени инструмента заменяются символом подчёркивания _
  • В качестве разделителей используются двойные подчёркивания __

Примеры:

Имя сервераИсходное имя инструментаИдентификатор в Agent
filesystemread_filemcp__filesystem__read_file
brave-searchbrave_web_searchmcp__brave_search__brave_web_search
githubcreate_issuemcp__github__create_issue

Режимы использования MCP​

Elftia предоставляет три режима использования MCP, управляющих доступностью инструментов в ходе беседы:

РежимОписаниеСценарий использования
Автоматический (по умолчанию)Инструменты всех активных серверов доступны автоматическиПовседневное использование; Agent выбирает инструменты самостоятельно
РучнойВыбор серверов перед каждой беседойСценарии, требующие точного контроля над набором инструментов
ОтключёнMCP-инструменты полностью отключеныПростые беседы, не требующие внешних инструментов

Автоматический режим​

Режим по умолчанию. Инструменты всех активных (isActive) MCP-серверов автоматически добавляются в список инструментов Agent. Agent самостоятельно решает, следует ли вызвать инструмент, исходя из содержания беседы.

Ручной режим​

В ручном режиме можно точно выбрать, какие MCP-серверы использовать в текущей беседе:

  1. Переключите режим MCP в настройках беседы на Ручной
  2. Отметьте нужные серверы из списка доступных
  3. В ходе беседы будут доступны только инструменты выбранных серверов

Режим «Отключён»​

Полностью отключает функциональность MCP. Agent не загружает никакие MCP-инструменты.

Адаптация формата инструментов​

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

ПровайдерФормат инструментовОписание
OpenAI / DeepSeek / китайские LLMформат function{ type: "function", function: { name, description, parameters } }
Anthropic (Claude)формат tool{ name, description, input_schema }
Google (Gemini)формат functionDeclarations{ functionDeclarations: [{ name, description, parameters }] }

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

Отображение инструментов в беседе​

Когда Agent вызывает MCP-инструмент, в UI беседы отображается специальная карточка вызова инструмента:

  • Вызов — показывает имя инструмента и переданные ему аргументы
  • Результат — отображает содержимое, возвращённое инструментом (текст, изображения и т. д.)
  • Ошибка — при сбое вызова показываются сведения об ошибке

Типы возвращаемого содержимого​

MCP-инструменты могут возвращать содержимое следующих типов:

Тип содержимогоОписание
textТекстовый результат, отображается напрямую
imageДанные изображения (Base64-кодирование), отображается как картинка
audioАудиоданные (Base64-кодирование), отображается как плеер

Таймаут вызова​

Таймаут одного вызова инструмента составляет 2 минуты (120 секунд). Если инструмент не возвращает результат за это время, вызов прерывается и возвращается ошибка таймаута.

Привязка MCP-серверов к Agents​

Можно привязать конкретные MCP-серверы к конкретным Agents для более детального распределения инструментов:

Шаги привязки​

  1. В списке MCP-серверов нажмите кнопку Управление на целевом сервере
  2. В открывшемся диалоге просмотрите список уже привязанных Agents
  3. Нажмите Добавить к Agent, чтобы раскрыть список доступных Agents
  4. Выберите Agents, которые хотите привязать

Управление привязками​

В диалоге управления вы можете:

ДействиеОписание
Просмотр привязанных AgentsПоказывает, какие Agents привязаны в данный момент
Включить/ОтключитьПереключателем управлять доступностью инструментов для конкретного Agent
Удалить привязкуНажать кнопку удаления для снятия привязки Agent
Поиск AgentsИскать и фильтровать список Agents при добавлении

Отключение отдельных инструментов​

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

  • Список disabledTools на уровне сервера содержит имена отключённых инструментов
  • Отключённые инструменты не появляются в списке инструментов Agent
  • Отключение выполняется через интерфейс обновления сервера

Управление доверием​

MCP-серверы имеют два уровня доверия:

УровеньОписаниеОтличие в поведении
Недоверенный (по умолчанию)Вновь добавленные серверы по умолчанию недоверенныеНормальное использование, но могут применяться дополнительные ограничения
ДоверенныйСерверы, явно отмеченные пользователем как надёжныеПолное доверие к вызовам инструментов

Пометка как доверенного​

Обновите свойство isTrusted сервера в управлении серверами, чтобы пометить его как доверенный. Доверенные серверы получают повышенные права при автоматическом подтверждении вызовов инструментов.

Включение и отключение серверов​

Каждый MCP-сервер имеет переключатель isActive:

  • Включён — сервер участвует в загрузке инструментов (в автоматическом режиме подключается автоматически)
  • Отключён — сервер пропускается, не участвует в загрузке инструментов и не потребляет ресурсы соединения

Отключение сервера не удаляет его конфигурацию; его можно повторно включить в любое время.

Устранение неполадок​

Вызов инструмента возвращает ошибку​

Симптом: после вызова инструмента Agent отображается сообщение об ошибке.

Решение:

  • Убедитесь, что API Key, необходимый инструменту, настроен правильно
  • Подтвердите, что аргументы инструмента соответствуют ожидаемому формату
  • Проверьте, что сервер ещё работает (для серверов Stdio)
  • Попробуйте переподключить сервер

Список инструментов пуст​

Симптом: сервер подключён, но инструменты не обнаружены.

Решение:

  • Используйте функцию Обнаружить для ручного получения списка инструментов
  • Убедитесь, что версия сервера поддерживает конечную точку tools/list
  • Проверьте журнал вывода сервера на наличие ошибок

Agent не использует доступные инструменты​

Симптом: инструменты зарегистрированы, но Agent не вызывает их в ходе беседы.

Решение:

  • Явно упомяните имя инструмента или соответствующую возможность в промпте
  • Проверьте, не установлен ли режим «Отключён»
  • Убедитесь, что описание инструмента точное, чтобы Agent мог определить, когда его использовать
  • Сократите количество доступных инструментов, чтобы избежать паралича выбора

Дальнейшие шаги​