> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Didit MCP: настройка, устранение неполадок и self-hosting > Роли и разрешения, работа между приложениями, размещённый каталог, ветвящиеся сценарии, webhook, транспорт, устранение неполадок и self-hosting в Didit MCP. ## Области действия и права ролей Коннектор работает в рамках областей действия `didit:management` и `didit:verification`. Третья область действия, `didit:staff`, анонсируется, но имеет значение только для учётных записей сотрудников Didit. Оба ограничения проверяются при каждом вызове: токен содержит области действия, которые вы одобрили, а **в их пределах доступ определяет роль в консоли**. Фактический доступ определяется пересечением этих ограничений, поэтому если одобрить только `didit:verification`, раздел управления остаётся закрытым, даже для `OWNER`. Каждый инструмент соответствует одному серверному разрешению (`read:sessions`, `write:workflows`, `delete:lists` и т. д.; [справочник инструментов](https://docs.didit.me/ru/integration/mcp/tools.md) указывает его для каждого инструмента). Сервер заранее проверяет это разрешение по организационным разрешениям, которые возвращает интроспекция токена. Поведение задаётся переменной `MCP_PERMISSION_MODE`: | Режим | Поведение | | - | - | | `shadow` (по умолчанию) | Все инструменты показываются в списке. Вызов, который ваша роль не может выполнить, передаётся в бэкенд, и тот отвечает `403`. Результат проверки записывается в журнал аудита сервера. | | `enforce` | Инструменты, которые ваша роль не может выполнить, исключаются из `tools/list`. Вызов такого инструмента возвращает ошибку `missing_scope` с указанием разрешения. | | `off` | Предварительная проверка не выполняется. | MCP никогда не выходит за пределы вашей роли. Ответ `403` на один инструмент означает, что вашей роли не хватает этого разрешения, а не то, что всё подключение не сработало. *** ## Определение области действия для приложений и организаций Управляющий API Didit привязан к приложению (`/organization/{org}/application/{app}/…`). MCP определяет область для вас: * **Одна организация и одно приложение** → определяются автоматически. ID передавать не нужно. * **Несколько приложений** → межприложенческие инструменты (`didit_session_search`, `didit_transaction_search`, `didit_case_search`, `didit_vendor_user_search`, `didit_vendor_business_search`, `didit_workflow_search`, `didit_analytics`) агрегируют данные по **всем** приложениям за один вызов. Каждая строка помечена `organization_id` и `application_id`. * Инструменты списков по приложениям (`didit_session_list`, `didit_transaction_list`, `didit_case_list`, `didit_vendor_user_list`, `didit_vendor_business_list`, `didit_workflow_list`) **автоматически охватывают все приложения**, если вы не указали конкретное. Поэтому запрос «покажи мои сессии» работает и при большом количестве приложений. Передайте `organization_id` и `application_id`, чтобы ограничить выборку одним приложением. Используйте `didit_context_get`, чтобы за один вызов увидеть все ваши организации и приложения (с их ID). Он также показывает `mode` каждого приложения (`live` или `sandbox`), поэтому никогда не угадывайте среду по названию приложения. `didit_session_create` принимает `sandbox_scenario` для приложений в sandbox, что позволяет запускать тестовые прогоны без тарификации. *** ## Состав размещённого каталога Размещённый коннектор предоставляет **169 инструментов**. В списке также есть 17 инструментов Investigator, которые работают только после включения Investigator для вашей организации. Ещё два инструмента, `didit_org_top_up` (оплата через Stripe) и `didit_org_reveal_application_api_key` (сырой секрет), скрыты из `tools/list` для каждого вызывающего, прошедшего аутентификацию через OAuth. Пять инструментов настройки аккаунта (`didit_account_*`) полностью исключены из удалённых серверов и отказываются работать там, потому что удалённый коннектор никогда не должен принимать учётные данные как аргументы инструмента. Локальный сервер stdio сохраняет их все: всего 193. Каждый инструмент в списке содержит аннотации MCP (`readOnlyHint`, `destructiveHint`, `openWorldHint`, `title`), `outputSchema` и метку `_meta["anthropic/toolGroup"]`, которая называет его область (Сессии, Сценарии и анкеты, Транзакции (AML) и т. д.). Клиенты, такие как Claude, используют аннотации, чтобы разделить инструменты коннектора на группы для чтения, записи и деструктивных действий. ## Ветвящиеся сценарии Простые сценарии представляют собой плоский список функций. Для **условной логики** (отклонить при определённом статусе, направить по извлечённому полю, разрешить выполнение шага при совпадении, добавить запрос Document AI) MCP работает с **графом узлов** Didit, то есть с той же структурой, что и визуальный конструктор в консоли. Граф задаётся как `{ start_node, nodes }`. Каждый узел представляет собой `feature` (функция), `branch` (ветвление), `status` (терминальный статус), `action` (действие) или `webhook`. Правила ветвления поддерживают операторы, включая **`fuzzy_match`** (для строковых полей с порогом сходства `score` от 0 до 100) по извлечённым полям, например `kyc.extra_fields.profession`. Узел функции `DOCUMENT_AI` запрашивает документы, например подтверждение наличия средств. ### Редактирование существующего сценария (рекомендуется) Реальные сценарии содержат **большие** конфигурации функций: список разрешённых документов OCR `documents_allowed` может занимать 150 KB+, а также списки POA и кодов стран телефона. Поэтому **не** читайте весь граф и не отправляйте его целиком. Вместо этого редактируйте сценарий с помощью небольших **операций**: **1. Поиск и просмотр** `didit_workflow_search { workflow_id }` находит сценарий во всех ваших приложениях. `didit_workflow_get_graph` возвращает структуру, в которой большие конфигурации **сокращены** (размер ответа не превышает лимит; передайте `include_config: true`, чтобы получить исходные значения). `didit_workflow_get_field_definitions` перечисляет поля, по которым можно ветвить, и допустимые операторы. **2. Редактирование с помощью операций** `didit_workflow_edit_graph` принимает несколько небольших операций: `set_next`, `set_node`, `set_branches`, `merge_node_config`. MCP получает **полный граф на стороне сервера**, применяет операции, проверяет граф, автоматически создаёт **черновик** и сохраняет его. Ваши списки разрешений сохраняются **байт в байт** и никогда не передаются в запросе. Если проверка не пройдена, возвращается `applied: false` (ничего не сохранено). **3. Проверка и публикация** Сценарий остаётся черновиком для проверки, пока вы не выполните `publish` (в консоли или через `didit_workflow_publish`). Действующая версия никогда не изменяется. Например, чтобы вставить ветку после верификации личности, которая **возвращается в существующий процесс**, достаточно передать следующее: перенаправить `next` узла OCR на новую ветку, а также добавить ветку, терминальный узел `Declined` и шаг `DOCUMENT_AI`, чей `next` указывает обратно на исходный следующий шаг. Остальные 10 узлов и их списки разрешений остаются без изменений. > *"После верификации личности, если она была отклонена, отклонить; если profession ≈ «Software Engineer» (≥80%), запросить подтверждение наличия средств; затем продолжить."* → один узел `branch`: `kyc.status == Declined` → узел статуса `Declined`; `kyc.extra_fields.profession` `fuzzy_match` «Software Engineer» с оценкой 80 → узел `DOCUMENT_AI` для подтверждения наличия средств → и путь **иначе** обратно в процесс. > [!NOTE] > > **Ветвление всегда требует явного пути «иначе».** Путь по умолчанию, то есть путь, который выбирается, когда ни одно условие не совпало, должен быть веткой с пустым `rules`, например `{ "id": "else", "rules": [], "goto": "" }`, а не простым полем `next` узла ветвления. MCP (и бэкенд) автоматически преобразуют `next` узла ветвления в ветку **иначе**, поэтому ветвление никогда не отображается как неоднозначная связь без видимого пути **иначе**. Чтобы построить **новый** сценарий с нуля, используйте `didit_workflow_validate_graph`, а затем `didit_workflow_set_graph` (полный граф), либо позвольте `didit_workflow_build_graph` собрать полный граф из простой спецификации функций без сохранения. Даже простой `didit_workflow_create` сохраняется как тот же граф узлов: MCP собирает список `features` в цепочку узлов функций, которая заканчивается узлом статуса с автоматическим решением, чтобы функции действительно выполнялись. По умолчанию сценарий публикуется; передайте `status: "draft"`, чтобы оставить его неопубликованным. Полную структуру JSON см. в разделе [Создание сценария → ветвящиеся и узловые сценарии](https://docs.didit.me/ru/management-api/workflows/create.md). ### Ветвление по причинам пропуска NFC в MCP Для нового графа попросите: > *"Создай черновик сценария с верификацией личности, за которой следует NFC. Если `nfc.skip_reason` равен `DEVICE_WITHOUT_NFC` или `DOCUMENT_WITHOUT_CHIP`, переведи сессию в статус «на проверке»; в остальных случаях одобри её. Сохрани явную ветку «иначе» и проверь граф перед сохранением."* Агент должен вызвать `didit_workflow_get_field_definitions`, `didit_workflow_validate_graph`, а затем `didit_workflow_set_graph`. Для существующего сценария попросите: > *"Измени сценарий `26d33c04…`: после его узла NFC переведи любое из семи известных значений `nfc.skip_reason` в статус «на проверке», а существующий путь успешного NFC сохрани как явную ветку «иначе». Сохрани черновик и не публикуй его."* Агент должен вызвать `didit_workflow_search`, `didit_workflow_get_graph`, `didit_workflow_get_field_definitions`, а затем `didit_workflow_edit_graph`. Инструмент редактирования применяет небольшие операции на стороне сервера, поэтому не затрагивает несвязанные узлы и большие списки разрешений. Семь значений, правила `equals` и `in`, поведение при null и полный упорядоченный граф см. в разделе [Создание сценария → Ветвление по причине, по которой NFC не запустился](https://docs.didit.me/ru/management-api/workflows/create.md#ветвление-по-причине-по-которой-nfc-не-выполнялся). ### Конфигурации функций и списки разрешений Поле `config` узла функции ограничивает набор принимаемых данных. `didit_workflow_get_feature_config_schema` возвращает все ключи, которые принимает каждая функция, с типами и значениями по умолчанию. Два каталожных инструмента (`didit_workflow_get_id_verification_methods_catalog` и `didit_workflow_get_kyb_registry_catalog`) отвечают на вопросы, определяемые сервером и необходимые для настройки конфигурации. Канонический список разрешений OCR имеет структуру «страна → документ → объект»: `{ "": { "": { "enabled": 1 } } }`, например `{ "ESP": { "P": { "enabled": 1 } } }`. Перед проверкой MCP **нормализует более простые формы** записи, поэтому вам не нужно писать эту структуру вручную: | Можно передать | Нормализуется в | | - | - | | Массив типов документов, например `["PASSPORT"]` | этот документ для **каждой** страны (только паспорт во всём мире) | | Названия или коды документов: `PASSPORT`/`P`, `NATIONAL_ID`/`ID`, `DRIVER_LICENSE`/`DL`, `RESIDENCE_PERMIT`/`RP` (также `SSC`, `HIC`, `TC`) | канонический код | | Ключ страны `"ALL"`, например `{ "ALL": { "P": 1 } }` | применяется ко всем странам | | Скалярные флаги, например `{ "ESP": { "P": 1 } }` | `{ "ESP": { "P": { "enabled": 1 } } }` | | Не указано вовсе | все документы, все страны | `poa_languages_allowed` у `PROOF_OF_ADDRESS` работает по тому же принципу: передайте массив языков (`["es"]`) или словарь (`{ "es": 1 }`). Эти удобства применяются везде, где вы передаёте MCP конфигурацию функции: в параметрах `didit_workflow_create` (в поле функций), а также в `config` узлов в `set_graph`, `edit_graph` и `validate_graph`. ## Структура ответа (контракт V3) Каждый инструмент возвращает исходный JSON соответствующего REST-endpoint. Учтите два момента: * **Синхронные инструменты** (сценарии, биллинг, отдельные `verify_*` и управление списками) возвращают окончательный результат прямо в ответе. Действуйте по нему в том же сообщении. * **Создание сессии асинхронно.** `didit_session_create` возвращает `url`, по которому пользователь должен перейти и завершить процедуру. Решение приходит через webhook или через `didit_session_get_decision`. Ключи решений **всегда представлены массивами**, и у каждого элемента есть `node_id`: `id_verifications[]`, `liveness_checks[]`, `face_matches[]`, `aml_screenings[]`, `poa_verifications[]`, `phone_verifications[]`, `email_verifications[]`, `database_validations[]`, `reviews[]`, а также для KYB `registry_checks[]`, `document_verifications[]` и `key_people_checks[]`. См. [Модели данных](https://docs.didit.me/ru/reference/data-models.md) и [Статусы верификации](https://docs.didit.me/ru/integration/verification-statuses.md). *** ## Обработка webhooks Пусть webhook доставляет окончательное решение на ваш бэкенд вместо того, чтобы агент опрашивал статус: 1. Агент один раз вызывает `didit_webhook_create` с `label`, вашим публичным HTTPS-`url`, `webhook_version: "v3"` и `subscribed_events` (обычно `["status.updated", "data.updated"]`). Ответ скрывает секрет подписи, так же как `didit_webhook_get` и `didit_webhook_list`. Скопируйте секрет из раздела **Вебхуки** в консоли и сохраните его как `DIDIT_WEBHOOK_SECRET`. 2. Ваш бэкенд проверяет канонический заголовок **X-Signature-V2** в каждой доставке: `shortenFloats` → `sortKeys` → `JSON.stringify` (без экранирования unicode) → HMAC-SHA256 → `timingSafeEqual`. Отклоняйте запрос, если `abs(now − X-Timestamp) > 300` секунд. 3. Дедуплицируйте события по `event_id`. Возвращайте `2xx` в течение **5 секунд**, а тяжёлую работу переносите в очередь. 4. Didit повторяет доставку при `5xx` или `404` до **2 раз** (примерно через 1 минуту, затем через 4 минуты), после чего отбрасывает её. Неудачные доставки можно повторить из вкладки **Доставки** в консоли. Агенту нужно только *настроить* приёмник: сам он не слушает события. Полная спецификация: [Вебхуки](https://docs.didit.me/ru/integration/webhooks.md). *** ## Транспорт и endpoints | Endpoint | Назначение | | - | - | | `POST https://mcp.didit.me/mcp` | endpoint MCP (Streamable HTTP). `GET` и `DELETE` возвращают `405`: сервер не хранит состояние, создаёт новый экземпляр сервера на каждый запрос и не ведёт поток или сессию, инициированные сервером, которые нужно было бы закрывать. | | `GET https://mcp.didit.me/healthz` | Проверка работоспособности: `{ "status": "ok", "service": "didit-mcp-server", "version": "5.1.1" }`. | | `GET https://mcp.didit.me/.well-known/oauth-protected-resource/mcp` | Метаданные защищённого ресурса по RFC 9728 (также доступны в корне домена). | Endpoint работает в двух режимах. Клиенты, которые в каждом сообщении указывают версию протокола 2026-07-28 или новее, пропускают рукопожатие `initialize` и могут вызывать `server/discover`. Все более ранние клиенты (Claude Code, Cursor, клиенты на базе SDK) используют стандартное рукопожатие Streamable HTTP без изменений. CORS открыт, поэтому браузерные клиенты (веб-коннектор Claude, MCP Inspector) могут обращаться к `/mcp` и документам обнаружения с других доменов. Лимит размера JSON-тела составляет 25 МБ, этого достаточно для входного файла в base64 размером 15 МБ. *** ## Устранение неполадок > [accordion] Агент вызывает инструмент и получает 403 или missing\_scope > > Вашей **роли** в этой организации не хватает разрешения, которое нужно инструменту (например, `READER` пытается выполнить запись). Ошибка `missing_scope` указывает, какое именно. Если не работает ни один инструмент, переподключитесь или повторите *Log in with Didit*. (MCP работает только через Bearer/OAuth. `x-api-key` отклоняется всеми инструментами, поэтому API-ключ не исправит ошибку 403.) > [accordion] Запись или удаление не выполнились > > Операция записи или удаления не выполнилась. Деструктивные инструменты требуют подтверждения в вашем клиенте. Подтвердите вызов или проверьте, что запрос подтверждения не отклоняется автоматически. Для `didit_session_delete`, `didit_session_batch_delete` и `didit_org_reveal_application_api_key` дополнительно нужен `confirm: true` в аргументах инструмента. Без него вызов отклоняется до выполнения. > [accordion] 'organization\_id is required' или пустой результат > > Скорее всего, у вас несколько приложений. Используйте инструмент `*_search` (он ищет во всех приложениях) или выполните `didit_context_get` и передайте нужные `organization_id` и `application_id`. > [accordion] Браузер не открылся для входа (размещённый режим) > > Некоторые клиенты (Windsurf, Zed) подключаются через мост `mcp-remote`. Убедитесь, что в конфигурации есть `npx -y mcp-remote@latest https://mcp.didit.me/mcp`. Чтобы заново запустить OAuth-рукопожатие, переоткройте клиент. > [accordion] Инструменты не появляются в клиенте > > Убедитесь, что сервер подключён (в большинстве клиентов это показывает индикатор статуса) и что вы прошли *Log in with Didit*. После изменения конфигурации перезапустите хост MCP. `didit_org_top_up` и `didit_org_reveal_application_api_key` никогда не отображаются в размещённом коннекторе. > [accordion] VS Code (или другой клиент) не может найти OAuth и не открывает браузер > > Убедитесь, что указан адрес `https://mcp.didit.me/mcp`, а не корневой адрес `https://mcp.didit.me`. Метаданные ресурса доступны по пути `/.well-known/oauth-protected-resource/mcp` и привязаны к этому пути, а копия находится в корне домена для клиентов, которые проверяют именно там. При самостоятельном развёртывании обычно причина в том, что `MCP_RESOURCE_URI` указывает на корневой URL, а не на полный URL транспорта. См. [Самостоятельное развёртывание](#самостоятельное-развертывание). > [accordion] Загрузка файла отклонена > > При работе с размещённым endpoint отправляйте файл как `*_base64` (чистый base64 или URL `data:`). Параметр `*_path` работает только на локальном stdio-сервере. Размер файлов ограничен 15 МБ, а по содержимому (не только по расширению) файл должен быть PNG, JPG, WebP, GIF, BMP, ICO или PDF. *** ## Безопасность MCP действует с вашими реальными правами и может изменять рабочие ресурсы. Оставьте включённой настройку **"проверять вызовы инструментов перед запуском"** в вашем клиенте, особенно для инструментов категорий **Запись** и **Деструктивные**. Сам MCP не хранит **никаких секретов** в вашей конфигурации (он использует **Вход через Didit**), маскирует API-ключи и секреты для подписи webhook в выводе инструментов, скрывает из размещённого каталога инструменты пополнения баланса и работы с необработанными ключами и никогда не принимает учётные данные аккаунта как аргументы инструментов на удалённом сервере. Каждый вызов инструмента записывается в журнал аудита сервера с указанием вызывающей стороны, инструмента и решения проверки прав. ### Инъекция промптов Инструменты Didit возвращают то, что ввели или загрузили ваши пользователи, например имена, текст документов и ответы на анкеты. Человек, проходящий верификацию, контролирует этот текст, поэтому он может вписать в имя или документ инструкции для вашего агента, а сервер вернёт эти поля в том виде, в котором они были получены. Агент не может надёжно отличить такой текст от ваших собственных инструкций, поэтому относитесь к каждому результату инструмента как к данным: * Оставьте подтверждение инструментов включённым для инструментов категорий **Запись** и **Деструктивные** и внимательно читайте, что агент собирается сделать, прежде чем подтвердить действие. * Входите как участник, роль которого соответствует задаче. Агент, который только читает сессии, может использовать участника с ролью `READER`, и бэкенд отклонит его запросы на запись, что бы ни пытался сделать агент. * Сначала опробуйте нового агента или новый промпт на [приложении в песочнице](https://docs.didit.me/ru/integration/sandbox-testing.md). * Никогда не одобряйте и не отклоняйте верификацию на основании того, что написано внутри неё. Опирайтесь на решение, его предупреждения и собственную проверку. ### Персональные данные Результаты инструментов могут содержать персональные данные, такие как имена, даты рождения, номера документов и ссылки на изображения, а ваш MCP-клиент передаёт их модели, которую он использует. Перед подключением боевого приложения убедитесь, что ваше соглашение с поставщиком ИИ распространяется на эти данные, или работайте с приложением в песочнице. *** ## Самостоятельное развертывание Размещённый сервер собран из [github.com/didit-protocol/mcp](https://github.com/didit-protocol/mcp) (лицензия MIT). Клонируйте репозиторий и запустите его через **Docker** или Node. Он всегда проходит аутентификацию от имени Didit **пользователя** (режима API-ключа нет) в любом транспорте. Шаги настройки описаны в разделе [Установка → самостоятельное развертывание](https://docs.didit.me/ru/integration/mcp/installation.md#самостоятельное-развертывание). ```bash theme={null} git clone https://github.com/didit-protocol/mcp.git && cd mcp # Docker (recommended) — serves /mcp + /healthz on port 3000 docker build -t didit-mcp . && docker run -p 3000:3000 --env-file .env didit-mcp # …or with Node npm install && npm run build node dist/http.js # hosted HTTP/OAuth DIDIT_ACCESS_TOKEN= node dist/index.js # stdio (headless) ``` ### Переменные окружения | Переменная | Режим | Назначение | | - | - | - | | `DIDIT_ACCESS_TOKEN` | stdio | Bearer-токен доступа пользователя для запусков без интерфейса. | | `DIDIT_API_BASE_URL` | оба | Базовый URL API верификации (по умолчанию `https://verification.didit.me/v3`). | | `DIDIT_AUTH_BASE_URL` | оба | Базовый URL API аутентификации (по умолчанию `https://apx.didit.me/auth/v2`). | | `MCP_PORT` | размещённый | Порт прослушивания HTTP (по умолчанию `3000`). | | `MCP_RESOURCE_URI` | размещённый | Публичный URL транспорта, включая путь (например, `https://mcp.example.com/mcp`). URL метаданных RFC 9728 формируется из него. | | `MCP_AUTHORIZATION_SERVER_ORIGIN` | размещённый | источник сервера авторизации (по умолчанию `https://business.didit.me`). | | `MCP_TOKEN_VERIFY_MODE` | размещённый | `introspection` (по умолчанию; непрозрачные токены) или `jwks` (JWT-токены доступа). | | `MCP_OAUTH_INTROSPECT_URL` | размещённый | endpoint интроспекции по RFC 7662. | | `MCP_OAUTH_CLIENT_ID` / `MCP_OAUTH_CLIENT_SECRET` | размещённый | Учётные данные Basic-аутентификации, которые ресурсный сервер использует для вызова интроспекции. Передавайте их из менеджера секретов. | | `MCP_SCOPES_SUPPORTED` | размещённый | Скоупы, объявленные в метаданных (по умолчанию `didit:management didit:verification`). | | `MCP_DEFAULT_ORG` / `MCP_DEFAULT_APP` | оба | Автоматически заполняют скоуп для однотенантных развертываний. | | `DIDIT_AUTH_ISSUER`, `DIDIT_OIDC_DISCOVERY_URL`, `DIDIT_OIDC_AUTHORIZE_URL`, `DIDIT_OIDC_TOKEN_URL`, `DIDIT_OIDC_REGISTRATION_URL` | размещённый | Переопределяют метаданные сервера авторизации; нужны, только если он публикует свои endpoint’ы где-либо, кроме URL по умолчанию для этого источника. | | `DIDIT_JWKS_URL` | размещённый | JWKS, который используется при `MCP_TOKEN_VERIFY_MODE=jwks`. | | `MCP_PERMISSION_MODE` | оба | Предварительная проверка прав для каждого инструмента: `shadow` (по умолчанию), `enforce` или `off`. | | `MCP_JSON_BODY_LIMIT` | размещённый | Лимит размера тела JSON-RPC (по умолчанию `25mb`). | `.env.example` в репозитории: шаблон для копирования, а `ARCHITECTURE.md` объясняет разделение ресурсного сервера и сервера авторизации. При запуске HTTP-сервер запрашивает документ обнаружения сервера авторизации и, если он недоступен, использует настроенные URL. *** > [card] [Справочник инструментов](https://docs.didit.me/ru/integration/mcp/tools.md) > > Все инструменты, сгруппированные по областям. > [card] [Примеры](https://docs.didit.me/ru/integration/mcp/examples.md) > > Промпты и сквозные диалоги. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.