MCP в Open WebUI: подключить локальный инструмент и проверить вызов

Что именно подключается в Open WebUI?

Нативный MCP-клиент Open WebUI доступен с версии v0.6.31 и принимает Streamable HTTP, не локальный stdio-процесс и не старый SSE URL. В административном интерфейсе нужно выбрать именно MCP (Streamable HTTP), а не OpenAPI. MCP-сервер предоставляет список функций с именами и схемами аргументов; открывшийся в чате список ещё не означает, что модель вызвала функцию. s1 s6 s7

Инструмент получает права той учётной записи, под которой он работает; администратор добавляет MCP-соединение и через Access Control ограничивает, кто сможет его включать. Обычному пользователю доступна возможность добавить собственный OpenAPI-сервер при отдельном разрешении Direct Tool Servers, но не произвольный MCP-сервер. Не путайте это с разделом Workspace Tools: сторонние Python-плагины там запускаются в процессе Open WebUI и требуют отдельного доверия к коду. s1 s2

Для задачи «локальный помощник вызывает безопасную функцию» цепочка такова: запрос в чате → локальная модель с поддержкой tool calling → Open WebUI → MCP endpoint → проверяемый ответ инструмента. Сам протокол не делает модель лучше: разработчики прямо предупреждают, что она может проигнорировать доступную функцию либо ошибиться в аргументах. Не выводите успех из правдоподобной фразы модели. s1 s2

Что подготовить до настройки?

Нужны рабочий Open WebUI версии не ниже v0.6.31, административный доступ, модель с функцией вызова инструментов и отдельный MCP Streamable HTTP endpoint, доступный из процесса Open WebUI. Начните с общей инструкции Open WebUI и проверки tool calling. Для опытов берите инструмент без доступа к рабочим файлам, ключам, почте и учётным системам. s1 s2 s7

Если Open WebUI работает в контейнере, 127.0.0.1 внутри него — не loopback хоста с вашим MCP-сервером. В документации для размещённого на хосте сервиса указан адрес host.docker.internal:<port>; фактическую доступность этого адреса из контейнера и сетевые ограничения нужно проверять на своей ОС. Не открывайте тестовый endpoint на 0.0.0.0 и в интернет только ради устранения ошибки соединения: спецификация рекомендует локальный bind на loopback и проверку Origin. Для нескольких контейнеров используйте согласованную внутреннюю сеть и проверяйте адрес сервиса именно из Open WebUI. s1 s6

Отличайте три адреса: URL Open WebUI в браузере, URL локальной модели (например, Ollama у вас на хосте) и URL MCP-сервера. Успешный ответ Ollama не подтверждает доступность MCP endpoint. Не передавайте в инструменты реальные секреты, пока не подтверждены авторизация, сетевой периметр и права пользователя. s1 s6

Как получить безопасный пробный сервер?

Если у вас уже есть собственный проверенный Streamable HTTP-сервер, используйте его точный /mcp URL и разрешённую функцию только для чтения; не переустанавливайте рабочий сервис. Для отдельного учебного опыта на Unix-подобной системе Python SDK документирует uv add "mcp[cli]", объект MCPServer, декоратор @mcp.tool() и запуск mcp.run(transport="streamable-http", port=3001). Ниже код адаптирован под безвредный ответ: он не открывает файлы и не делает сетевых запросов. Это инструкция для вашего теста по исходникам, не результат прогона Modelium. s3 s4 s8

В пустом учебном каталоге создайте проект, установите SDK и сохраните server.py. Сначала оцените зависимости по правилам своей среды: установка mcp получает пакет из пакетного индекса. Не запускайте этот код в среде с рабочими секретами. s3 s4

mkdir mcp-webui-smoke && cd mcp-webui-smoke
uv init
uv add "mcp[cli]"

import logging
from mcp.server import MCPServer

logging.basicConfig(level=logging.INFO)
mcp = MCPServer("Modelium-safe-smoke")

@mcp.tool()
def echo_marker(marker: str) -> str:
"""Return an explicit test marker without reading private data."""
logging.info("echo_marker called with marker=%s", marker)
return f"tool_called:{marker}"

if __name__ == "__main__":
mcp.run(transport="streamable-http", port=3001)

uv run python server.py

SDK в закреплённом примере поднимает endpoint http://127.0.0.1:3001/mcp. Этот вариант предназначен для Open WebUI на том же сетевом хосте; если интерфейс в Docker, не копируйте адрес 127.0.0.1 в его настройки. Чтобы подключить сервис через контейнерную сеть, нужно отдельно настроить bind, изоляцию и ограничение доступа; публичный незащищённый endpoint не подходит. Простая проверка curl -I /mcp не годится: MCP использует POST и может не поддерживать HEAD или обычный GET без сессии. s8 s6

