---
doc_id: ARC-CK8S-MCP-INTERACTION-0001
type: api-contract
title: kodex — MCP и модель взаимодействий
status: active
owner_role: SA
created_at: 2026-04-26
updated_at: 2026-05-28
related_issues: [599, 600, 601, 602, 747, 753, 778, 786, 830, 841, 852, 933, 322, 782]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-26-platform-architecture-frame"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-26
---

# MCP и модель взаимодействий

## Кратко

Платформенный MCP-сервер является тонкой инструментальной поверхностью для agent-manager, агентов в слотах и будущих интеграций. Он не владеет доменными данными, а проверяет политики, пишет аудит и маршрутизирует вызовы к сервисам-владельцам. Решения по risk/gate/release принадлежат `governance-manager`, а доставка человеку, callbacks, уведомления и внешние каналы принадлежат `interaction-hub`.

## Роли MCP-контура

| Контур | Назначение |
|---|---|
| `platform-mcp-server` | Авторизация MCP-клиента, проверка политики, аудит, маршрутизация MCP-инструментов к сервисам-владельцам. |
| `codex-hook-ingress` | Приём нормализованных Codex hook events от hook emitter или локального sidecar; это не MCP-сервер и не владелец бизнес-состояния. |
| `agent-manager` | Быстрый управляющий агент, который использует MCP как основной инструментальный интерфейс платформы. |
| `governance-manager` | Сервис-владелец risk assessments, review signals, gate decisions, release decisions и release safety-loop. |
| Агент в слоте | Использует MCP для платформенных операций, обратной связи, согласований, среды исполнения и безопасных действий. |
| Сервисы-владельцы | Реализуют фактические команды и чтения; MCP не подменяет их доменную логику. |
| `interaction-hub` | Владеет диалогами, доставкой запросов к человеку, уведомлениями, обратными вызовами и внешними каналами. |

## Что идёт через MCP

Через MCP должны проходить операции, где нужны:
- политика и аудит;
- доступ к платформенным сервисам-владельцам;
- управление агентным запуском, обратной связью, запросом Human gate или уведомлением;
- работа со средой исполнения, слотом, заданием или контуром серверов и кластеров;
- операция провайдера, если она выполняется как платформенная операция, а не как обычная работа агента в слоте через `gh`;
- запрос к человеку из слота или agent-manager.

Через MCP не надо пропускать обычную работу агента в слоте с нативными артефактами провайдера, если роль и политика разрешают `gh` или нативный API провайдера.

## Категории инструментов

| Категория | Сервис-владелец | Примеры инструментов |
|---|---|---|
| Инструменты доступа | `access-manager` | Проверить principal, получить допустимые действия, проверить членство. |
| Инструменты проектов | `project-catalog` | Получить состав рабочего пространства, источники документации, релизную политику, политику размещения. |
| Инструменты провайдера | `provider-hub` | Создать `Issue`, обновить метки, перечитать артефакт, получить состояние лимитов. |
| Инструменты пакетов | `package-hub` | Найти пакет, проверить установку, получить манифест руководящего пакета. |
| Инструменты агентов | `agent-manager` | Создать агентный запуск, продолжить сессию, записать результат приёмки, зафиксировать ожидание flow, запросить последующую задачу. |
| Инструменты governance | `governance-manager` | Оценить риск, записать review signal, создать gate request, зафиксировать gate/release decision. |
| Инструменты среды исполнения | `fleet-manager`, `runtime-manager` | Получить слот, запросить задание, продлить удержание слота, освободить слот. |
| Инструменты взаимодействий | `interaction-hub` | Запросить обратную связь, доставить запрос согласования, отправить уведомление, обработать обратный вызов. |
| Операционные инструменты | `operations-hub` | Получить операторскую ленту событий, очереди, блокировки и сводку статуса. |

## MVP platform-mcp-server

Стартовая реализация `platform-mcp-server` должна поддержать минимальную MCP-поверхность, нужную для `agent-manager`, slot-агентов и будущих интеграций. Каноническая машинно-читаемая поверхность MCP получается из `tools/list`, где инструменты зарегистрированы в коде через MCP SDK и имеют JSON Schema входа. Codex hooks не являются MCP tool calls: Codex запускает command hooks, а нормализованные hook events принимает отдельный `codex-hook-ingress`.

