ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Универсальный MCP-прокси с централизованной авторизацией и self-service подключением MCP-серверов
КОД: TBD-MCP-PROXY
КОМПОНЕНТЫ: [frontend] [backend] [api] [db] [infra]
СТАТУС: СОГЛАСОВАНИЕ

ПРЕДПОСЫЛКИ
- В организации существует доверенный источник идентификации пользователя, который выпускает подписанный JWT с полями `sub`, `email`, `employee_id`, `login`, `exp`, `iss`, `aud`.
- Агент или оператор, от имени которого выполняется запрос, аутентифицируется в прокси отдельным машинным токеном или API-ключом.
- Для каждой внешней системы определен поддерживаемый способ авторизации: `oauth_token_exchange`, `oauth_refresh_token`, `login_password`, `api_token`, `service_jwt_exchange`.
- Все секреты хранятся во внешнем защищенном хранилище секретов; база данных не хранит пароли и токены в открытом виде.
- Поддерживаемые внешние MCP-серверы доступны по `Streamable HTTP` как основному транспорту. Для legacy MCP по `HTTP+SSE` или `stdio` используется адаптер-обертка со стороны платформы.
- Для коробочных систем доступны или могут быть реализованы адаптеры выпуска/обновления пользовательских токенов без патча самих MCP-серверов.
- Для self-service публикации новых MCP-серверов доступен UI и публичный API для владельцев серверов.
- Код Jira для задачи на момент подготовки документа не предоставлен и должен быть заменен перед утверждением ТЗ.

ЦЕЛЬ
- Обеспечить единый MCP-прокси, через который агенты вызывают любые подключенные MCP-серверы от имени конкретного пользователя, а система автоматически валидирует агента, определяет пользователя, получает или обновляет допустимые для целевой системы учетные данные, проксирует запрос и логирует все действия без ручного участия сторонних подразделений.

ФУНКЦИОНАЛЬНЫЕ ТРЕБОВАНИЯ
1) Система должна предоставлять единый внешний MCP endpoint для агентов и операторских сервисов.
2) Система должна принимать два независимых контекста безопасности: идентификатор агента и подписанное утверждение пользователя.
3) Система должна валидировать подлинность агента, статус его ключа, допустимые окружения и список разрешенных MCP-серверов.
4) Система должна валидировать подпись, срок жизни, аудиторию и issuer пользовательского JWT.
5) Система должна сопоставлять пользователя из JWT с внутренним профилем и учетными данными во внешних системах.
6) Система должна по коду целевого MCP-сервера определять транспорт, endpoint, владельца, политику авторизации, поддерживаемые инструменты и статус публикации.
7) Система должна автоматически использовать существующие пользовательские токены или выпускать новые через настроенный auth adapter.
8) Система должна обновлять истекшие токены без участия конечного пользователя, если это поддерживается конкретной системой.
9) Система не должна повышать полномочия пользователя и должна вызывать внешний MCP только в разрешенном для данного пользователя контексте.
10) Система должна поддерживать self-service регистрацию нового MCP-сервера через API и UI без заявок в сторонние подразделения.
11) Система должна выполнять автоматическую валидацию нового MCP-сервера: доступность endpoint, TLS, успешный `initialize`, получение списка инструментов, проверка политики авторизации.
12) Система должна публиковать в каталоге только серверы в статусе `active`.
13) Система должна вести каталог MCP-серверов и инструментов с фильтрацией по системе, владельцу, тегам, типу авторизации и статусу.
14) Система должна предоставлять API поиска инструментов для внешнего маршрутизатора интентов или для агентской платформы.
15) Система должна поддерживать коробочные MCP для Jira, Wiki, GitLab, Figma и иных систем при условии, что они принимают логин/пароль, токен, API key или результат token exchange.
16) Система должна логировать каждый входящий и исходящий вызов с привязкой к агенту, пользователю, MCP-серверу, инструменту, trace id и результату.
17) Система должна хранить отдельный аудит административных действий: регистрация сервера, смена конфигурации, деактивация, ротация секретов.
18) Система должна предоставлять статус здоровья MCP-сервера и статус последней синхронизации списка инструментов.
19) Система должна помечать сервер признаком `maintenance_status=abandoned`, если по настроенной политике у upstream-решения отсутствуют обновления более 90 календарных дней и последний commit старше 14 календарных дней; данный признак является предупреждением, но не блокирует вызовы автоматически.
20) Система должна поддерживать versioned-конфигурацию MCP-сервера, чтобы изменение авторизации или endpoint не ломало уже активные сессии.
21) Система должна поддерживать прозрачное изменение формата аутентификации между агентом и прокси без модификации коробочных MCP-серверов.
22) Система должна поддерживать stateful MCP-сессии и отображение `proxy session -> upstream session`.
23) Система должна поддерживать принудительное завершение сессии агентом или администратором.
24) Система должна скрывать от клиентов любые учетные данные, секреты и внутренние endpoint внешних систем, которые не требуются для вызова MCP.

