MCP Gateway — Этап 1 (KLIP, только чтение)

Единый защищённый сервис, который позволяет авторизованным сотрудникам Energi-Up запрашивать KLIP на естественном языке через Claude, не открывая приложение. Строго только чтение.

Целевое развёртывание (PRD Q3, теперь закрыто): <gateway-hostname> -> <gateway-public-ip> (ECS-MCP, ap-southeast-5). Обратите внимание: имя хоста — mcp-gw, а не mcp.example.com, как предполагалось в документах v0.9; PRD/TSD следует обновить соответствующим образом.

Документы: PRD v0.9 · TSD v0.9 · Руководство по внедрению · Ревью дизайна · Runbook развёртывания

1. Зафиксированные версии (T-1)

Ревision спецификации MCP и версия SDK зафиксированы здесь. Если собственная документация SDK расходится с проектными документами, решающим является SDK — он определяет точный API.

Related MCP server: Snowflake MCP Server

2. Структура

src/
  core/       config, logger, db, audit, cache, rateLimit, semaphore, migrate, errors
  adapters/klip/  routes(APPENDIX A) · fields(APPENDIX A) · client(guard) · session · paginate · normalize
  tools/klip/ 9 tool definitions + shared parameter plumbing
  mcp/        server, envelope, runner
  auth/       keys, hub(OIDC RP), users, clients, tokens, provider, loginPage
  http/       app, consent(Hub + break-glass), health, origin, clientIp
migrations/   idempotent SQL (001 schema, 002 Hub OIDC)
deploy/       nginx config, backup sidecar
test/         120 tests + mock KLIP and mock Hub fixtures

Правило уровней (T-3): tools → adapters → core. Ничто не импортирует http/, кроме точки входа. Вся бизнес-нормализация находится в adapters/klip/normalize.ts, который ничего не импортирует, поэтому его можно юнит-тестировать изолированно.

3. Аутентификация — Downstream Hub OIDC

Пилотные пользователи входят через Downstream Hub (OIDC). Шлюз остаётся сервером авторизации, с которым общается Claude; Hub — один шаг внутри его собственного потока /authorize.

Мы сознательно не используем ProxyOAuthServerProvider из SDK. Проксирование передало бы Claude токен Hub, что нарушило бы привязку аудитории по RFC 8707, дало бы Claude более широкие области Hub, чем klip:read, и вывело бы выпуск токенов из-под нашего контроля, так что аварийный рубильник S8 больше не смог бы аннулировать активные сессии.

Claude ──/authorize──▶ gateway ──302──▶ Downstream Hub ──302──▶ /authorize/hub/callback
                          │                                              │
                          │        validate id_token (sig/iss/aud/nonce)  │
                          │        check the pilot ALLOWLIST              │
                          ◀──────────────────────────────────────────────┘
                          └──302 code──▶ Claude ──/token──▶ gateway token (klip:read)

Аутентификация — это не авторизация. Hub доказывает, кто этот человек; таблица users решает, может ли он пользоваться коннектором. На этапе 1 используется один общий сервисный аккаунт KLIP, поэтому каждый допущенный пользователь может читать всё, что может прочитать MCP_READONLY (ревью H8) — членство в пилоте и есть контроль доступа к данным. Аккаунт Hub, которого нет в списке, получает 403, а ограничение <= 15 обеспечивается командой user:add.

В потоке выполняются два обмена PKCE; не смешивайте их. Собственный code_challenge от Claude защищает участок Claude→шлюз (обрабатывается SDK); отдельный верификатор, который шлюз хранит на своей стороне, защищает участок шлюз→Hub.

Какой клиент Hub? Собственный шлюза — не KLIP

Зарегистрируйте новый OIDC-клиент для MCP Gateway. Не используйте повторно регистрацию KLIP в Hub, даже если KLIP уже зарегистрирован в тестовом DWS Hub.

Hub касается только одной из двух границ доверия:

