crank/docs/mcp-interface.md

MCP Interface

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

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

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

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

Решение:

• основной transport: Streamable HTTP;
• отдельный 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;
• принимать вызовы 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 использует workspace-scoped platform API keys как machine credentials.

Контракт:

• клиент передает Authorization: Bearer crk_...;
• ключ должен принадлежать workspace из path;
• read разрешает initialize, notifications/initialized, ping, tools/list;
• write разрешает tools/call;
• deploy сейчас включает те же MCP права, что и write, и зарезервирован для deploy-scoped automation;
• успешная аутентификация обновляет platform_api_keys.last_used_at.

8. MCP lifecycle

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

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

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. возвращает результат.

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;
• endpoint определяется парой workspace + agent;
• одна published operation = один MCP tool внутри agent;
• reload published tools без пересборки сервиса;
• никакой draft-логики или admin CRUD в MCP слое.