НЕФУНКЦИОНАЛЬНЫЕ ТРЕБОВАНИЯ
- Емкость решения: не менее 2000 зарегистрированных агентских ключей и не менее 500 одновременно активных MCP-сессий.
- Производительность каталога: `GET /api/v1/catalog/*` с p95 не более 300 мс без учета внешнего полнотекстового движка.
- Производительность прокси: добавленная латентность прокси относительно прямого вызова внешнего MCP не более 150 мс p95 при наличии валидного токена в кэше.
- Производительность авторизации: получение токена из кэша не более 100 мс p95; выпуск или refresh токена через auth adapter не более 3 секунд p95, если целевая система отвечает штатно.
- Масштабируемость: backend-прокси должен масштабироваться горизонтально; состояние долгоживущих сессий и кэшей не должно быть привязано к одному экземпляру.
- Надежность: при отказе одного инстанса активные stateful-сессии должны восстанавливаться через общий session store или пересоздаваться с контролируемой ошибкой `session_expired`.
- Доступность: целевой SLA сервиса прокси не ниже 99.5% в месяц без учета недоступности внешних коробочных систем.
- Безопасность: все внешние и внутренние HTTP-взаимодействия только по TLS 1.2+; секреты шифруются в покое через KMS/Vault; в логах запрещено хранить токены, пароли, refresh token и персональные секреты.
- Изоляция прав: права определяются только комбинацией `agent policy + user identity + server policy`; прокси не имеет права выполнять запросы "от себя", если сервер не помечен как `service_account_allowed=true`.
- Совместимость со стандартом: новый remote MCP публикуется по `Streamable HTTP`; поддержка `HTTP+SSE` допускается только в режиме обратной совместимости через адаптер.
- Наблюдаемость: должны публиковаться метрики `request_total`, `request_duration`, `auth_resolve_duration`, `token_refresh_total`, `upstream_4xx_total`, `upstream_5xx_total`, `session_active`, `catalog_sync_status`.
- Аудит: хранение аудита не менее 365 дней.
- Резервирование: конфигурация MCP-серверов и политики авторизации должны входить в стандартную схему резервного копирования.

АЛГОРИТМ РАБОТЫ
1) Операторский сервис или агент получает от доверенного IdP подписанный JWT пользователя.
2) Агент определяет подходящий MCP-сервер через каталог или через внешний маршрутизатор интентов, использующий API каталога прокси.
3) Агент отправляет MCP `initialize` или последующий JSON-RPC запрос в прокси по endpoint целевого сервера.
4) Агент передает в HTTP-заголовках:
   `Authorization: Bearer <agent_access_token>`
   `X-User-Assertion: <signed_user_jwt>`
   `MCP-Protocol-Version: <negotiated_version>`
   `X-Request-Id: <uuid>`
