# Внешние инструменты (MCP)

> ИИ-ассистент · Подключите MCP-сервер — и ассистент сможет вызывать его инструменты прямо в разговоре.

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

> **Совет:** Никто не сделал для вас MCP-сервер? Пропустите эту страницу — ассистент полноценен и без него. Если у вас есть API, но нет MCP-сервера, короче путь через [Data Actions](/docs/ai-assistant/data-actions).

Pommy работает по обе стороны этого стандарта, и это стоит понять, прежде чем читать дальше. **Эта страница — о стороне, где Pommy выступает клиентом**: ваш ассистент поддержки пользуется чужим сервером. Другая сторона — ваш агент программирования, использующий Pommy как сервер, — описана в разделе [Агенты программирования](/docs/coding-agents/connect-your-agent), и общего у них только название.

![Страница API Connections с окном Add MCP Server: имя сервера, URL сервера, транспорт и пользовательские заголовки](/docs/docs-mcp.png)

*API Connections — имя, адрес и заголовки, которые нужны вашему серверу. Инструменты Pommy находит сам.*

## Прежде чем начать

- **Работающий MCP-сервер, доступный из интернета**, с полным адресом эндпоинта — например, `https://tools.example.com/mcp`, вместе с путём.
- **Streamable HTTP.** Это транспорт, который поддерживает Pommy: он отправляет запрос на ваш адрес и читает ответ. Сервер, сделанный под старую схему SSE с двумя эндпоинтами, не подключится, какой бы вариант вы ни выбрали в списке.
- **То, что нужно вашему серверу, чтобы доверять вызывающей стороне**, — на практике это токен, который передаётся в заголовке.
- **Запас в тарифе.** Число MCP-серверов в проекте ограничено тарифом, а в тариф Free они не входят вовсе. При превышении лимита добавление завершится сообщением с указанием лимита.

## Добавление сервера

1. **Откройте API Connections** — **API Connections** в левом меню, затем **Add MCP Server**.
2. **Задайте имя и вставьте адрес** — **Имя** нужно только вам — достаточно «Order API». **Server URL** — эндпоинт, указанный в документации вашего сервера, вместе с путём. **Transport** оставьте на **Streamable HTTP**.
3. **Добавьте нужные заголовки** — В **Custom Headers** можно указать сколько угодно пар «имя/значение», и Pommy отправляет их с каждым запросом, — обычно это заголовок `Authorization` с bearer-токеном. Отдельного поля для токена нет: аутентификация делается через заголовок. Значения скрыты, иконка глаза их показывает.
4. **Добавьте и найдите инструменты** — Pommy сразу подключается и спрашивает сервер, что тот умеет. Откройте новую строку — там будут найденные инструменты с описаниями, которые дал им сервер. Пустой список означает, что сервер недоступен или не предоставляет инструментов.
5. **Отдайте его ассистенту** — Новый сервер пока не привязан ни к одному ассистенту, так что для ваших клиентов ничего не изменилось. Это делается в следующем разделе.

> **Внимание:** **Внутренние адреса не принимаются.** Pommy обращается к вашему серверу со своих серверов, а не изнутри вашей сети, поэтому адрес должен быть доступен из интернета. Сохранение блокируется для `localhost` и `127.x`, частных диапазонов `10.x`, `172.16–172.31.x` и `192.168.x`, link-local `169.254.x`, адреса облачных метаданных и их аналогов в IPv6 — вы увидите **Invalid MCP server URL** и причину. Сервер на вашем компьютере или в офисной сети нужно опубликовать или пробросить через туннель на публичный адрес, прежде чем Pommy сможет им пользоваться.

## Как включить инструменты для ассистента

Инструменты включаются **для каждого сервера и каждого ассистента отдельно**. Откройте **AI Agent**, отредактируйте ассистента и перейдите на шаг **MCP Tools**: там перечислены серверы проекта с индикатором состояния и числом инструментов. Отметьте те, которыми может пользоваться этот ассистент, и сохраните.

Отмеченный сервер даёт ассистенту **все** свои инструменты — переключателя для отдельного инструмента нет. Если ассистенту нужны только некоторые инструменты, вынесите их на второй сервер и подключите его.

Чтобы инструмент попал в разговор, должны быть включены два переключателя: собственный переключатель **Active** сервера на странице API Connections (кнопка паузы в его строке) и отметка на этом шаге. Пауза сервера сразу убирает его инструменты у всех ассистентов, а привязки сохраняются до повторного включения.