| Группа | Владелец маршрута | MVP-смысл |
|---|---|---|
| Agent tools | `agent-manager` | Run, session, session snapshot и Human gate request/get/list только через `agent-manager`; acceptance и follow-up добавляются отдельными срезами. |
| Governance tools | `governance-manager` | Оценка риска маршрутизируется через `governance.risk.evaluate/reevaluate/get/list`, жизненный цикл gate — через `governance.gate.request/get/list/submit_decision/cancel/expire`, релизные решения — через `governance.release.*`, review signals — через `governance.signal.record_review/list_review`. |
| Provider tools | `provider-hub` | Read/write операции провайдера через типизированный provider pipeline, без прямого GitHub/GitLab доступа из MCP. |
| Project/runtime/fleet/package reads | `project-catalog`, `runtime-manager`, `fleet-manager`, `package-hub` | Авторитетные чтения проектной политики, runtime/fleet состояния и пакетных manifest/installations. |
| Interaction tools | `interaction-hub` | Входящие задачи владельца list/get/respond маршрутизируются через `interaction-hub`; запросы обратной связи, approval delivery и отдельные чтения доставки добавляются после готовности соответствующих сервисных операций. |
| Diagnostics | `platform-mcp-server` и владельцы маршрутов | Ограниченный статус readiness/dependency/error без секретов, больших логов и сырых данных вызова. |

Codex hook events для MVP: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `Stop`. Они идут через hook emitter/local sidecar в `codex-hook-ingress`; machine-readable envelope, sanitizer contract и runtime config emitter/sidecar живут в `specs/jsonschema/codex-hook-ingress.v1/**`. Контрольные точки сжатия контекста проектируются отдельно как внутренние события `agent-manager`/`runtime-manager`, а не как Codex hooks.

MCP может быть инструментальной поверхностью для запуска подготовки runtime, но не становится materializer. Для руководящих пакетов MCP передаёт владельцам только refs: `agent-manager` владеет `Run` и замороженными guidance refs, `package-hub` отдаёт package/install/manifest truth, `runtime-manager` материализует источники `guidance_package` и сгенерированный контекст в workspace.

Governance risk, gate, release, review signal и summary tools в MCP являются тонкими маршрутами к `governance-manager`: risk evaluate/reevaluate/get/list используют типизированный governance client, безопасный actor/source/request context, project/provider/agent/runtime refs, ограниченные evidence refs и короткую сводку классификатора; gate request/get/list/submit/cancel/expire используют типизированный governance client, безопасный actor/source/request context и ограниченные refs; release package/decision/blocking/safety-loop tools используют типизированные refs, ограниченные сводки, expected version/idempotency/correlation и возвращают только безопасные ссылки, статусы, outcomes/states, счётчики, версии и timestamps; `governance.summary.get` возвращает owner-prepared `status` rollup, required gate counts, pending/completed decisions, evidence и diagnostics без вычисления governance/security правил в MCP. Для self-deploy MCP показывает безопасную следующую стадию из `agent-manager`/`governance-manager`: request governance gate, owner decision, build context, build, deploy, health или blocker. Запуск deploy job, provider write и доставка владельцу остаются у сервисов-владельцев. MCP не хранит risk assessment, gate request, gate decision, release decision package, release decision, blocking signal, safety-loop, review signal или delivery callback state и не подменяет `interaction-hub` для доставки человеку.

Детальная сервисная граница, стратегия контрактов и план поставки живут в `docs/domains/platform-mcp-server/**`. Граница входного контура Codex hooks живёт в `docs/domains/codex-hook-ingress/**`.

## Безопасность и политики

Каждый MCP-вызов должен иметь:
- идентификатор вызывающей стороны: agent-manager, агент в слоте, нагрузка плагина, пользовательская сессия или сервисный аккаунт;
- область проекта и организации;
- цель операции;
- решение политики;
- запись аудита;
- идентификатор корреляции для связи с агентным запуском, заданием, слотом, артефактом провайдера или согласованием.
- привязку source/run/session/slot для вызовов, которые приходят от slot-агента.