Повторное использование клиента KLIP конкретным образом ломает первую границу. Шлюз проверяет aud ID-токена по своему собственному HUB_CLIENT_ID; совместное использование идентификатора клиента KLIP означает, что ID-токен, выпущенный при входе в KLIP, был бы принят шлюзом — это форма confused-deputy. Отдельные клиенты — это то, что делает две полагающиеся стороны различимыми. Это также сохраняет независимость списков разрешённых redirect-URI, секретов клиентов, графиков ротации, записей аудита Hub SSO и переключателей отключения — отключение клиента Hub коннектора не должно останавливать вход в KLIP.

Ни одно из этих изменений не требует изменений на стороне KLIP. K1–K4 не затрагиваются.

Два экземпляра Hub, две регистрации

Зарегистрируйте шлюз отдельно в каждом Hub и сопоставьте их с соответствующим KLIP:

Сопоставление проверяется при загрузке, потому что ошибка в одну сторону опасна, а не просто неаккуратна:

• KLIP_ENV=production + тестовый HUB_ISSUER → шлюз отказывается запускаться. Иначе любой, кто может создать аккаунт в тестовом Hub, получил бы доступ к реальным коммерческим данным.

• KLIP_ENV=staging + продуктовый HUB_ISSUER → предупреждение и продолжение работы.

hub:check выводит обнаруженное сопоставление, так что cutover можно проверить:

pairing:       KLIP staging  <->  Hub testing

Что требует DWS Hub (это не ванильный OIDC)

Согласно Docs/SSO-TARGET-APP-INTEGRATION.md. Четыре пункта отличаются от значений по умолчанию, которые предполагает библиотека OIDC-клиента, и три привели бы к полному отказу:

Поэтому HUB_DISCOVERY_URL настраивается явно, HUB_CLIENT_SECRET необязателен, а HUB_TOKEN_BODY по умолчанию равен json с одноразовым откатом на форму при unsupported_grant_type (с записью в лог того, что сработало, чтобы это можно было зафиксировать).

Настройка

1. Зарегистрируйте шлюз как OIDC-клиент в Hub с redirect URI <PUBLIC_URL>/authorize/hub/callback. Это публичный клиент — не запрашивайте секрет.

2. Поместите HUB_ISSUER, HUB_DISCOVERY_URL и HUB_CLIENT_ID в /opt/mcp/.env.

3. Проверьте до того, как любой пилотный пользователь попробует:

   docker compose exec -T gateway node dist/cli.js hub:check

   Это выводит redirect URI для регистрации, выполняет discovery и предупреждает, если Hub не объявляет PKCE S256. Шлюз также проверяет discovery при загрузке и сообщает о нём в /healthz как hub_oidc.

4. Добавьте пилотных пользователей (без паролей — их аутентифицирует Hub):

   docker compose exec -T gateway node dist/cli.js user:add someone@example.com "Their Name"

Аварийный аккаунт

Разрешён ровно один локальный аккаунт с паролем, для случаев, когда Hub недоступен или неправильно настроен:

docker compose exec -T gateway node dist/cli.js user:add-break-glass it-emergency@example.com

Он скрыт за раскрытием на странице входа, принуждает к смене пароля при первом использовании, и каждый вход через него аудируется с break_glass: true с высоким уровнем серьёзности. Пользователь, аутентифицированный через Hub, вообще не может использовать путь с паролем, так что отключение Hub — это не способ откатиться к паролю, который никто не задавал.

Установите BREAK_GLASS_ENABLED=false, как только путь через Hub будет подтверждён в production, чтобы полностью исключить пароль как поверхность атаки.

Опциональный групповой контроль — недоступен на DWS Hub

HUB_REQUIRED_GROUP добавляет вторую проверку по claim groups. DWS Hub не выдаёт такой claim (он объявляет только openid profile email), поэтому его установка приведёт к отказу для каждого пользователя. hub:check предупредит об этом. Разрешительный список пилота в таблице users остаётся механизмом контроля авторизации.

Вход, инициированный IdP

Hub может направить пользователя сразу на callback из плитки своей панели управления. Для коннектора так работать не может: callback существует, чтобы завершить запрос авторизации, начатый Claude, поэтому при обращении без такого запроса не остаётся ничего, для чего можно было бы выдать код. Шлюз обнаруживает это и сообщает «начните с Claude», а не завершается ошибкой «вход истёк».

4. Быстрый старт (локально)