5) Прокси проверяет токен агента, статус ключа, список разрешенных серверов и окружение.
6) Прокси проверяет подпись и срок действия `X-User-Assertion`, затем извлекает `sub`, `employee_id`, `login`, `groups`.
7) Прокси загружает конфигурацию MCP-сервера по `server_code`, проверяет, что сервер активен и не заблокирован политикой безопасности.
8) Прокси проверяет наличие существующей proxy-session. Если это `initialize`, создается новая proxy-session; если это последующий вызов, проверяется валидность `MCP-Session-Id`.
9) Прокси определяет `auth_policy` сервера и запрашивает credential broker на получение действующего credential context для пары `user + external_system + scope`.
10) Credential broker ищет действующий токен или credential binding в кэше и защищенном хранилище.
11) Если credential найден и валиден, broker возвращает способ инъекции: заголовок, query, body field или secure side-channel к upstream-коннектору.
12) Если credential отсутствует или истек, broker выбирает auth adapter согласно `auth_policy`.
13) Auth adapter выполняет один из сценариев:
14) Для `service_jwt_exchange` принимает пользовательский JWT, преобразует его в token grant для внешней системы и получает пользовательский access token.
15) Для `oauth_refresh_token` использует сохраненный refresh token и получает новый access token.
16) Для `login_password` извлекает логин/пароль пользователя из хранилища секретов и получает session token целевой системы.
17) Для `api_token` извлекает сохраненный персональный API token и возвращает его без дополнительного обмена.
18) Если нужный сценарий авторизации невозможен без интерактивного участия пользователя, broker возвращает статус `auth_bootstrap_required`.
19) Прокси формирует upstream-request к коробочному MCP-серверу.
20) Если upstream MCP работает по `Streamable HTTP`, прокси открывает или переиспользует upstream-session и передает JSON-RPC сообщение.
21) Если upstream MCP является legacy-сервером, прокси обращается к platform adapter, который конвертирует вызов в необходимый формат взаимодействия.
22) Прокси добавляет только те credential-атрибуты, которые ожидает конкретный upstream MCP или внешний коннектор, и не передает агентский токен дальше по цепочке.
23) Коробочный MCP использует полученный credential context для обращения во внешнюю систему и формирует ответ.
24) Прокси принимает ответ, удаляет секреты и технические заголовки, которые не должны видеть клиенты.
25) Прокси записывает аудит вызова, технические метрики и финальный статус.
26) Прокси возвращает агенту JSON-RPC результат или MCP-совместимую ошибку.
27) При закрытии агентом сессии прокси отправляет `DELETE` в upstream MCP, снимает session mapping и помечает proxy-session как `closed`.

АЛГОРИТМ SELF-SERVICE ПОДКЛЮЧЕНИЯ НОВОГО MCP-СЕРВЕРА
1) Владелец MCP-сервера открывает UI или вызывает `POST /api/v1/servers`.
2) Владелец передает базовую карточку сервера: код, название, описание, owner, endpoint, transport, тип авторизации, поддерживаемые системы, теги.
3) Система создает запись сервера в статусе `draft`.
4) Владелец указывает `auth_policy` и связывает сервер с существующим `auth_adapter`.
5) Система запускает автоматическую валидацию endpoint, TLS-сертификата, `initialize`, `tools/list`, совместимости версии MCP и допустимости схемы авторизации.
6) При успехе система синхронизирует список инструментов, вычисляет health baseline и переводит сервер в статус `active`.
7) При ошибке сервер переводится в статус `validation_failed`, а владельцу возвращается список причин.
8) После активации сервер попадает в каталог и становится доступен агентам согласно policy rules.

АЛГОРИТМ ПОИСКА MCP/ИНСТРУМЕНТА
1) Агентская платформа или отдельный роутер вызывает `GET /api/v1/catalog/tools/search`.
2) Прокси фильтрует результаты по доступам агента и пользователя, чтобы не возвращать заведомо недоступные инструменты.
3) Поиск выполняется по названию, описанию, тегам, системе, owner и дополнительному полю `intent_text`.
4) При наличии отдельного intent router прокси возвращает нормализованный список кандидатов и их metadata, а окончательный выбор остается на стороне роутера.

