MCP-сервер в production: OAuth, scopes, безопасные tools и наблюдаемость

MCP-сервер - адаптер возможностей, а не доверенный агент

Model Context Protocol описывает, как host обнаруживает и вызывает tools, получает resources и предлагает prompts. Решение о доступе, правах и выполнении остаётся за приложением. Модель формирует предложение вызова, но сервер обязан проверить identity, scope, arguments и бизнес-инварианты.

Production-готовность определяется не количеством интеграций, а тем, можно ли объяснить каждый доступ и безопасно пережить ошибочный или вредоносный вызов.

Разделите ответственность host, client и server

Выберите транспорт по границе доверия

Stdio подходит локальному server-процессу, который запускает host. Он не использует MCP HTTP authorization flow; credentials берутся из защищённого окружения процесса. Remote Streamable HTTP подходит общему cloud-сервису и требует полноценной сетевой защиты и авторизации.

Начните с threat model и data flow

Нарисуйте путь от user intent до side effect: какой текст видит модель, какой token получает server, какие upstream APIs вызываются, где сохраняются prompts, results и traces. Отметьте trust boundaries и data classifications.

OAuth защищает пользователя только при правильной audience

Для удалённого HTTP-сервера следуйте актуальной MCP authorization specification. Access token должен быть выпущен именно для MCP resource; server проверяет issuer, audience/resource, signature, expiry и scopes. Передача upstream token через MCP запрещена: confused deputy и утечка полномочий становятся вероятными.

HTTPS only
Discover protected resource and authorization metadata
Authorization Code + PKCE for public clients
Validate issuer, signature, audience/resource, expiry and scope
Use short-lived access tokens
Rotate refresh tokens where required
Never accept tokens issued for another resource
Never pass the MCP access token through to an upstream API

User delegation и machine identity - разные потоки

Если host действует от имени человека, consent и scopes привязываются к пользователю и tenant. Для server-to-server задачи применяется machine identity без имитации пользователя. Не подменяйте один режим другим ради простоты.

Scopes должны отражать узкие операции

Scope вида all делает consent бессодержательным. Разделяйте чтение, создание proposal и выполнение: orders:read, refunds:propose, refunds:execute. Каталог capabilities для запроса формируется как пересечение scopes, tenant policy и текущего состояния.

• Scope не содержит произвольный resource ID.
• Object-level authorization выполняется после scope.
• Admin capabilities находятся в отдельном consent flow.
• Изменение scopes требует нового token.
• Denied capability не раскрывается через подробную ошибку.

Tools, resources и prompts имеют разную модель контроля

Спецификация описывает tools как model-controlled, resources как application-controlled, prompts как user-controlled. Это полезная UX-модель, но host может вводить дополнительные подтверждения. Не выдавайте write-операцию как resource только для обхода approval.

Каталог capabilities фильтруется по текущим правам

Server может возвращать только tools, разрешённые представленным credentials. Это уменьшает поверхность выбора модели, однако invoke endpoint всё равно повторно проверяет доступ: каталог мог измениться, token - истечь, объект - перейти в другое состояние.

visible_capabilities = intersection of:
server deployment allowlist
∩ token scopes
∩ tenant entitlements
∩ actor roles
∩ environment policy
∩ current risk tier

Invocation repeats authorization and business validation.
Visibility is an optimization, never the final security gate.

Tool contract должен быть узким и строгим

Имя и description участвуют в выборе модели. Опишите действие, условия использования и запреты. Input schema ограничивает типы, enums, длины и число элементов; output schema возвращает только нужные поля. Identity и tenant server получает из trusted context.

Annotations - подсказка, а не security boundary

Признак read-only помогает host выбрать approval UX, но злонамеренный или ошибочный server может разметить tool неверно. Host применяет allowlist и trust policy, а backend оценивает фактический side effect. Версия каталога фиксируется в trace.

