# 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:

```text
/mcp/v1/{workspace_slug}/{agent_slug}
```

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

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

## 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 слое.