Перейти к основному содержанию

​
Области действия и права ролей

Коннектор работает в рамках областей действия didit:management и didit:verification. Третья область действия, didit:staff, анонсируется, но имеет значение только для учётных записей сотрудников Didit. Оба ограничения проверяются при каждом вызове: токен содержит области действия, которые вы одобрили, а в их пределах доступ определяет роль в консоли. Фактический доступ определяется пересечением этих ограничений, поэтому если одобрить только didit:verification, раздел управления остаётся закрытым, даже для OWNER. Каждый инструмент соответствует одному серверному разрешению (read:sessions, write:workflows, delete:lists и т. д.; справочник инструментов указывает его для каждого инструмента). Сервер заранее проверяет это разрешение по организационным разрешениям, которые возвращает интроспекция токена. Поведение задаётся переменной MCP_PERMISSION_MODE: 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 для подтверждения наличия средств → и путь иначе обратно в процесс.
Ветвление всегда требует явного пути «иначе». Путь по умолчанию, то есть путь, который выбирается, когда ни одно условие не совпало, должен быть веткой с пустым rules, например { "id": "else", "rules": [], "goto": "<liveness>" }, а не простым полем next узла ветвления. MCP (и бэкенд) автоматически преобразуют next узла ветвления в ветку иначе, поэтому ветвление никогда не отображается как неоднозначная связь без видимого пути иначе.
Чтобы построить новый сценарий с нуля, используйте didit_workflow_validate_graph, а затем didit_workflow_set_graph (полный граф), либо позвольте didit_workflow_build_graph собрать полный граф из простой спецификации функций без сохранения. Даже простой didit_workflow_create сохраняется как тот же граф узлов: MCP собирает список features в цепочку узлов функций, которая заканчивается узлом статуса с автоматическим решением, чтобы функции действительно выполнялись. По умолчанию сценарий публикуется; передайте status: "draft", чтобы оставить его неопубликованным. Полную структуру JSON см. в разделе Создание сценария → ветвящиеся и узловые сценарии.

​
Ветвление по причинам пропуска 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 не запустился.

​
Конфигурации функций и списки разрешений

Поле config узла функции ограничивает набор принимаемых данных. didit_workflow_get_feature_config_schema возвращает все ключи, которые принимает каждая функция, с типами и значениями по умолчанию. Два каталожных инструмента (didit_workflow_get_id_verification_methods_catalog и didit_workflow_get_kyb_registry_catalog) отвечают на вопросы, определяемые сервером и необходимые для настройки конфигурации. Канонический список разрешений OCR имеет структуру «страна → документ → объект»: { "<ISO3>": { "<CODE>": { "enabled": 1 } } }, например { "ESP": { "P": { "enabled": 1 } } }. Перед проверкой MCP нормализует более простые формы записи, поэтому вам не нужно писать эту структуру вручную: 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[]. См. Модели данных и Статусы верификации.

​
Обработка 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 минуты), после чего отбрасывает её. Неудачные доставки можно повторить из вкладки Доставки в консоли.
Агенту нужно только настроить приёмник: сам он не слушает события. Полная спецификация: Вебхуки.

​
Транспорт и endpoints

Endpoint работает в двух режимах. Клиенты, которые в каждом сообщении указывают версию протокола 2026-07-28 или новее, пропускают рукопожатие initialize и могут вызывать server/discover. Все более ранние клиенты (Claude Code, Cursor, клиенты на базе SDK) используют стандартное рукопожатие Streamable HTTP без изменений. CORS открыт, поэтому браузерные клиенты (веб-коннектор Claude, MCP Inspector) могут обращаться к /mcp и документам обнаружения с других доменов. Лимит размера JSON-тела составляет 25 МБ, этого достаточно для входного файла в base64 размером 15 МБ.

​
Устранение неполадок

