MCP server: allowlist инструментов и минимальные права

Короткий ответ: разрешайте действие, а не целый сервер

Полезная allowlist описывает не абстрактное «доверенное подключение», а конкретное действие: кто может вызвать его, с какими полями, над каким проектом и с каким пределом результата. Например, чтение агрегированного статуса и создание production-задачи имеют разный риск, даже если находятся в одном MCP server. Отдельно задайте environment, tenant, максимальный объём, таймаут и необходимость подтверждения человека.

Не публикуйте все доступные методы в надежде, что клиент выберет правильный. Сначала включите один read-only инструмент на synthetic данных, затем проверьте журнал и отрицательные сценарии. Вновь появившийся метод не должен автоматически становиться доступным в production. Его добавляют в allowlist после владельца, описания входов, теста ошибок и понятного rollback. Такой процесс медленнее одного переключателя, но заметно проще для расследования и отзыва.

Минимальные права начинаются с карты ресурсов

Для каждого инструмента выпишите ресурс, операцию и границу: какой проект он видит, может ли он писать, какие поля возвращает и кто утверждает изменение. Принцип минимальных прав означает, что инструмент чтения не получает право удаления, а тестовый контур не видит production-данные. Не используйте общий технический аккаунт для всех интеграций: при ошибке невозможно быстро отключить один маршрут и понять владельца действия.

Права должны проверяться server-side для каждого вызова, а не только при открытии MCP-сессии. Пользователь, инструмент и ресурс могут меняться между сообщениями. Сверяйте внутренний actor ID, проект, тип операции и разрешённый набор параметров. Если контекст неполный, возвращайте контролируемый отказ. Не пытайтесь «угадать» нужный tenant по тексту prompt и не передавайте модели список чужих проектов ради удобства выбора.

Проверяйте аргументы независимо от вывода модели

Tool call — это предложение выполнить действие, а не готовая команда. Сервер обязан проверить JSON Schema, типы, диапазоны, идентификатор проекта и бизнес-условия. Для операций с побочным эффектом полезно требовать идемпотентный operation ID и короткое подтверждение в приложении. Строка из retrieved-документа или ответ модели не может стать SQL, shell-командой, URL для внутренней сети или правом расширить доступ.

Составьте тестовый набор из корректных и неправильных вызовов: лишнее поле, неизвестный инструмент, чужой project ID, слишком большой лимит, просроченное подтверждение и повтор той же операции. Проверяйте, что каждый случай завершается безопасно, не раскрывает внутреннюю схему и не записывает секреты в лог. Если формат поставщика или SDK меняется, повторите контрактный тест; совместимость протокола не доказывает совместимость конкретного инструмента или модели.

Секреты, сеть и журнал действий — отдельные границы

Не передавайте MCP server upstream-ключи, пароль, cookie, export из секретного хранилища или полный Authorization header. Инструмент получает только тот short-lived server-side контекст, который нужен для одной разрешённой операции. Ограничьте исходящие сети и запретите доступ к metadata endpoint, локальным сокетам и произвольным URL, если задача этого не требует. Внешний текст может просить сделать исключение; это не является полномочием.

В журнал записывайте время, внутренний actor ID, имя инструмента, project ID, результат, correlation ID и причину отказа. Не записывайте prompt, полный ответ, вложение или параметры, если они могут содержать персональные данные и секреты. Регулярно проверяйте выборку журналов и маскирование аварийных веток. Журнал нужен, чтобы связать решение с владельцем и быстро отключить доступ, а не чтобы накопить содержимое разговоров.

Запускайте через staging и измеримый rollback

Начните с отдельного тестового MCP server или feature flag, synthetic ресурса и ограниченного числа сотрудников. До rollout определите стоп-условия: неожиданный инструмент, ошибка проверки прав, увеличение отказов, несоответствие schema или подозрительный экспорт данных. Назначьте человека, который может выключить интеграцию без ожидания следующего релиза. Не включайте одновременно новые tools, новую модель и новый источник документов: иначе причина проблемы останется неясной.

После пилота сравните разрешённые и фактические вызовы, время выполнения, отказы валидации и полезность результата. Уберите неиспользуемые разрешения, уточните ограничения и задокументируйте владельца. MCP — это протокол, а не подтверждение доступа к конкретной модели или данным. RussiaAPI не заменяет проверку возможностей, политики и условий у вашей организации и поставщиков. Безопасный итог пилота может быть и таким: инструмент остаётся выключенным, пока контракт не станет яснее.

Server-side пример

Пример показывает локальную проверку на сервере. Ключи берутся только из окружения; до запуска подтвердите маршрут, model ID и параметры в текущем каталоге RussiaAPI.

const TOOL_POLICY = {
  get_project_status: { verbs: ['read'], maxItems: 20 },
  create_review_request: { verbs: ['write'], maxItems: 1 },
};

export function authorizeTool({ tool, actor, projectId, args }) {
  const policy = TOOL_POLICY[tool];
  if (!policy || !actor.projects.includes(projectId)) throw new Error('tool_not_allowed');
  if (!Number.isInteger(args.limit ?? 1) || (args.limit ?? 1) > policy.maxItems) throw new Error('invalid_input');
  return { tool, projectId, actorId: actor.id }; // no credentials or prompt in the audit event
}

Проверьте синтаксис через node --check, добавьте аутентификацию своего маршрута и негативные тесты. Не логируйте тело запроса или заголовки только ради отладки.

Границы и безопасный запуск

Это инженерное руководство, а не юридическое заключение и не инструкция по обходу законов, санкций, региональных, платёжных или платформенных ограничений. Не передавайте в тесты персональные данные, коммерческие секреты, upstream-ключи, cookie, пароли или полный заголовок Authorization. Для чувствительных данных подтвердите цель, минимизацию, срок хранения и договорные условия с ответственными специалистами.

Ключ RussiaAPI хранится только в server-side secret store. Разделяйте development, staging и production, ограничивайте доступ и журналируйте лишь безопасные метаданные. Неизвестную функцию, модель, квоту, подпись callback или поле ответа считайте неподтверждёнными, пока не проверите их в текущем разрешённом тестовом контуре.