ВЕТВЛЕНИЯ / ОШИБКИ
- Если отсутствует `Authorization` или токен агента невалиден, вернуть `401 agent_unauthorized`.
- Если отсутствует `X-User-Assertion`, вернуть `400 user_assertion_missing`.
- Если пользовательский JWT не проходит проверку подписи, срока жизни, аудитории или issuer, вернуть `401 user_assertion_invalid`.
- Если сервер не найден или находится не в статусе `active`, вернуть `404 server_not_available`.
- Если агент не имеет доступа к серверу, вернуть `403 agent_access_denied`.
- Если пользователь не имеет сопоставления с целевой системой, вернуть `403 user_mapping_missing`.
- Если для сервера отсутствует настроенный auth adapter, вернуть `500 auth_adapter_not_configured`.
- Если credential broker не смог получить токен без интерактивного шага, вернуть `409 auth_bootstrap_required`.
- Если upstream MCP возвращает `401` и запрос относится к безопасным операциям `initialize`, `tools/list`, `resources/list`, `resources/read`, `prompts/list` или к tool с `readOnlyHint=true`, прокси выполняет не более одного refresh token и один повтор запроса.
- Если upstream MCP возвращает `401` на потенциально изменяющий `tools/call` без `readOnlyHint=true`, прокси не делает автоматический повтор и возвращает `502 upstream_auth_failed` с причиной `retry_not_safe`.
- Если не передан `MCP-Session-Id` для stateful-сессии после `initialize`, вернуть `400 session_id_missing`.
- Если `MCP-Session-Id` не найден или истек, вернуть `404 session_expired`.
- Если валидация конфигурации нового сервера не прошла, сервер остается в `validation_failed`, а API возвращает `422 validation_error` с перечнем ошибок.
- Если внешний auth adapter или коробочная система недоступны, выполнить до 2 повторов с экспоненциальной задержкой 200 мс и 1000 мс только для безопасных операций чтения.
- Если превышен общий таймаут прокси на вызов upstream MCP, вернуть `504 upstream_timeout`.
- Если превышен лимит частоты по агентскому ключу, вернуть `429 rate_limited`.
- Если журнал аудита недоступен, основной вызов не блокируется, но событие пишется в отказоустойчивую очередь `audit_dlq`.

ИНТЕРФЕЙСЫ

1. Внешний MCP endpoint прокси

Метод: `POST /mcp/{server_code}`
Назначение: единая точка входа для JSON-RPC сообщений MCP по `Streamable HTTP`.
Аутентификация:
- `Authorization: Bearer <agent_access_token>`
- `X-User-Assertion: <signed_user_jwt>`
- `MCP-Protocol-Version: <version>`
- `MCP-Session-Id: <proxy_session_id>` для всех запросов после `initialize`
- `X-Request-Id: <uuid>` опционально, если не передан, генерируется прокси

Пример `initialize`:
```http
POST /mcp/jira-prod HTTP/1.1
Authorization: Bearer eyJhbGciOi...
X-User-Assertion: eyJhbGciOi...
MCP-Protocol-Version: 2025-11-25
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "finam-agent",
      "version": "1.0.0"
    }
  }
}
```

Пример успешного ответа:
```http
HTTP/1.1 200 OK
Content-Type: application/json
MCP-Session-Id: ps_01HRJ1K9S3Y7N9FJ4F6M

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "jira-prod-via-proxy",
      "version": "1.3.0"
    }
  }
}
```

Пример вызова `tools/call`:
```http
POST /mcp/jira-prod HTTP/1.1
Authorization: Bearer eyJhbGciOi...
X-User-Assertion: eyJhbGciOi...
MCP-Protocol-Version: 2025-11-25
MCP-Session-Id: ps_01HRJ1K9S3Y7N9FJ4F6M
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "42",
  "method": "tools/call",
  "params": {
    "name": "jira_get_issue",
    "arguments": {
      "issueKey": "AITECH-123"
    }
  }
}
```

Стандартный формат ошибки:
```json
{
  "jsonrpc": "2.0",
  "id": "42",
  "error": {
    "code": -32001,
    "message": "upstream_auth_failed",
    "data": {
      "requestId": "8a0f8a86-b8c5-4bf6-a0e8-0fb9d8f423ef",
      "reason": "retry_not_safe"
    }
  }
}
```

