Document human approval flow

docs/mcp-interface.md

@@ -32,6 +32,8 @@ Authorization: Bearer <agent_api_key>
 
 Ключ выдается в разделе **API ключи**. Полное значение показывается только один раз при создании.
 
+Для операций с подтверждением человеком нужен отдельный ключ подтверждения. Его тоже выдают в разделе **API ключи**, но в режиме **Подтверждения**. Такой ключ нельзя передавать LLM или MCP-клиенту. Он нужен только вашему внешнему интерфейсу, где пользователь нажимает «Подтвердить» или «Отклонить».
+
 ## Поддерживаемые методы
 
 MCP methods:
@@ -148,6 +150,57 @@ Crank выполнит REST-запрос:
 GET https://api.frankfurter.dev/v1/latest?base=USD&symbols=EUR
 ```
 
+## Операции с подтверждением человеком
+
+Если в мастере операции включено **Подтверждение человеком**, первый `tools/call` не выполняет REST-запрос сразу. Вместо этого Crank создает ожидающий запрос на подтверждение и возвращает MCP-клиенту структурированный результат:
+
+```json
+{
+  "status": "approval_required",
+  "approval_id": "approval_...",
+  "approval_url": "/v1/default/sales/approvals/approval_...",
+  "approve": {
+    "method": "POST",
+    "url": "/v1/default/sales/approvals/approval_.../approve",
+    "body": { "approve": "yes" }
+  },
+  "deny": {
+    "method": "POST",
+    "url": "/v1/default/sales/approvals/approval_.../deny",
+    "body": { "approve": "no" }
+  }
+}
+```
+
+`approval_url` в ответе является путем на MCP-сервере. Если вы публикуете MCP через префикс `/mcp`, внешний URL будет начинаться с `/mcp/v1/...`.
+
+Внешний интерфейс подтверждения работает отдельным ключом подтверждения:
+
+```bash
+curl https://crank.example.com/mcp/v1/default/sales/approvals \
+  -H 'Authorization: Bearer <approval_api_key>'
+```
+
+Подтверждение:
+
+```bash
+curl https://crank.example.com/mcp/v1/default/sales/approvals/<approval_id>/approve \
+  -H 'Authorization: Bearer <approval_api_key>' \
+  -H 'Content-Type: application/json' \
+  --data '{ "approve": "yes", "note": "Пользователь подтвердил действие" }'
+```
+
+Отклонение:
+
+```bash
+curl https://crank.example.com/mcp/v1/default/sales/approvals/<approval_id>/deny \
+  -H 'Authorization: Bearer <approval_api_key>' \
+  -H 'Content-Type: application/json' \
+  --data '{ "approve": "no", "note": "Пользователь отклонил действие" }'
+```
+
+Ключ MCP-клиента не подходит для этих endpoints. Ключ подтверждения, наоборот, не подходит для `initialize`, `tools/list` и `tools/call`.
+
 ## Как формируется каталог инструментов
 
 MCP-клиент видит только опубликованные операции, которые привязаны к опубликованному агенту.

docs/ui.md

@@ -60,12 +60,16 @@
 
 ## API ключи
 
-API-ключ выдается на конкретного агента. Ключ позволяет MCP-клиенту:
+API-ключ выдается на конкретного агента. В Community есть два режима ключей.
+
+Ключ MCP-клиента позволяет:
 
 - открыть MCP-сессию;
 - получить список инструментов агента;
 - вызвать опубликованный инструмент.
 
+Ключ подтверждения используется только внешним интерфейсом, где человек подтверждает или отклоняет опасное действие. Такой ключ нельзя передавать MCP-клиенту или LLM.
+
 Полное значение ключа показывается только при создании.
 
 ## Секреты