## Что сообщается ассистенту

Для каждого инструмента ассистент получает **имя**, **описание** и список параметров ровно в том виде, в каком их сообщает ваш сервер, — Pommy не добавляет своих пояснений. Значит, описание на вашем сервере — единственная инструкция о том, когда использовать инструмент. Пишите его как фразу о ситуации («Возвращает текущий статус заказа по номеру заказа»), а не как справочник по API.

Результат уходит ассистенту, а не клиенту: ассистент читает его и пишет ответ своими словами. Ваша команда во время разговора видит в Agent console сам вызов, его результат и длительность.

Имена должны быть уникальными. Инструмент с таким же именем, как у встроенных инструментов Pommy, — `search_knowledge_base`, `book_calendar_appointment`, `transfer_to_human` и других, — молча отбрасывается, а одинаковые имена инструментов на двух подключённых серверах ассистент не различает. Если сомневаетесь, добавьте к своим именам префикс.

> **Внимание:** Инструмент, который может вызывать ассистент, он может вызывать **от имени клиента** — с учётными данными, которые вы дали серверу, и без чьего-либо подтверждения. Начните с инструментов только для чтения и не открывайте ничего, что записывает, возвращает деньги, отменяет или удаляет, пока не убедитесь, что читающие работают как надо. И учтите: токен в ваших заголовках одинаков для всех посетителей — ваш сервер не отличит одного клиента от другого, поэтому ни один инструмент здесь не должен возвращать персональные данные только по идентификатору. Для ответов, относящихся к конкретному клиенту, используйте [Data Actions](/docs/ai-assistant/data-actions): там группа может требовать подтверждённого посетителя.

## Наблюдение за сервером

В списке API Connections у каждого сервера своя строка: имя с индикатором состояния, адрес, транспорт и число инструментов, статус работоспособности и дата последней проверки. Нажмите на строку, чтобы открыть сервер: заголовки (их можно редактировать), ассистенты, которые его используют, полный список найденных инструментов и четыре действия.

- **Refresh Tools** — снова спрашивает сервер, что он умеет, и заменяет сохранённый список. Только так список и обновляется: автоматического повторного поиска по расписанию нет, так что инструмент, добавленный на вашей стороне, остаётся невидимым для Pommy, пока вы не нажмёте эту кнопку.
- **Health Check** — быстрая проверка «отвечаешь ли ты». О том, работает ли отдельный инструмент, она ничего не говорит.
- **Pause** — убирает инструменты сервера из всех разговоров, ничего не удаляя.
- **Delete** — удаляет сервер и освобождает место в тарифе.

**Healthy** означает, что последняя проверка достучалась до сервера и нашла инструменты. **Unhealthy** — что она вернулась пустой или завершилась ошибкой. **Unknown** — что проверок ещё не было. Подробнее статус не бывает: если что-то не так, причину нужно искать на стороне вашего сервера, в его собственных логах.

## Если что-то не работает

### Я добавил сервер, но ассистент никогда не вызывает его инструменты.

Проверьте две вещи по порядку. Отмечен ли сервер на шаге MCP Tools у этого ассистента? Только что добавленный сервер не принадлежит ни одному ассистенту. Если отмечен, прочитайте описание инструмента глазами ассистента: если из него прямо не следует, на какой вопрос отвечает инструмент, ассистент к нему не обратится.

### Число инструментов упало до нуля.

Обновление заменяет сохранённый список тем, что ответил сервер, — а недоступный сервер не отвечает ничем. Инструменты вернутся при следующем успешном обновлении, а до тех пор ассистент работает без них.

### Я изменил адрес или токен, но ничего не поменялось.

Редактирование строки меняет то, что показывает страница, но ассистент продолжает использовать подключение, созданное при добавлении сервера. Удалите сервер и добавьте его заново с новыми значениями.

### Добавление сервера завершилось ошибкой «Invalid MCP server URL».

Адрес указывает на что-то внутреннее — localhost, диапазон частной сети или link-local. Pommy обращается из интернета и такие адреса отклоняет. Опубликуйте сервер на публичном адресе или пробросьте его туда через туннель.

### Видит ли клиент, что вернул инструмент?

Нет. Результат получает ассистент и отвечает своими словами; сырой результат в чате никогда не появляется. Ваша команда может увидеть его в Agent console.

---

Читать эту страницу на сайте: [Внешние инструменты (MCP)](/ru/docs/ai-assistant/external-tools-mcp)
