ChatGPT и локальные MCP-клиенты

Локальное подключение

Установленное приложение на той же машине использует http://127.0.0.1:38182/mcp/<project-token> с авторизацией проекта. Tailscale не нужен. Владелец проверил локально установленное приложение Qwen Studio; это не подтверждает работу веб-версии Qwen Studio или всех других клиентов.

На другой машине localhost указывает на неё саму. Нужны доступный адрес MCPBox и настройка слушателя либо подходящий прокси.

Облачный ChatGPT

Для прямого удалённого подключения нужен публичный HTTPS-адрес проекта. Для локальной установки рекомендуем Tailscale Funnel; готовый HTTPS reverse proxy тоже подходит. Панель управления оставьте приватной.

На машине MCPBox, после включения необходимых возможностей Funnel в Tailscale:

tailscale funnel 38182

К напечатанному HTTPS URL добавьте /mcp/<project-token>. Публичному адресу не добавляйте :38182. Оставьте MCPBox и команду Funnel работающими. tailscale funnel status проверяет публикацию, tailscale funnel 38182 off отключает её. Funnel публичный и не заменяет авторизацию MCPBox. См. справочник команд Tailscale.

Настройте публичный origin

Получив публичный HTTPS-адрес, задайте MCPBOX_PUBLIC_MCP_URL=https://mcp.example.com в окружении службы MCPBox, заменив пример своим origin, и перезапустите MCPBox. Для systemd добавьте Environment="MCPBOX_PUBLIC_MCP_URL=https://mcp.example.com" в override службы. Не включайте /mcp/<project-token> в эту переменную.

Направляйте /mcp/, /oauth/ и /.well-known/ на MCP listener с сохранением путей. Если прокси или туннель использует отдельные правила для путей, проверьте, что префиксы не обрезаются. OAuth-маршруты относятся к порту 38182, а не к административному 38181.

Проверьте, что https://mcp.example.com/.well-known/oauth-authorization-server возвращает метаданные с публичным HTTPS origin. Запрос к защищённому MCP без учётных данных должен содержать в WWW-Authenticate публичный URL resource_metadata конкретного проекта. URL проекта в интерфейсе и при копировании тоже должен использовать этот origin независимо от адреса админки. См. конфигурацию.

OAuth проекта

1. Включите bearer-аутентификацию проекта MCPBox и проверьте доступность HTTPS.
2. Начните создание удалённого MCP-приложения/подключения в ChatGPT. Доступность и названия экранов зависят от аккаунта и workspace.
3. Скопируйте точный redirect URL из текущего подключения. Создайте в MCPBox именованный OAuth-клиент проекта с этим адресом.
4. Если запрошены заранее зарегистрированные учётные данные, client ID — имя подключения MCPBox, client secret — его раскрытый токен. Сохраняйте текущий процесс настройки открытым.
5. Завершите авторизацию и обнаружение инструментов, выполните безопасный запрос чтения и проверьте Логи MCPBox.

MCPBox использует заранее заданные клиенты и authorization-code/PKCE, а не динамическую регистрацию. OIDC панели — отдельный механизм. Протокол со стороны клиента описан в официальной документации OpenAI.

Диагностика

• Неверный публичный адрес или OAuth discovery возвращает 404: проверьте MCPBOX_PUBLIC_MCP_URL в окружении службы и направьте /.well-known/ и /oauth/ на MCP-порт с сохранением путей. Отдельный порт админки не обслуживает эти маршруты.
• redirect_uri_mismatch: пересоздайте именованный клиент с callback текущей настройки; новый процесс настройки может изменить адрес.
• Вход успешен, инструменты не обнаружены: проверьте запущенный бинарник, endpoint, схемы инструментов и маршруты прокси. Успех OAuth не подтверждает обнаружение инструментов.
• Skills не видны: пакет нужно скачать и подключить установленную версию именно к этому проекту. Обновите кэш инструментов клиента. Вызывать list_skills на каждом сообщении не требуется.
• Файлы: путь или вложение локального клиента автоматически не передаётся MCPBox. Для запуска нужны реальные байты в задании на сервере: Skills.

Владелец проверил авторизацию ChatGPT и обнаружение/чтение инструкций Skills. Эта проверка не включала выполнение сторонних скриптов навыков.