2. Завершение MCP-сессии

Метод: `DELETE /mcp/{server_code}`
Назначение: завершить proxy-session и соответствующую upstream-session.
Заголовки:
- `Authorization: Bearer <agent_access_token>`
- `MCP-Session-Id: <proxy_session_id>`
- `X-User-Assertion: <signed_user_jwt>`

Успешный ответ:
```http
HTTP/1.1 204 No Content
```

3. Каталог MCP-серверов

Метод: `GET /api/v1/catalog/servers`
Назначение: получить список доступных серверов.
Параметры:
- `system`
- `tag`
- `owner`
- `status`
- `page`
- `page_size`

Ответ:
```json
{
  "items": [
    {
      "code": "jira-prod",
      "name": "Jira Production",
      "status": "active",
      "transport": "streamable_http",
      "authPolicy": "jira-user-token",
      "systems": ["jira"],
      "tags": ["issues", "project-management"],
      "maintenanceStatus": "healthy"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}
```

4. Поиск инструментов

Метод: `GET /api/v1/catalog/tools/search`
Назначение: поиск кандидатов для маршрутизации по каталогу.
Параметры:
- `q` строка поиска
- `intent` исходная фраза пользователя
- `system`
- `tag`
- `limit`

Ответ:
```json
{
  "items": [
    {
      "serverCode": "jira-prod",
      "toolName": "jira_get_issue",
      "title": "Получить задачу Jira",
      "description": "Чтение карточки задачи по ключу",
      "readOnlyHint": true,
      "score": 0.93
    }
  ]
}
```

5. Регистрация нового MCP-сервера

Метод: `POST /api/v1/servers`
Назначение: self-service публикация новой интеграции владельцем MCP.
Аутентификация: `Authorization: Bearer <publisher_access_token>`

Тело запроса:
```json
{
  "code": "gitlab-prod",
  "name": "GitLab Production MCP",
  "description": "Коробочный MCP для GitLab",
  "ownerLogin": "baxenov",
  "endpointUrl": "https://gitlab-mcp.example.ru/mcp",
  "transport": "streamable_http",
  "legacyMode": "none",
  "systemCodes": ["gitlab"],
  "tags": ["git", "repository", "ci"],
  "authPolicy": {
    "code": "gitlab-user-token",
    "grantType": "service_jwt_exchange",
    "scopes": ["read_repository", "read_api"],
    "injectMode": "authorization_header"
  },
  "healthcheck": {
    "enabled": true,
    "intervalSec": 60
  }
}
```

Ответ:
```json
{
  "serverId": "srv_01HRJ2P0M6M8C12K8QKQ",
  "status": "draft",
  "validationStatus": "scheduled"
}
```

6. Обновление конфигурации MCP-сервера

Метод: `PATCH /api/v1/servers/{server_id}`
Назначение: частичное обновление метаданных, endpoint, owner, тегов, health policy.

7. Запуск валидации MCP-сервера

Метод: `POST /api/v1/servers/{server_id}/validate`
Назначение: принудительный прогон валидации и синхронизации инструментов.

Ответ:
```json
{
  "status": "validation_running",
  "jobId": "job_01HRJ2VQ0WQ9D5FZNV3D"
}
```

8. Получение статуса валидации

Метод: `GET /api/v1/servers/{server_id}/validation`

Ответ:
```json
{
  "status": "validation_failed",
  "errors": [
    {
      "code": "initialize_failed",
      "message": "MCP initialize returned 401"
    }
  ],
  "lastCheckedAt": "2026-04-06T08:15:00Z"
}
```

9. Внутренний API credential broker

Метод: `POST /internal/v1/credentials/resolve`
Назначение: внутренний контракт между прокси и модулем разрешения credential context.

