crank/docs/mcp-interface.md

MCP Interface

1. Назначение документа

Этот документ фиксирует, как именно платформа публикует agents и operations в виде MCP tools и какой transport используется в целевой модели.

2. Архитектурное решение

mcp-server публикует tools через network-oriented MCP transport.

Решение:

• основной transport: Streamable HTTP;
• POST может завершаться application/json или text/event-stream;
• GET SSE stream поддерживается как server-to-client канал;
• отдельный mcp-server как сервис;
• stdio не является обязательной частью текущего scope.

3. Модель публикации tools

Каждая published operation превращается в один MCP tool внутри конкретного published agent.

Соответствие:

• один published agent;
• набор AgentOperationBinding;
• один tool name на binding;
• одна input schema;
• один результат.

Публикация tool основана на:

• agent.slug
• operation.name или binding-level tool_name
• tool_description
• input_schema
• published runtime view

4. Что делает mcp-server

mcp-server должен:

• загрузить published agents и их bindings из registry;
• преобразовать их в MCP tool definitions;
• вести Mcp-Session-Id и MCP-Protocol-Version;
• принимать вызовы tools от MCP clients;
• валидировать вход;
• делегировать исполнение в runtime;
• возвращать нормализованный output.

5. Что не делает mcp-server

mcp-server не должен:

• читать draft-конфигурации;
• управлять versioning;
• импортировать YAML;
• выполнять CRUD;
• заниматься protobuf discovery;
• содержать бизнес-логику admin UI.

6. Runtime view

В runtime view остаются:

• workspace_id
• agent_id
• operation_id
• protocol
• target
• input_schema
• output_schema
• input_mapping
• output_mapping
• execution_config
• tool_description

В runtime view не попадают:

• raw uploaded samples;
• generated draft metadata;
• YAML import metadata;
• UI-specific helper fields.

7. MCP endpoint model

Канонический endpoint:

/mcp/v1/{workspace_slug}/{agent_slug}

Этот endpoint определяет:

• tenant boundary;
• конкретный curated toolset;
• набор usage и log labels.

7.1. MCP authentication

Целевая модель машинной аутентификации для mcp-server строится вокруг AI-агента, а не вокруг рабочей области целиком. При этом допустимый способ вызова определяется не только агентом, но и уровнем защиты самой операции.

Контракт:

• каждому published agent соответствует собственный длинноживущий agent key;
• agent key принадлежит одновременно workspace и agent;
• в редакции Community вызовы допускаются по статическому agent key;
• в управляемой платформе для операций уровня elevated должен использоваться короткоживущий токен;
• в редакции Enterprise для операций уровня strict должен использоваться одноразовый токен;
• операция задает обязательный security_level, и mcp-server обязан отклонять вызов, если представленный credential слабее требуемого уровня;
• детальная модель уровней зафиксирована в docs/agent-auth-model.md.

Уровни защиты операции:

• standard
• elevated
• strict

Правило применения:

• standard допускает статический ключ агента, короткоживущий токен и одноразовый токен;
• elevated допускает короткоживущий токен и одноразовый токен;
• strict допускает только одноразовый токен.

8. MCP lifecycle

Поддерживаемые JSON-RPC методы:

• initialize
• notifications/initialized
• ping
• tools/list
• tools/call

Дополнительно на transport уровне:

• POST /mcp/v1/{workspace_slug}/{agent_slug} как основной MCP endpoint;
• GET /mcp/v1/{workspace_slug}/{agent_slug} для SSE stream;
• DELETE /mcp/v1/{workspace_slug}/{agent_slug} для explicit session termination, если сервер разрешает client-side session close.

Tool listing

1. клиент вызывает tools/list;
2. mcp-server извлекает workspace_slug и agent_slug из path;
3. перечитывает published agent по refresh policy;
4. строит или обновляет in-memory catalog tools только для этого agent;
5. отдает список tools через MCP JSON-RPC result.

Tool call

1. клиент вызывает tool;
2. mcp-server определяет workspace и agent;
3. находит binding нужной operation внутри published agent;
4. валидирует input относительно schema;
5. делегирует вызов в crank-runtime;
6. возвращает результат.

Tool call и streaming

Поддерживаются четыре execution modes:

• unary
• window
• session
• async_job

Правила публикации:

• unary и window публикуются как один tool;
• session публикуется как start/poll/stop family;
• async_job публикуется как start/status/result/cancel family.

Transport-level SSE не отменяет bounded tool semantics. Даже если POST отвечает через text/event-stream, итогом вызова должен оставаться управляемый JSON-RPC lifecycle.

8.1. Multiple SSE connections

Crank должен корректно работать, если MCP client держит несколько SSE streams одновременно.

Правила:

• одно server message отправляется только в один stream;
• disconnect не считается cancel;
• cancel выражается отдельным MCP notification или session/job control tool;
• resumability допустима как будущая возможность, но не обязательна в MVP.

9. Обновление tools

После публикации новой operation version или agent version:

1. admin-api фиксирует published version в registry;
2. registry обновляет published operations или published agents;
3. mcp-server не требует restart;
4. выполняется controlled refresh опубликованного каталога;
5. новый tool contract становится доступен MCP clients.

10. Именование tools

Рекомендуется использовать стабильные tool names:

• crm_create_lead
• user_get_profile
• inventory_list_items

Требования:

• имя уникально в пределах одного agent;
• имя не зависит от numeric version;
• один и тот же operation может публиковаться под разными именами в разных agents.

11. Ошибки MCP слоя

На MCP слое нужно различать:

• schema validation error;
• mapping error;
• adapter execution error;
• external service error;
• internal runtime error.

12. Практический итог

• mcp-server - отдельный сервис;
• transport - Streamable HTTP;
• POST и GET transport semantics соответствуют MCP spec 2025-06-18;
• endpoint определяется парой workspace + agent;
• одна published operation = один MCP tool внутри agent;
• streaming operations публикуются как bounded tools или tool families;
• reload published tools без пересборки сервиса;
• никакой draft-логики или admin CRUD в MCP слое.