Перейти к основному содержимому
Открыть Markdown

Использование секретов с MCP-хостингом

Подключите секрет аккаунта к инстансу Hosted MCP по имени. При следующем развертывании Just Run разрешит секрет и добавит его переменные в окружение процесса MCP-сервера, не возвращая значения через API Hosted MCP.

В этом руководстве изменяется существующий развернутый инстанс. Его постоянный URL и клиентский bearer-токен не меняются при повторном развертывании.

Перед началом​

Вам понадобятся:

  • инстанс Hosted MCP в том же активном аккаунте, что и секрет;
  • секрет типа env с переменными, необходимыми серверу;
  • владение инстансом Hosted MCP или роль Владелец либо Администратор в организации;
  • cURL, jq и персональный токен с правами Полные для пути через REST.

Другие типы секретов нельзя подключить к Hosted MCP. Если секрет типа env еще не создан, следуйте руководству Создание и управление секретами. В организации секрет private может использовать инстанс Hosted MCP с видимостью private того же автора. Общему инстансу (org) нужен секрет org. Песочница, в которой работает сервер, наследует видимость и владельца инстанса.

Для REST задайте:

export JUSTRUN_API="https://your-just-run-host"
export JUSTRUN_PAT="your-personal-access-token"
export HOSTED_MCP_ID="your-hosted-mcp-id"
export SECRET_NAME="hosted-mcp-credentials"

В инсталляции должны быть включены возможности Hosted MCP и секретов.

Подключение через веб-интерфейс​

  1. Откройте MCP-хостинг.
  2. Нажмите значок карандаша (Изменить) у нужного инстанса.
  3. В форме найдите раздел Переменные окружения.
  4. В поле Из секретов нажмите Добавить секрет и выберите секрет типа env. Чтобы подключить несколько секретов, повторите действие.
  5. Оставьте поля переменных окружения, заданных напрямую, пустыми, если не собираетесь полностью заменить сохраненные для них значения, затем нажмите Сохранить.
  6. Дождитесь состояния нужен redeploy и нажмите значок Передеплоить у инстанса.
  7. Дождитесь состояния готов, разверните строку инстанса и нажмите Проверить соединение.

При успешной проверке интерфейс показывает зеленый результат и количество инструментов, возвращенных сервером. Форма редактирования никогда не подставляет сохраненные значения переменных окружения, заданные напрямую, или значения секретов.

Подключение через REST API​

Сначала прочитайте текущий инстанс. Сохраните исходные ссылки, чтобы после временной проверки восстановить их:

INSTANCE="$(
curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/hosted-mcp/$HOSTED_MCP_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT"
)"

ORIGINAL_REFS="$(jq -c '.secret_refs' <<<"$INSTANCE")"
NEXT_REFS="$(
jq -c --arg name "$SECRET_NAME" \
'.secret_refs + [$name] | unique' <<<"$INSTANCE"
)"

jq -n --argjson refs "$NEXT_REFS" '{secret_refs: $refs}' |
curl --fail-with-body --silent --show-error \
--request PATCH "$JUSTRUN_API/v1/hosted-mcp/$HOSTED_MCP_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data-binary @- |
jq '{id, status, secret_refs}'

secret_refs — полный новый список, а не дополнение к текущему. Для уже развернутого инстанса его изменение возвращает status: "needs_redeploy". Запустите асинхронное повторное развертывание:

curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/hosted-mcp/$HOSTED_MCP_ID/redeploy" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq '{id, status, url, secret_refs}'

Эндпоинт возвращает HTTP 202. Опрашивайте инстанс до завершения развертывания:

while :; do
INSTANCE="$(
curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/hosted-mcp/$HOSTED_MCP_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT"
)"
STATUS="$(jq -r '.status' <<<"$INSTANCE")"

if [ "$STATUS" = "ready" ]; then
break
fi
if [ "$STATUS" = "failed" ]; then
jq '{status, deploy_error}' <<<"$INSTANCE"
exit 1
fi

sleep 2
done

Проверка MCP-соединения​

Запустите ту же проверку initialize и tools/list, которую предоставляет веб-интерфейс:

TEST_RESULT="$(
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/hosted-mcp/$HOSTED_MCP_ID/test" \
--header "Authorization: Bearer $JUSTRUN_PAT"
)"

jq '{ok, tools, error}' <<<"$TEST_RESULT"
jq -e '.ok == true' >/dev/null <<<"$TEST_RESULT"

Эндпоинт проверки возвращает HTTP 200 и при успешном, и при неуспешном MCP handshake. Проверяйте ok, а не только HTTP-статус. Повторные проверки с интервалом около 10 секунд или меньше могут вернуть HTTP 429.

Приоритет и жизненный цикл​

Hosted MCP разрешает каждый указанный секрет при каждом развертывании:

  • отсутствующая ссылка или ссылка на тип, отличный от env, приводит к ошибке развертывания;
  • запись должна содержать имена переменных, которые действительно нужны серверу: одного существования ссылки недостаточно;
  • значения переменных окружения Hosted MCP, заданные напрямую, побеждают, когда тот же ключ приходит из секрета;
  • приоритет двух секретов с одинаковым ключом не является публичным контрактом, поэтому не допускайте пересечения их наборов ключей;
  • изменение или удаление секрета не меняет работающий сервис;
  • чтобы материализовать текущие значения, выполните повторное развертывание инстанса.

Каждое развертывание заново проверяет членство автора в организации и доступ к подключенным секретам. При потере права новое развертывание отклоняется до удаления старой песочницы. Уже работающий инстанс и его URL, защищенный bearer-токеном, остаются активными, пока их вручную не отключат, не удалят или не сменят токен.

Повторное развертывание заменяет песочницу, в которой работает сервер, и может прервать доступность эндпоинта, пока новое поколение не перейдет в ready. URL Hosted MCP и клиентский bearer-токен при этом сохраняются.

Восстановление исходных ссылок​

Если подключение было временной проверкой, восстановите точный список, сохраненный ранее, и снова выполните повторное развертывание:

jq -n --argjson refs "$ORIGINAL_REFS" '{secret_refs: $refs}' |
curl --fail-with-body --silent --show-error \
--request PATCH "$JUSTRUN_API/v1/hosted-mcp/$HOSTED_MCP_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data-binary @- |
jq '{id, status, secret_refs}'

curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/hosted-mcp/$HOSTED_MCP_ID/redeploy" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq '{id, status}'

Повторите описанный выше опрос статуса и убедитесь, что восстановленное поколение перешло в ready. Оставьте ссылку, если это целевая конфигурация для рабочей среды.

Устранение неполадок​

  • HTTP 403: у персонального токена права Только чтение либо у клиента нет права изменять этот инстанс Hosted MCP.
  • HTTP 503: Hosted MCP выключен либо в инсталляции не настроен ключ шифрования секретов.
  • status: "failed" и unknown secret(s): такого имени нет в активном аккаунте.
  • status: "failed" и is not an env secret: пересоздайте данные как секрет типа env и укажите новую запись.
  • ok: false: изучите error и логи инстанса; нужной переменной может не быть, даже если ссылка успешно разрешилась.
  • Ротированное значение не применилось: ротация секрета не меняет статус Hosted MCP или работающий процесс; запустите повторное развертывание явно.