Тело запроса:
```json
{
  "requestId": "8a0f8a86-b8c5-4bf6-a0e8-0fb9d8f423ef",
  "serverCode": "jira-prod",
  "systemCode": "jira",
  "user": {
    "sub": "1f9b4f03",
    "login": "iivanov",
    "employeeId": "123456"
  },
  "agent": {
    "agentId": "agent-legal-assistant",
    "environment": "prod"
  },
  "grantType": "service_jwt_exchange",
  "requestedScopes": ["read:issue", "read:comment"],
  "userAssertionJwt": "eyJhbGciOi..."
}
```

Ответ:
```json
{
  "status": "resolved",
  "credentialType": "bearer",
  "injectMode": "authorization_header",
  "headerName": "Authorization",
  "secretRef": "vault://mcp/jira/iivanov/token/2026-04-06T08:15:00Z",
  "expiresAt": "2026-04-06T09:15:00Z",
  "refreshAfter": "2026-04-06T09:05:00Z",
  "subjectLogin": "iivanov"
}
```

10. Внутренний API синхронизации каталога инструментов

Метод: `POST /internal/v1/catalog/sync-tools`
Назначение: синхронизировать `tools/list` из upstream MCP в локальный каталог.

Тело запроса:
```json
{
  "serverId": "srv_01HRJ2P0M6M8C12K8QKQ",
  "force": true
}
```

ИЗМЕНЕНИЯ В ДАННЫХ
- Таблица `mcp_server`
  `id`, `code`, `name`, `description`, `owner_login`, `endpoint_url`, `transport`, `legacy_mode`, `status`, `maintenance_status`, `auth_policy_id`, `active_version`, `created_at`, `updated_at`
- Таблица `mcp_server_version`
  `id`, `server_id`, `version`, `protocol_version`, `endpoint_url`, `config_json`, `status`, `created_at`
- Таблица `mcp_tool`
  `id`, `server_id`, `name`, `title`, `description`, `input_schema_json`, `read_only_hint`, `tags_json`, `intent_text`, `last_synced_at`
- Таблица `auth_policy`
  `id`, `code`, `grant_type`, `system_code`, `inject_mode`, `scopes_json`, `adapter_code`, `service_account_allowed`, `created_at`, `updated_at`
- Таблица `auth_adapter`
  `id`, `code`, `type`, `endpoint_url`, `config_json`, `status`, `created_at`, `updated_at`
- Таблица `user_external_identity`
  `id`, `user_sub`, `system_code`, `external_login`, `external_subject`, `status`, `last_verified_at`
- Таблица `credential_binding`
  `id`, `user_sub`, `system_code`, `binding_type`, `secret_ref`, `expires_at`, `refresh_after`, `status`, `last_used_at`
- Таблица `proxy_session`
  `id`, `proxy_session_id`, `upstream_session_id`, `server_id`, `agent_id`, `user_sub`, `protocol_version`, `status`, `expires_at`, `created_at`, `closed_at`
- Таблица `audit_event`
  `id`, `request_id`, `event_type`, `agent_id`, `user_sub`, `server_code`, `tool_name`, `result_status`, `http_status`, `duration_ms`, `created_at`, `payload_json`
- Индексы:
  уникальный индекс на `mcp_server.code`
  составной индекс на `credential_binding (user_sub, system_code, status)`
  индекс на `proxy_session.proxy_session_id`
  индекс на `audit_event (created_at, agent_id, server_code)`
- Секреты по полям `secret_ref`, `refresh_token`, `password` в БД не хранятся; вместо них хранится только ссылка на Vault/KMS.
- Для `mcp_tool.intent_text` допускается полнотекстовый индекс или перенос в отдельный search engine.

UI-ТРЕБОВАНИЯ
- В UI должен быть экран "Подключить MCP" с формой: код, название, описание, endpoint, transport, owner, система, теги, auth policy.
- Для выбора авторизации UI должен показывать только поддерживаемые организацией grant types и короткое пояснение по каждому.
- Перед сохранением UI должен запускать "Проверить подключение" и показывать по шагам: TLS, initialize, tools/list, auth policy.
- Серверы в статусах `draft`, `validation_running`, `validation_failed`, `active`, `disabled` должны иметь визуально разные бейджи.
- На карточке сервера должен отображаться список инструментов, дата последней синхронизации и maintenance status.
- Ошибки валидации должны выводиться в явном виде с кодом и человекочитаемым сообщением.
- UI не должен отображать реальные токены, пароли, refresh token или содержимое `secret_ref`.

