From 78d3052a617eb3929bfe4a134b6bc22fd2d7c7db Mon Sep 17 00:00:00 2001
From: github-ops <github-ops@rmcp.itexp.me>
Date: Wed, 24 Jun 2026 11:43:34 +0000
Subject: [PATCH] Document human approval flow

---
 docs/mcp-interface.md | 53 +++++++++++++++++++++++++++++++++++++++++++
 docs/ui.md            |  6 ++++-
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/docs/mcp-interface.md b/docs/mcp-interface.md
index 964d74e..c244dab 100644
--- a/docs/mcp-interface.md
+++ b/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-клиент видит только опубликованные операции, которые привязаны к опубликованному агенту.
diff --git a/docs/ui.md b/docs/ui.md
index 759a66b..fa06742 100644
--- a/docs/ui.md
+++ b/docs/ui.md
@@ -60,12 +60,16 @@
 
 ## API ключи
 
-API-ключ выдается на конкретного агента. Ключ позволяет MCP-клиенту:
+API-ключ выдается на конкретного агента. В Community есть два режима ключей.
+
+Ключ MCP-клиента позволяет:
 
 - открыть MCP-сессию;
 - получить список инструментов агента;
 - вызвать опубликованный инструмент.
 
+Ключ подтверждения используется только внешним интерфейсом, где человек подтверждает или отклоняет опасное действие. Такой ключ нельзя передавать MCP-клиенту или LLM.
+
 Полное значение ключа показывается только при создании.
 
 ## Секреты