Правило: MCP-сервер не должен сам вычислять бизнес-решение, если это решение принадлежит сервису-владельцу. Он проверяет доступ к инструменту и обращается к соответствующему сервису-владельцу.

MCP-вызов не должен сохранять значения секретов, полный tool input/output, полный prompt, исходные данные провайдера, kubeconfig, большие stdout/stderr или session dump. Для аудита и диагностики используются только безопасные refs, hash/digest, короткие сводки, коды ошибок и correlation id.

## Взаимодействие с человеком

`interaction-hub` владеет:
- диалоговыми ветками;
- пользовательскими сообщениями;
- запросами обратной связи;
- delivery refs и callback-связями для согласований;
- уведомлениями;
- подписками;
- попытками доставки;
- обратными вызовами из внешних каналов;
- ссылками на временные голосовые и медиа-вложения.

Взаимодействие может начаться из:
- web-console;
- голосового ввода;
- нативного упоминания или комментария у провайдера;
- внешнего канала через пакет;
- автоматического события, сигнала тревоги или правила расписания;
- агента в слоте, которому нужна обратная связь.

## Внешние каналы

Список внешних каналов не фиксируется в ядре. Каналы подключаются через пакетную платформу и общий контракт пакета взаимодействия.

Минимальный контракт канала:
- принять сообщение или запрос;
- доставить уведомление;
- вернуть обратный вызов или решение;
- связать попытку доставки с исходным согласованием, агентным запуском, заданием или диалоговой веткой;
- передать ошибки доставки в `interaction-hub`;
- объявить требуемые права и секреты в манифесте пакета.

Примеры каналов:
- Telegram-пакет согласований;
- Telegram-пакет обратной связи;
- пакет email-уведомлений;
- пакет корпоративного мессенджера;
- webhook-пакет для внешних систем.

## Типовые потоки

### Запрос из пользовательского интерфейса или голоса

1. Пользователь отправляет текст или голос в web-console.
2. Соответствующий gateway проверяет сессию и маршрутизирует запрос.
3. `interaction-hub` создаёт или продолжает диалоговую ветку.
4. `agent-manager` интерпретирует намерение через MCP-инструменты.
5. При необходимости `provider-hub` создаёт или обновляет нативный артефакт провайдера.
6. `operations-hub` обновляет проекцию чтения для пользовательского интерфейса.

### Агент в слоте просит обратную связь

1. Агент в слоте вызывает MCP-инструмент запроса обратной связи.
2. `platform-mcp-server` проверяет вызывающую сторону, политику роли, область проекта и контекст агентного запуска.
3. `interaction-hub` создаёт запрос и выбирает канал доставки.
4. Пользователь отвечает через пользовательский интерфейс или внешний канал.
5. `interaction-hub` связывает обратный вызов с запросом.
6. `agent-manager` продолжает сессию или переводит агентный запуск в ожидание или ошибку по политике.

### Human gate перед релизом

1. `governance-manager` формирует release decision package и gate request по релизной политике, полученной через `project-catalog`.
2. `interaction-hub` доставляет запрос владельцу, ведёт попытки доставки и возвращает callback/result в governance-контур.
3. `governance-manager` проверяет actor policy, фиксирует release decision и публикует событие с decision ref.
4. `runtime-manager` не запускает задание выкладки до принятого governance decision ref.
5. `operations-hub` показывает контрольную точку в операторской очереди.
6. После решения сервис-владелец перехода меняет состояние и публикует событие.

## Наблюдаемость

Для MCP и взаимодействий обязательно хранить:
- аудиторский след по каждому вызову инструмента;
- решение политики и причину отказа;
- задержку и класс ошибки;
- статус попытки доставки;
- связь с агентным запуском, заданием, слотом, артефактом провайдера и согласованием;
- короткое описание для операторской ленты событий.

Полные вложения и медиа не хранятся в PostgreSQL. В БД хранится ссылка, метаданные, срок хранения и связь с диалоговой веткой.

## Апрув

- request_id: `owner-2026-04-26-platform-architecture-frame`
- Решение: approved
- Комментарий: MCP и модель взаимодействий входят в сквозной архитектурный каркас платформы.