ТЕСТ-КЕЙСЫ
1) Отправить `initialize` в активный MCP-сервер с валидным агентским токеном и пользовательским JWT -> прокси возвращает `InitializeResult` и `MCP-Session-Id`.
2) Отправить `tools/call` в активную session c валидным токеном в кэше -> вызов проходит успешно, в аудит пишется запись.
3) Отправить `tools/list` при истекшем access token и валидном refresh token -> прокси обновляет токен и возвращает результат без ошибки.
4) Отправить изменяющий `tools/call` при ответе upstream `401` -> прокси не повторяет запрос автоматически и возвращает `upstream_auth_failed`.
5) Отправить запрос без `Authorization` -> вернуть `401 agent_unauthorized`.
6) Отправить запрос без `X-User-Assertion` -> вернуть `400 user_assertion_missing`.
7) Отправить запрос с просроченным пользовательским JWT -> вернуть `401 user_assertion_invalid`.
8) Вызвать несуществующий `server_code` -> вернуть `404 server_not_available`.
9) Зарегистрировать новый MCP-сервер с корректным endpoint и рабочим `initialize` -> сервер переходит в `active`, инструменты синхронизированы.
10) Зарегистрировать MCP-сервер с невалидным endpoint -> сервер переходит в `validation_failed`, пользователь получает `422 validation_error`.
11) Выполнить поиск инструмента по `intent` и тегу -> API возвращает только серверы, доступные данному агенту.
12) Закрыть session через `DELETE /mcp/{server_code}` -> proxy-session и upstream-session завершаются, повторный вызов с тем же `MCP-Session-Id` возвращает `404 session_expired`.
13) Отключить аудит-хранилище во время рабочего вызова -> пользователь получает успешный ответ, событие попадает в `audit_dlq`.
14) Синхронизировать tool catalog после изменения списка инструментов upstream MCP -> локальный каталог обновляется, дата `last_synced_at` изменяется.

КРИТЕРИИ ГОТОВНОСТИ
- Реализован единый MCP proxy endpoint для stateful remote-сессий.
- Реализована валидация агентского токена и пользовательского JWT.
- Реализован credential broker с поддержкой минимум `service_jwt_exchange`, `oauth_refresh_token`, `api_token`.
- Реализован self-service API/UI для публикации и валидации новых MCP-серверов.
- Реализован каталог серверов и инструментов с фильтрацией по доступам.
- Реализован аудит вызовов и административных действий.
- Реализованы health checks, session store и базовые эксплуатационные метрики.
- Пройдены позитивные и негативные тест-кейсы из настоящего ТЗ.
- Подготовлена эксплуатационная документация по добавлению нового auth adapter и нового коробочного MCP.
- Не выявлено критических дефектов уровня блокер и critical.

ГЛОССАРИЙ
- MCP Proxy — единая точка входа, которая принимает вызовы агентов и проксирует их в целевые MCP-серверы.
- Коробочный MCP — внешний MCP-сервер для конкретной системы без модификации его исходного кода под инфраструктуру заказчика.
- Agent Access Token — токен или API-ключ, которым агент аутентифицируется в прокси.
- User Assertion — подписанный JWT, представляющий конечного пользователя, от имени которого выполняется вызов.
- Credential Broker — внутренний модуль, который находит, создает, обновляет и выдает credential context для внешней системы.
- Auth Adapter — плагин или сервис, реализующий конкретный сценарий выпуска токена или получения сессии во внешней системе.
- Proxy Session — состояние сессии между агентом и прокси.
- Upstream Session — состояние сессии между прокси и коробочным MCP.
- Maintenance Status — вычисляемый признак актуальности upstream MCP-решения.
- Intent Router — внешний или встроенный слой, который выбирает подходящий MCP или tool на основании пользовательского намерения.