npm ci
docker run -d --name mcpgw-devdb -e POSTGRES_DB=gateway -e POSTGRES_USER=gateway \
  -e POSTGRES_PASSWORD=devpassword -p 127.0.0.1:55432:5432 postgres:16-alpine
cp .env.example .env.dev   # then edit: PUBLIC_URL=http://localhost:8787, DATABASE_URL=...55432...
npx tsx test/fixtures/mockKlip.ts 5099 &      # mock KLIP, behaves like the real one
set -a; . ./.env.dev; set +a
npm run migrate
npx tsx src/index.ts

Создайте пилотного пользователя (работает с TTY или вводом через пайп):

printf 'a-strong-password\na-strong-password\n' | npx tsx src/cli.ts user:add you@example.com "Your Name"

5. Тесты

npm test

Mock Hub — это работающий мини-OIDC-провайдер — настоящий discovery-документ, настоящие JWKS, настоящие RS256 ID-токены и проверка PKCE для кода авторизации — со всеми настройками, необходимыми для подделки плохого токена, потому что негативные сценарии и есть суть.

Фикстура mock KLIP намеренно воспроизводит особенности реальной системы: килограммы, помеченные как MT, статусы на разных языках, incoterm за пределами стандартной четвёрки, количества со значением null, контракт с перепоставкой, limit молча усекаемый до 100, и примечание к контракту, содержащее полезную нагрузку для prompt-инъекции.

6. Развёртывание

Полная процедура для конкретного хоста, с реальным IP, именем хоста и таблицей групп безопасности: deploy/RUNBOOK.md.

# on ECS-MCP
cd /opt/mcp && git pull
docker compose build gateway && docker compose up -d
curl -fsS http://127.0.0.1:8787/healthz

Административный CLI — обратите внимание, он запускается внутри контейнера, поскольку на хосте установлен только Docker и нет Node.js:

docker compose exec -T gateway node dist/cli.js user:list
docker compose exec -T gateway node dist/cli.js audit:summary --days 7
docker compose exec -T gateway node dist/cli.js audit:export --from 2026-08-01 --to 2026-09-01 --out /tmp/audit.csv
docker compose exec -T gateway node dist/cli.js routes:verify        # probes KLIP, reports Appendix A gaps

Kill switch (S8) — целевое время: менее 5 минут:

docker compose exec -T gateway node dist/cli.js tokens:revoke-all --reason "incident 2026-xx"
docker compose stop gateway

Break-glass, если контейнер приложения нездоров:

docker compose exec -T db psql -U gateway -d gateway -c "UPDATE oauth_tokens SET revoked_at=now() WHERE revoked_at IS NULL;"

7. Приложение A — это жёсткий барьер

src/adapters/klip/routes.ts и src/adapters/klip/fields.ts содержат каждый путь KLIP, имя query-параметра, максимальный размер страницы, имя поля ответа и значение enum, от которых зависит адаптер. Каждая запись на данный момент не проверена.

Этот барьер исполняемый, а не формальный: при KLIP_ENV=production процесс отказывается запускаться, пока какой-либо маршрут не проверен. Запустите routes:verify на staging, зафиксируйте результаты, установите verified: true для каждого маршрута и enums.verified = true.

Два поля важнее остальных:

• `

9. Открытые вопросы

• K1–K4 на стороне Hub — роль MCP_READONLY, учётная запись svc-mcp, правило security-group.

• Внешняя синхронизация бэкапов и протестированное восстановление — sidecar пишет только локально.

• Реальные корпоративные egress-диапазоны в deploy/nginx/mcp.conf и включение двух закомментированных строк return 403.

• Нагрузочное тестирование на ёмкости 30 одновременных подключений.

• Регистрация клиента в тестовом Hub — собственная регистрация коннектора, с URI редиректа <PUBLIC_URL>/authorize/callback, ключами HUB_ISSUER, client_id/client_secret Hub, подтверждёнными email и группами, затем hub:check. Отдельная регистрация для продакшн-Hub — на этапе 7.

• Решить, задавать ли HUB_REQUIRED_GROUP и выключать ли BREAK_GLASS_ENABLED после подтверждения пути через Hub на проде.