Как добавить сервер и включить инструмент?

Администратор открывает Settings → Admin → Integrations → External Tool Servers → Add Connection, выбирает MCP (Streamable HTTP), указывает проверенный URL endpoint и подходящую авторизацию. Для локального учебного сервера без токена — None; Bearer выбирают только когда сервер действительно требует ключ и он задан. При необходимости ограничьте список функций фильтром и выдайте доступ тестовому пользователю, затем сохраните; если UI требует рестарт, выполните его в своей тестовой среде. s1

Для сервера с OAuth режимы 2.1 и Static требуют отдельной регистрации клиента, а доступ пользователя завершается в его браузере. Кнопка Check OAuth Discovery проверяет только документ авторизации: она не доказывает наличие инструментов или успешный вызов. Не ставьте OAuth-инструментом «по умолчанию» модель, пока пользователь не авторизовался: интерактивное подтверждение нельзя прозрачно провести посередине запроса модели. Если задействован OAuth, закрепите постоянный WEBUI_SECRET_KEY, иначе токены могут стать нечитаемыми после пересоздания Docker-контейнера. s1

В чате выберите локальную модель, откройте Integrations → Tools у поля ввода и явно включите только тестовую функцию. Используйте режим Native function calling; при недостаточной надёжности конкретной модели ищите проблему отдельно в модели, не называйте её молчание ошибкой MCP. Видимость функции и включённый переключатель — только предварительные признаки. s1 s2

Как проверить вызов, а не только ответ модели?

Для echo_marker отправьте в тестовом чате: «Вызови инструмент echo_marker с аргументом marker=smoke-28, покажи точный ответ инструмента. Если вызов недоступен, так и скажи». Критерий успеха: в трассе/истории исполнения инструмента есть вызов echo_marker с аргументом smoke-28, инструмент вернул tool_called:smoke-28, и ответ модели опирается на этот результат. Если ваша версия интерфейса не показывает трассу, добавьте журнал вызовов в самом доверенном MCP-сервере для теста; текст модели без записи выполнения не доказывает вызов. Это проверка маршрута на ваших данных, не бенчмарк модели. s2 s4 s7

Сначала проверяйте сетевую точку и транспорт, затем наличие функции и права пользователя, потом tool-calling модели. Повторите тест с заведомо другой меткой (smoke-29) и сравните оба аргумента и результата: заранее заученная реплика уже не сойдёт за вызов. Для корпоративных данных следующий этап — отдельная политика авторизации инструмента, подтверждение операций и контроль доступа к источникам; права входа в WebUI сами по себе не подтверждают ограничение содержимого документов в RAG. s1 s7

Если подключение не работает или нужен stdio

• Бесконечная загрузка после добавления. Проверьте тип соединения: JSON с mcpServers не вводят как OpenAPI-сервер. Восстановите настройку из Admin → Integrations и добавьте MCP-коннектор с правильным типом. s1
• Нет соединения, но OAuth discovery «зелёный». Discovery не обращается к MCP tool endpoint; отдельно проверьте URL, область видимости сервера из контейнера, требуемый Bearer/OAuth и таймаут холодного старта. s1
• Инструмент есть у администратора, но не у читателя. Проверьте Access Control коннектора и индивидуальный допуск пользователя; по умолчанию нельзя считать, что общий сервер доступен всем. s1 s2
• Функция доступна, но модель отвечает без вызова. Проверьте Native mode, достаточность контекста и качество tool calling у выбранной модели; не подменяйте это тестом «похоже, сработало». s1 s2
• У вас сервер только stdio или старый SSE. Нативное соединение Open WebUI с ним не описано. Либо используйте HTTP-версию самого сервера, либо отдельный mcpo, который публикует OpenAPI endpoint для stdio/SSE, затем подключайте его как OpenAPI, а не как нативный MCP. Этот мост — дополнительная поверхность доступа: задайте ключ и закрытую сеть, не обещайте безопасность только потому, что появился HTTP URL. s1 s5

Следующий шаг: проверить tool calling локальной модели на безвредном инструменте и сохранить фактическую трассу вызова. После этого можно выбирать конкретную задачу, runtime и железо; пока нет проверенного результата, страницу нельзя трактовать как свидетельство локального запуска Modelium. s1 s2