Дизайн возможностей

Возможность (Capability) — наименьшая описываемая способность системы: типизированная, с проверкой прав, аудируемая и одинаково пригодная как для людей, так и для агентов. MCP-first начинается не с экранов, а с этих способностей. Только когда набор возможностей полон, появляются веб-приложение, мобильное приложение, CLI и агентные интерфейсы как клиенты поверх него.

Семь строительных блоков

MCP-first моделирует каждую способность с помощью семи структурных элементов.

Resources

Данные и контексты, которые можно читать. Resources предоставляют агенту подготовленный контекст — не сырые таблицы баз данных, а отфильтрованные, целевые представления состояния системы.

Tools

Действия, которые система может выполнять. Каждый Tool имеет типизированную входную схему, выходную схему, схему ошибок и схему аудита. Tool — это то, что кнопка в веб-приложении лишь представляет.

Prompts / Workflows

Готовые сценарии, ведущие агента через сложные многоступенчатые процессы. Workflows определяют, какие Tools в какой последовательности и с каким контекстом следует вызывать — и где ожидается участие человека.

Policies

Правила, права, уровни защиты и процессы согласования. Policies определяют, кто вправе видеть, вызывать и автономно выполнять возможность. Они — не слой, который добавляют потом, — они часть определения возможности.

Audit Events

Каждое действие создаёт запись аудита: кто, что, когда, с каким разрешением, с каким результатом. Audit Events — не опциональное расширение операций, а обязательная составляющая каждой возможности.

Human Confirmation Gates

Механизмы, при которых агент обязан активно запросить подтверждение у пользователя перед выполнением действия. Confirmation Gates задекларированы в возможности — не реализуются ad hoc в UI.

Risk Metadata

Каждая возможность несёт уровень риска: low, medium, high, critical или forbidden_for_ai. Эти метаданные управляют фильтрацией Discovery, требованием подтверждения и Step-up Auth — и машиночитаемы в Tool Contract.

Что должна предоставлять каждая сущность

Независимо от предметной области, каждая сущность требует последовательного базового набора возможностей.

Базовые возможности для каждой сущности

entity.list Вернуть отфильтрованный список
entity.search Полнотекстовый поиск со скоупингом
entity.get Одна сущность с контекстом
entity.create Создать новую сущность
entity.update Изменить поля, идемпотентно
entity.archive Деактивировать вместо удаления
entity.audit Получить историю изменений
entity.permissions Запросить действующие права
entity.related Загрузить связанные сущности
entity.recommended_next_actions Агентно-ориентированные предложения действий

Action Layer — прежде всего

Каждая функция сначала реализуется как Action в центральном Action Layer. Только потом создаётся соответствующий интерфейсный адаптер.

Action: create_project

Используется из:
  Webapp
  Mobile App
  MCP Tool
  Worker
  CLI

Благодаря этому нет двойной реализации: когда кнопка веб-приложения вызывает create_project и агент делает то же самое, оба используют один и тот же код, одни и те же валидации, одни и те же Audit Events.

Build capabilities once. Expose them everywhere.

Центральный тезис

MCP-сервер — это адаптер

MCP-сервер не содержит бизнес-логики. Он — тонкий адаптер между агентным клиентом и Action Layer.

Его задачи:

Discovery — какие Tools и Resources существуют в данном контексте?
Schema Exposure — типизированное описание входных, выходных данных и ошибок
Auth Context Mapping — отображение токена клиента на контекст пользователя и тенанта
Policy Checks — вправе ли этот агент вызывать этот Tool в данном контексте?
Audit Logging — записывать Execution Events для каждого выполнения Tool

Типизированные входные и выходные данные

Каждый Tool определяет четыре схемы:

Схема	Назначение
Input Schema	Какие параметры ожидает Tool, какие типы, какие обязательные поля?
Output Schema	Что Tool возвращает при успехе?
Схема ошибок	Какие коды ошибок возможны — `permission_denied`, `confirmation_required`, `policy_violation`?
Схема аудита	Что записывается в Audit Event?

Никаких свободных JSON-структур. Агенты — как и компиляторы и тесты — полагаются на эти схемы. Нетипизированные выходные данные вынуждают к угадыванию логики на стороне клиента.

Идемпотентность

Многие Tools должны быть идемпотентны: при одинаковом запросе возвращать тот же результат без создания нежелательных дубликатов.

create_download_link(fileId, expiresAt)

Если для fileId уже существует действующая ссылка с идентичным expiresAt, возвращается существующая ссылка — не создаётся вторая. Это снижает ошибки агентов при повторных попытках и делает рабочие процессы устойчивее к сетевым сбоям.