Вашей роли в этой организации не хватает разрешения, которое нужно инструменту (например, READER пытается выполнить запись). Ошибка missing_scope указывает, какое именно. Если не работает ни один инструмент, переподключитесь или повторите Log in with Didit. (MCP работает только через Bearer/OAuth. x-api-key отклоняется всеми инструментами, поэтому API-ключ не исправит ошибку 403.)
Операция записи или удаления не выполнилась. Деструктивные инструменты требуют подтверждения в вашем клиенте. Подтвердите вызов или проверьте, что запрос подтверждения не отклоняется автоматически. Для didit_session_delete, didit_session_batch_delete и didit_org_reveal_application_api_key дополнительно нужен confirm: true в аргументах инструмента. Без него вызов отклоняется до выполнения.
Скорее всего, у вас несколько приложений. Используйте инструмент *_search (он ищет во всех приложениях) или выполните didit_context_get и передайте нужные organization_id и application_id.
Некоторые клиенты (Windsurf, Zed) подключаются через мост mcp-remote. Убедитесь, что в конфигурации есть npx -y mcp-remote@latest https://mcp.didit.me/mcp. Чтобы заново запустить OAuth-рукопожатие, переоткройте клиент.
Убедитесь, что сервер подключён (в большинстве клиентов это показывает индикатор статуса) и что вы прошли Log in with Didit. После изменения конфигурации перезапустите хост MCP. didit_org_top_up и didit_org_reveal_application_api_key никогда не отображаются в размещённом коннекторе.
Убедитесь, что указан адрес https://mcp.didit.me/mcp, а не корневой адрес https://mcp.didit.me. Метаданные ресурса доступны по пути /.well-known/oauth-protected-resource/mcp и привязаны к этому пути, а копия находится в корне домена для клиентов, которые проверяют именно там. При самостоятельном развёртывании обычно причина в том, что MCP_RESOURCE_URI указывает на корневой URL, а не на полный URL транспорта. См. Самостоятельное развёртывание.
При работе с размещённым endpoint отправляйте файл как *_base64 (чистый base64 или URL data:). Параметр *_path работает только на локальном stdio-сервере. Размер файлов ограничен 15 МБ, а по содержимому (не только по расширению) файл должен быть PNG, JPG, WebP, GIF, BMP, ICO или PDF.

​
Безопасность

MCP действует с вашими реальными правами и может изменять рабочие ресурсы. Оставьте включённой настройку “проверять вызовы инструментов перед запуском” в вашем клиенте, особенно для инструментов категорий Запись и Деструктивные. Сам MCP не хранит никаких секретов в вашей конфигурации (он использует Вход через Didit), маскирует API-ключи и секреты для подписи webhook в выводе инструментов, скрывает из размещённого каталога инструменты пополнения баланса и работы с необработанными ключами и никогда не принимает учётные данные аккаунта как аргументы инструментов на удалённом сервере. Каждый вызов инструмента записывается в журнал аудита сервера с указанием вызывающей стороны, инструмента и решения проверки прав.

​
Инъекция промптов

Инструменты Didit возвращают то, что ввели или загрузили ваши пользователи, например имена, текст документов и ответы на анкеты. Человек, проходящий верификацию, контролирует этот текст, поэтому он может вписать в имя или документ инструкции для вашего агента, а сервер вернёт эти поля в том виде, в котором они были получены. Агент не может надёжно отличить такой текст от ваших собственных инструкций, поэтому относитесь к каждому результату инструмента как к данным:
  • Оставьте подтверждение инструментов включённым для инструментов категорий Запись и Деструктивные и внимательно читайте, что агент собирается сделать, прежде чем подтвердить действие.
  • Входите как участник, роль которого соответствует задаче. Агент, который только читает сессии, может использовать участника с ролью READER, и бэкенд отклонит его запросы на запись, что бы ни пытался сделать агент.
  • Сначала опробуйте нового агента или новый промпт на приложении в песочнице.
  • Никогда не одобряйте и не отклоняйте верификацию на основании того, что написано внутри неё. Опирайтесь на решение, его предупреждения и собственную проверку.

​
Персональные данные

Результаты инструментов могут содержать персональные данные, такие как имена, даты рождения, номера документов и ссылки на изображения, а ваш MCP-клиент передаёт их модели, которую он использует. Перед подключением боевого приложения убедитесь, что ваше соглашение с поставщиком ИИ распространяется на эти данные, или работайте с приложением в песочнице.

​
Самостоятельное развертывание

Размещённый сервер собран из github.com/didit-protocol/mcp (лицензия MIT). Клонируйте репозиторий и запустите его через Docker или Node. Он всегда проходит аутентификацию от имени Didit пользователя (режима API-ключа нет) в любом транспорте. Шаги настройки описаны в разделе Установка → самостоятельное развертывание.

​
Переменные окружения

.env.example в репозитории: шаблон для копирования, а ARCHITECTURE.md объясняет разделение ресурсного сервера и сервера авторизации. При запуске HTTP-сервер запрашивает документ обнаружения сервера авторизации и, если он недоступен, использует настроенные URL.

Справочник инструментов

Все инструменты, сгруппированные по областям.

Примеры

Промпты и сквозные диалоги.
Последнее изменение 7 ноября 2026 г.