Своя инсталляция

Для администраторов, разворачивающих сервис у себя.

Вход аккаунтом

Чтобы пользователи подключались адресом и входили через браузер — без ручных токенов, — сервер должен сообщать клиенту, что доступ закрыт и как авторизоваться.

Три условия:

1. Обращение к /mcp без токена возвращает 401 с заголовком WWW-Authenticate: Bearer resource_metadata="…". Ответ 200 без авторизации приводит к тому, что клиент считает сервер открытым и никогда не предложит вход.
2. Адреса /.well-known/oauth-protected-resource и /.well-known/oauth-authorization-server отдаются без авторизации. Если прокси закрывает их, клиент не прочитает описание входа.
3. В метаданных issuer совпадает с доменом инсталляции.

Проверить:

curl -i https://app.plantype.ru/.well-known/oauth-protected-resource
curl -i -X POST https://app.plantype.ru/mcp -H 'Content-Type: application/json' -d '{}'

Первая команда должна вернуть 200 с описанием, вторая — 401 с WWW-Authenticate.

Самая частая ошибка: .well-known не доходит до сервера

Она незаметна, потому что всё остальное работает. /mcp отвечает, страница подключения открывается, сервер выглядит поднятым — а подключиться нельзя ни из одного клиента. Клиент читает наш указатель на /.well-known/oauth-protected-resource, получает там ответ приложения вместо описания входа и делает единственный вывод: сервер не умеет OAuth.

Причина в том, что этот путь лежит в корне, а не под /mcp. Правило прокси, написанное для /mcp, его не покрывает — нужна отдельная строка:

location /mcp        { proxy_pass http://mcp_upstream; }
location /.well-known/ { proxy_pass http://mcp_upstream; }

Порядок важен: если / уже уходит в приложение, строку про .well-known надо поставить до неё.

Сервер проверяет это сам. Откройте /mcp в браузере — в ответе есть auth.discovery:

"discovery": { "url": "…/.well-known/oauth-protected-resource", "reachable": true }

reachable: false означает, что по этому адресу отвечает не MCP — рядом будет сказано, что именно поправить. Проверять стоит сразу после установки: иначе поломку находит первый пользователь, и находит в виде, из которого причина не следует.

Ссылки, которые ассистент даёт людям

Отвечая, ассистент прикладывает ссылку на задачу или страницу. Адрес для неё берётся из того же заголовка, по которому к серверу пришёл запрос, — поэтому за обратным прокси ссылки ведут на ваш домен, а не куда-то ещё. Отдельно настраивать это не нужно.

Настройка нужна в одном случае: приложение и /mcp живут на разных адресах. Тогда укажите адрес приложения явно, иначе ссылка приведёт человека на адрес сервера, где страницы нет:

LAYERS_BACKEND_FRONTENDBASEURL=https://app.your-domain.example

Если адрес определить неоткуда, ссылки в ответах просто не будет. Это сделано нарочно: отсутствие ссылки видно сразу, а ссылка на чужой сервер выглядит рабочей и уводит человека с его же данных.

Проверить одной командой — создайте что-нибудь и посмотрите на адрес в ответе: он должен начинаться с вашего домена.

Токены доступа

Второй способ входа — токен рабочего пространства, для скриптов и серверных интеграций. Токен показывается один раз при создании; при компрометации отзывается в настройках.

Набор инструментов

Значение задаётся при запуске и не требует пересборки.

Документация под свою инсталляцию

Сайт собирается один и тот же для любой инсталляции — домен и название сервиса задаются двумя переменными окружения:

Адрес в документации

Документация едет вместе с сервером и одна и та же во всех установках. Поэтому адрес подключения в неё не вписывается при сборке — иначе он был бы верным ровно у одной установки, а всем остальным показывал бы чужой сервер.

Адрес берётся при отдаче страницы, по порядку:

1. переменная окружения MCP_HOST контейнера — если задана, побеждает всегда;
2. адрес, по которому страницу сейчас открыли: её отдал тот самый сервер, к которому подключаются;
3. заглушка https://app.plantype.ru — если ни того, ни другого.

Задавать MCP_HOST нужно только когда сервер отвечает на несколько имён и людям надо показывать одно определённое:

MCP_HOST=https://mcp.example.com

MCP_HOST=https://mcp.example.com MCP_NAME=Acme npm run build

MCP_HOST подставится в адрес на всех страницах, MCP_NAME — в заголовок сайта и в тексты. Без MCP_NAME документация говорит нейтрально: «MCP-сервер», «ваше рабочее пространство».