Это руководство объясняет, как подключать внешние серверы Model Context Protocol (MCP) к агентам Discourse AI, что позволяет использовать любого совместимого с MCP поставщика инструментов напрямую внутри ИИ-бота.
Требуемый уровень пользователя: Администратор
Что такое «Bring Your Own MCP»?
Model Context Protocol — это открытый стандарт (первоначально предложенный Anthropic), который позволяет агентам ИИ общаться с внешними серверами инструментов через стандартный интерфейс HTTP/JSON-RPC. Сервер MCP предоставляет меню «инструментов» — функций с типизированными входными данными, — которые LLM может вызывать для выполнения задач.
Discourse AI теперь выступает в роли клиента MCP. Вы регистрируете любой HTTPS-сервер MCP в панели администратора, Discourse обнаруживает доступные ему инструменты, и эти инструменты становятся полноправными участниками любого выбранного вами ИИ-агента. Писать JavaScript не нужно; инструменты определяются удаленным сервером.
Это отличается от пользовательских скриптовых инструментов, требующих написания JavaScript-кода, который выполняется внутри Discourse. С помощью MCP вы подключаете уже работающий внешний сервер.
Краткое содержание
- Регистрация сервера MCP (URL + необязательная аутентификация)
- Автоматическое обнаружение и кэширование инструментов сервера в Discourse
- Назначение сервера одному или нескольким ИИ-агентам
- При необходимости ограничение доступа к инструментам для каждого агента
- Инструменты вызываются LLM во время выполнения, маршрутизируются через Discourse к внешнему серверу
Регистрация сервера MCP
Перейдите по пути:
Администрирование → Плагины → Discourse AI → Инструменты → вкладка Серверы MCP → Новый сервер MCP
Заполните следующие поля:
| Поле | Описание |
|---|---|
| Название | Человекопонятная метка (отображается в редакторе агента и логах) |
| Описание | Назначение этого сервера (справочная информация для администратора) |
| URL | HTTPS-эндпоинт сервера MCP — должен быть публичным HTTPS-URL, без частных IP-адресов |
| Аутентификация | Один из вариантов: Без аутентификации, Учетные данные в заголовке или OAuth |
| Тайм-аут (сек) | Время ожидания Discourse для каждого запроса — по умолчанию 30, максимум 300 |
| Включено | Переключатель для временного отключения сервера без его удаления |
URL-адреса должны использовать HTTPS.
localhostи частные адреса RFC-1918 заблокированы (защита от SSRF принудительно применяется на стороне сервера).
Варианты аутентификации
Без аутентификации
Сервер доступен публично. Учетные данные не передаются.
Учетные данные в заголовке
Секретное значение вставляется в HTTP-заголовок каждого запроса.
- Сначала создайте Учетные данные в разделе Администрирование → ИИ → Учетные данные
- Выберите их в поле Учетные данные в форме сервера MCP
- Укажите имя заголовка аутентификации (по умолчанию:
Authorization) - Укажите необязательный префикс схемы аутентификации (по умолчанию:
Bearer)
Заголовок запроса, отправляемый на сервер MCP, будет выглядеть так:
Authorization: Bearer <ваше-секретное-значение>
Вы можете изменить как имя заголовка, так и схему, чтобы соответствовать любому требуемому сервером стилю аутентификации (например, X-Api-Key: <значение>, оставив схему пустой).
OAuth
Discourse реализует полный поток OAuth 2.0 + PKCE в качестве клиента MCP. Это поддерживает серверы MCP, защищающие свои инструменты с помощью OAuth.
Шаги настройки:
- Установите Аутентификацию в значение
OAuth - Выберите Регистрацию клиента:
- Документ метаданных клиента (по умолчанию) — Discourse публикует свои собственные метаданные OAuth-клиента по адресу
https://your-site.com/discourse-ai/mcp/oauth/client-metadata. Если сервер MCP поддерживает динамическую регистрацию клиентов RFC 7591, регистрация произойдет автоматически - Ручные учетные данные клиента — введите ваш заранее зарегистрированный OAuth client ID и выберите учетные данные OAuth client secret
- Документ метаданных клиента (по умолчанию) — Discourse публикует свои собственные метаданные OAuth-клиента по адресу
- При необходимости установите OAuth scopes (разделенные пробелами)
- Сохраните сервер
- Нажмите Подключить — Discourse перенаправит вас на страницу авторизации провайдера
- После авторизации вы вернетесь в панель администратора, и статус изменится на Подключено
Расширенные опции OAuth (переключите «Показать расширенные опции»):
| Опция | Назначение |
|---|---|
| Параметры авторизации OAuth | JSON-объект, объединяемый с запросом авторизации (например, {"access_type":"offline"}) |
| Параметры токена OAuth | JSON-объект, объединяемый с запросами обмена токенами |
| Требовать refresh token | Прервать подключение, если провайдер не возвращает refresh token |
Discourse автоматически обновляет access tokens перед истечением срока их действия и повторяет запросы при ошибке 401, если доступен refresh token.
Тестирование подключения
Перед назначением сервера агенту используйте кнопку Проверить подключение в форме редактора. Это немедленно инициализирует сессию MCP, вызывает tools/list и возвращает:
- Сговоренную версию протокола MCP
- Количество обнаруженных инструментов
- Имена всех инструментов
Если тест не удался, сообщение об ошибке от сервера (или индикатор тайм-аута) отображается непосредственно в интерфейсе.
Как Discourse обнаруживает инструменты
Discourse следует спецификации MCP 2025-03-26. Последовательность подключения:
Discourse → POST / { method: "initialize", params: { protocolVersion, capabilities, clientInfo } }
Сервер → { result: { protocolVersion, capabilities } } + заголовок Mcp-Session-Id
Discourse → POST / { method: "notifications/initialized" } (рукопожатие сессии завершено)
Discourse → POST / { method: "tools/list", session_id: … }
Сервер → { result: { tools: [ { name, description, inputSchema } … ] } }
Определения инструментов кэшируются на 1 час для каждого сервера. После истечения срока действия кэша фоновая задача прозрачно обновляет его. Ключ кэша уникален для каждого сайта/сервера, поэтому установки с несколькими сайтами изолированы.
Вы также можете вручную инициировать обновление, нажав Проверить подключение — это всегда получает актуальные данные.
Состояние работоспособности сервера (healthy / error) обновляется при каждом обновлении кэша.
Назначение серверов MCP ИИ-агентам
После регистрации сервера назначьте его агенту:
- Перейдите в Администрирование → Плагины → Discourse AI → Агенты и отредактируйте или создайте агента
- Прокрутите до раздела Серверы MCP (ниже раздела Обычные инструменты)
- Список показывает все включенные серверы MCP с количеством их инструментов и оценочной стоимостью токенов
- Включите сервер — теперь он доступен для этого агента
Совет: По умолчанию все инструменты с сервера доступны агенту. Строка локализации хорошо это описывает: «Выбранные серверы MCP по умолчанию предоставляют все свои инструменты. Ограничьте их для каждого агента, чтобы снизить потребление токенов и сфокусировать выбор инструментов.»
Выбор конкретных инструментов для каждого агента
Наличие десятков доступных инструментов увеличивает стоимость токенов каждого сообщения (каждое определение инструмента отправляется модели в системном промпте). Чтобы сохранить легковесность:
- В редакторе агента рядом с назначенным сервером MCP нажмите Выбрать инструменты
- В модальном окне отображаются все инструменты, которые в данный момент предоставляет сервер, с их описанием и списком параметров
- Отметьте только те инструменты, которые нужны этому агенту
- Нажмите Сохранить — агент теперь будет видеть только выбранное подмножество
Таблица связей ai_agent_mcp_servers хранит selected_tool_names как массив JSONB. Пустой массив означает «все инструменты включены».
Именование инструментов и разрешение конфликтов
Имена инструментов MCP должны быть уникальными в пределах списка инструментов одного агента (включая встроенные и пользовательские скриптовые инструменты агента). Discourse автоматически обрабатывает конфликты:
- Если два разных сервера MCP предоставляют инструмент с одинаковым именем, Discourse добавляет пространственное имя:
servername__toolname - Если встроенный инструмент Discourse и инструмент MCP имеют одинаковое имя, инструмент MCP также получает пространственное имя
- Если после добавления пространственного имени все еще возникают коллизии, добавляется числовой суффикс (
_2,_3, …)
function_name, используемая в вызове LLM, может поэтому отличаться от исходного tool_name на сервере MCP. Это обрабатывается прозрачно — класс инструмента MCP всегда хранит исходное tool_name_value отдельно и использует его при вызове сервера.
Как работают вызовы инструментов во время выполнения
Когда LLM решает использовать инструмент MCP:
- Переиспользование сессии: Discourse ищет кэшированный ID сессии MCP для этого сервера в текущем контексте бота (
context.mcp_state). Сессии создаются для каждой цепочки ответов бота и переиспользуются при вызовах инструментов к одному и тому же серверу. - Инициализация при необходимости: Если сессия не существует, выполняется новое рукопожатие
initialize+notifications/initialized. - Вызов:
POST /с{ method: "tools/call", params: { name: tool_name, arguments: params } } - Истечение срока сессии: Если сервер возвращает
404(сессия истекла), Discourse автоматически переинициализируется и повторяет запрос один раз. - Нормализация ответа: Элементы содержимого MCP типа
textконкатенируются. Элементы не-текста сериализуются в JSON.structuredContentвыводится в виде красивого JSON. - Результат ошибки: Если сервер возвращает
isError: true, бот получает сообщение об ошибке вместо результата.
Ответ сервера может быть обычным JSON или потоком SSE — Discourse обрабатывает оба варианта.
Отображение стоимости токенов
В редакторе агента для каждого назначенного сервера MCP отображается оценочное количество токенов. Оно рассчитывается с использованием токенизатора OpenAI cl100k_base, примененного к полной JSON-подписи каждого инструмента (имя + описание + схема ввода). Это приблизительная оценка — фактическая стоимость зависит от токенизатора вашего LLM.
Детализация стоимости токенов отображается, чтобы помочь вам принять обоснованное решение о том, какие серверы и инструменты назначать конкретному агенту.
Устранение неполадок
| Симптом | Что проверить |
|---|---|
| Проверка подключения завершается ошибкой по тайм-ауту | Увеличьте Тайм-аут (сек). По умолчанию 30. Если сервер медленно инициализируется, попробуйте 60–120. |
| Проверка успешна, но инструменты не отображаются в агенте | Убедитесь, что сервер Включен и что агент активирован в его разделе серверов MCP. |
| Статус OAuth показывает «Требует внимания» | Последняя ошибка OAuth отображается в форме редактора. Частые причины: истек refresh token (нажмите Переподключить), сервер вернул неожиданные scopes или URL метаданных клиента недоступен с вашего сервера. |
Имена инструментов выглядят как myserver__sometool |
Это нормально — другой инструмент (встроенный или с другого сервера) имел такое же имя. LLM автоматически видит и использует это пространственное имя. |
| Здоровье показывает «ошибка» после некоторого времени | Фоновая задача обновления не смогла достичь сервера. Проверьте /logs на вашем сайте и убедитесь, что сервер MCP доступен с хоста Discourse. |
| Инструменты перестали работать во время разговора | Истечение срока сессии. Discourse автоматически повторяет попытку один раз для каждого вызова инструмента, но если сервер постоянно перезапускается, сократите его TTL сессии или изучите логи на стороне сервера. |
Для более глубокой отладки включите доступ к транскриптам ИИ через ai_bot_debugging_allowed_groups и изучите полный журнал разговора.
Техническая справка
Детали протокола MCP
| Свойство | Значение |
|---|---|
| Версия протокола | 2025-03-26 |
| Транспорт | HTTP POST (JSON-RPC 2.0) |
| Поддержка SSE | Да (для потоковой передачи ответов tools/call) |
| Управление сессиями | HTTP-заголовок Mcp-Session-Id |
| Макс. размер тела ответа | 5 МБ |
| User-Agent клиента | Discourse AI MCP Client / <версия> |
Поддержка JSON Schema
Discourse разрешает следующие конструкции JSON Schema в определениях inputSchema инструментов перед их передачей LLM:
$ref— разрешается относительно$defs/definitionsкорневого режимаallOf— объединяются (свойства и массивы required объединяются по объединению)anyOf/oneOf— используется первая не-nullвариация
Соответствующие исходные файлы
plugins/discourse-ai/lib/mcp/client.rb— HTTP-клиент MCP (сессия, вызов, повторная попытка OAuth)plugins/discourse-ai/lib/mcp/tool_registry.rb— кэширование инструментов, разрешение конфликтовplugins/discourse-ai/lib/agents/tools/mcp.rb— класс инструмента, инкапсулирующий вызовы MCP для времени выполнения агентаplugins/discourse-ai/app/models/ai_mcp_server.rb— модель сервера, управление токенами OAuthplugins/discourse-ai/app/models/ai_agent_mcp_server.rb— выбор инструментов для каждого агентаplugins/discourse-ai/lib/mcp/oauth_flow.rb— поток OAuth 2.0 + PKCE
Связанные темы
- ИИ-бот — Пользовательские инструменты (на основе скриптов)
- Руководство по персона/агенту Discourse AI
- Discourse MCP здесь! (Discourse как MCP-сервер)
Функция Discourse в качестве MCP-сервера (discourse/discourse-mcp) является дополнением к этому: она позволяет внешним ИИ-клиентам (Claude Code, Cursor и др.) читать и записывать данные на вашем сайте Discourse. Это руководство является обратным — оно позволяет вашим ИИ-агентам Discourse вызывать внешние серверы MCP.