• Проверяйте annotations при review.
• Не отключайте approval только по self-declared hint для неизвестного server.
• Разделяйте trusted internal и third-party catalogs.
• Alert на неожиданное изменение tools/list.
• Показывайте пользователю server, tool и arguments.

Write-операции проходят preview, approval и execute

Сначала tool создаёт immutable proposal с diff, последствиями и expiry. Host показывает его пользователю. Execute принимает proposal ID и одноразовое approval, а не заново сгенерированные arguments.

Prompt injection приходит через любой content block

Resource, tool result и error message могут содержать текст «игнорируй правила». Server возвращает это как data с provenance, а host не повышает до system instruction. Даже успешная injection не должна дать дополнительные tools или права.

Upstream credentials остаются за server

MCP access token подтверждает доступ к MCP resource, а не ко всем backend APIs. Server использует собственную workload identity либо отдельный delegated token exchange, если он спроектирован для upstream. Credentials не возвращаются в tool result, logs или model-visible errors.

Защитите server от resource exhaustion

Один model loop способен генерировать много calls. Вводите per-user и per-tenant concurrency, rate limits, request/body caps, deadlines, pagination, output limits и bounded queues. Cancel распространяется в upstream.

Повторы безопасны только с idempotency

Transport retry, host reconnect или model retry могут повторить вызов. Для write-tool client или host передаёт idempotency key, server связывает его с actor, operation и canonical arguments и возвращает прежний результат. Ключ не переиспользуется с другими parameters.

Retry only transient failures within one deadline.
Read tools: bounded retry with backoff and jitter.
Write tools: retry only with idempotency key.
Validation, authorization and policy errors: no retry.
Unknown outcome: reconcile by operation ID before repeating.
Respect cancellation and Retry-After.

Ошибки типизируются и не раскрывают лишнее

Возвращайте stable code, retryable, safe message и correlation ID. Не включайте stack trace, SQL, token, внутренний URL или существование чужого объекта. Для unauthorized и not found часто используют одинаковый безопасный ответ.

• INVALID_ARGUMENT - исправить input.
• NOT_FOUND_OR_NOT_ALLOWED - не раскрывать ownership.
• APPROVAL_REQUIRED - вернуть proposal reference.
• CONFLICT - перечитать state.
• RATE_LIMITED - Retry-After.
• TEMPORARY_UNAVAILABLE - ограниченный retry.
• INTERNAL - correlation ID и server log.

Trace связывает protocol и бизнес-действие

Сохраняйте request/trace ID, server и protocol version, client identity, actor/tenant, capability и schema version, arguments hash, policy decisions, approval, upstream call, latency, status и idempotency outcome. Payload редактируется по data class.

trace_id, mcp_request_id
protocol_version, server_version, client_id
actor_id, tenant_id, token_issuer, scopes
tool_name, tool_schema_version, arguments_hash
policy_decisions, approval_id
upstream_operation_id, idempotency_key
latency, result_size, error_code
side_effect_status

Compatibility проверяется как матрица

Клиенты обновляют protocol и поддерживают capabilities с разной скоростью. Зафиксируйте минимальную и максимальную версии, тестируйте initialize, discovery, pagination, cancellation, auth challenges, structured content и ошибки на поддерживаемых hosts. Не включайте draft-функцию без negotiation.

Evals охватывают protocol, security и task success

Unit tests schema недостаточно. Запускайте реальные client sessions с benign, edge и adversarial задачами. Проверяйте не только ответ модели, но и вызванный tool, arguments, права и side effects.

Пошаговый rollout MCP-сервера

1. Зафиксируйте threat model и trust boundaries.
2. Начните с одного read-only tool.
3. Включите OAuth, scopes и object authz.
4. Проверьте через MCP Inspector и contract tests.
5. Запустите internal allowlist.
6. Добавьте traces, quotas и alerts.
7. Проведите adversarial evals.
8. Откройте ограниченной группе клиентов.
9. Добавляйте write только через proposal и approval.
10. Держите kill switch на server и отдельные tools.

Production-чек-лист MCP-сервера