Руководство

Описание#

MCP (Model Context Protocol) — канал интеграции для AI-агентов кодирования. Наш MCP-сервер позволяет агенту в Claude Code, Cursor, Codex или любом другом совместимом со спецификацией клиенте просматривать подписки, проектировать Flow и smoke-тестировать сессии от имени клиента — без написания вручную ни одной строчки связующего кода.

Сервер работает по MCP поверх Streamable HTTP по адресу https://kyc.biometric.kz/mcp/, аутентификация — по API-ключу организации (Authorization: Bearer <key> или X-Org-API-Key: <key>).

Лимит запросов

На /mcp/* действует лимит 60 запросов в минуту на один IP. Лимит применяется до аутентификации, поэтому также ограничивает анонимные пробы и попытки подбора админ-ключа. При превышении возвращается HTTP 429 Too Many Requests с заголовком Retry-After (в секундах) и заголовками X-RateLimit-Limit / X-RateLimit-Remaining. Подождите указанное время и повторите — корректно работающие агенты не приближаются к этому лимиту.

MCP — только на этапе интеграции

MCP-сервер — это канал интегратора: используется один раз, агентом, чтобы настроить Flow клиента и подключить его бэкенд. Это не runtime-канал: конечные пользователи в продакшене никогда не обращаются к MCP. Все вызовы на одного пользователя (создание сессии, получение результата) идут через обычный REST API.

Не пишите mcp.call_tool(...) в контроллерах, обработчиках маршрутов или фоновых задачах. Для этого используйте REST-интеграции (Flow Remote, Flow Widget, Flow WebView).

sequenceDiagram
    title MCP-интеграция — настройка агентом, runtime через REST

    participant AGENT as Агент-интегратор<br/>(Claude Code / Cursor / Codex)
    participant BIO as Biometric.Vision (KYC)
    participant APP as Приложение клиента<br/>(бэкенд + фронтенд)
    participant USER as Конечный пользователь

    note over AGENT: Предусловие:<br/>API-ключ организации уже получен

    note over AGENT,BIO: Шаг 1 — Подключение (MCP)
    AGENT->>+BIO: initialize (Streamable HTTP)<br/>Authorization: Bearer <org_api_key>
    BIO-->>-AGENT: список инструментов и ресурсов

    note over AGENT,BIO: Шаг 2 — Открытие возможностей (MCP)
    AGENT->>+BIO: get_organization, list_subscription_technologies
    BIO-->>-AGENT: статус организации + лицензированные коды технологий

    note over AGENT,BIO: Шаг 3 — Проектирование (MCP)
    AGENT->>+BIO: create_flow(technology_ids, configs)
    BIO-->>-AGENT: { id, api_key, technology_configs }

    note over AGENT,BIO: Шаг 4 — Smoke-тест (MCP, разовый)
    AGENT->>+BIO: create_flow_session + прохождение сессии
    AGENT->>BIO: get_flow_session_light_result(session_id)
    BIO-->>-AGENT: FINISHED / FAILED

    note over AGENT,APP: Шаг 5 — Встраивание прод-кода
    AGENT->>APP: Добавить POST /kyc/start + GET /kyc/return<br/>с использованием api_key потока

    note over APP,USER: Дальше — только REST
    USER->>+APP: регистрация / запуск верификации
    APP->>+BIO: POST /api/v1/flows/session/create/
    BIO-->>-APP: { session_id }
    APP->>USER: редирект на https://remote.biometric.kz/flow/{session_id}
    USER->>BIO: прохождение интерфейса верификации
    BIO-->>APP: GET /api/v1/flows/session/result/light/
    APP->>USER: применение решения

Этапы#

1. Установка MCP-сервера в агенте#

Зарегистрируйте сервер в том AI-агенте, которым пользуется интегратор. Блок конфигурации одинаков во всех клиентах:

{
  "mcpServers": {
    "kyc": {
      "url": "https://kyc.biometric.kz/mcp/",
      "headers": {
        "Authorization": "Bearer <PASTE_ORG_API_KEY_HERE>"
      }
    }
  }
}

Куда вставлять:

Claude CodeCursorCodex / OpenCode / Continue / AiderClaude Desktop

Либо в глобальный конфиг пользователя ~/.claude.json, либо в .mcp.json в корне репозитория проекта. Или через консоль:

claude mcp add kyc https://kyc.biometric.kz/mcp/ \
  --header "Authorization: Bearer <PASTE_ORG_API_KEY_HERE>"

Settings → MCP → «Add new MCP server» → вставьте JSON. Либо отредактируйте ~/.cursor/mcp.json напрямую.

У каждого агента есть свой конфиг «MCP servers» (JSON или TOML). Найдите его в документации агента и вставьте тот же блок mcpServers.kyc.

~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows.

Перезапуск после правки

Большинству агентов нужен перезапуск (или перезагрузка MCP-сервера), прежде чем появится новый список инструментов.

Откуда взять API-ключ организации

API-ключ организации — тот же секрет, которым вы аутентифицируетесь в API для Backend интеграции. Скопируйте его из Кабинета: Настройки -> Данные компании -> API KEY. Он остаётся в конфиге агента-интегратора — никогда не разворачивайте его в продакшен.

2. Проверка подключения#

Прежде чем что-либо делать, выполните проверку подключения, чтобы последующие сбои не были двусмысленными. Агент-интегратор вызывает два инструмента:

get_organization(api_key="<API-ключ организации>") — подтверждает идентичность. В ответе есть поле status: организации TEST / DEMO — это песочница; PRODUCTION работает против боевых интеграций.
list_subscription_technologies() — перечисляет коды технологий, на которые у организации есть подписка для встраивания в Flow.

Если любой из вызовов завершился ошибкой:

Симптом	Вероятная причина
`401 Unauthorized` (`WWW-Authenticate: Bearer realm="kyc-mcp"`)	Неверный или просроченный API-ключ организации.
`429 Too Many Requests` (`Retry-After: <секунды>`)	Сработал лимит запросов на один IP (60 запросов в минуту). Подождите указанное число секунд и повторите.
`get_organization` не появился в списке инструментов агента	Агент не перезагрузился после правки конфига.
Connection refused / DNS-ошибка	Опечатка в URL, отсутствует схема, неверный порт.

3. Проектирование и создание Flow#

Flow — это упорядоченный конвейер технологий проверки для конечного пользователя. проходит. Агент-интегратор проектирует его один раз через MCP; с тех пор, каждый конечный пользователь получает сеанс с этим потоком через REST.

Перед формированием вызова create_flow прочитайте четыре справочных ресурса:

URI	Что даёт
`kyc://reference/flow-config-defaults`	Значения по умолчанию для конфига уровня Flow (URL-редиректы, отпечаток устройства, QR, mobile-only и т. д.).
`kyc://reference/technology-config-defaults`	Значения по умолчанию для каждого конфига технологии, ключ — имя поля конфига (`liveness_config`, `edocument_config`, …).
`kyc://reference/document-recognition-countries`	`id` стран, допустимые в `doc_recognition_config.allowed_countries`.
`kyc://reference/document-recognition-document-types`	`id` типов документов, допустимые в `doc_recognition_config.allowed_document_types`.

Описание самих технологий и регионы их доступности см. в разделе Технологии.

Типичный вызов create_flow с переопределением значений по умолчанию для каждой технологии:

// MCP-инструмент: create_flow
{
  "request_data": {
    "name": "kyc-prod-v1",
    "display_name": "KYC verification",
    "technology_ids": [
      "<liveness-core-uuid>",
      "<edocument-uuid>",
      "<face2face-uuid>"
    ],
    "flow_config": {
      "success_redirect_url": "https://myapp.example.com/kyc/return?outcome=success",
      "failure_redirect_url": "https://myapp.example.com/kyc/return?outcome=failure",
      "show_qr": true,
      "always_mobile": false
    },
    "technology_configs": {
      "liveness_config": {
        "max_attempts": 3,
        "eye_open_check": true,
        "mask_attack_check_required": true
      },
      "edocument_config": {
        "document_type": "IdentityCard",
        "max_retry_attempts": 3,
        "allow_retry": true
      },
      "face2face_config": {
        "threshold": 0.85,
        "fail_on_several_faces": true
      }
    }
  }
}

Замечания:

technology_ids — это UUID, которые вернул list_subscription_technologies, а не короткие коды.
success_redirect_url и failure_redirect_url — это сигнал завершения, который вы подключите в приложении клиента на Шаге 5. Параметр ?outcome=... в URL — только подсказка; никогда не считайте его доказательством исхода.
Если хотя бы для одной технологии не указан явный technology_configs, create_flow сначала пришлёт один «переопределить значения по умолчанию для технологий?» elicitation:
- Decline — для каждой технологии используются значения по умолчанию платформы, дальнейшие per-tech-промпты не отправляются.
- Accept — далее для каждой технологии отправляется типизированный промпт; declined-промпт оставляет значения по умолчанию для этой технологии.
- Cancel в любой момент прерывает вызов с ошибкой "create_flow cancelled by user.".
Если technology_configs задан явно для каждой технологии — ни одного elicitation не будет. Не-интерактивные клиенты (CI, headless-агенты) могут вызвать create_flow, отказывая (decline) на каждом промпте.

В ответе вы получите свежесозданный Flow. Для дальнейших шагов важны два поля:

id — UUID Flow.
api_key — API-ключ Flow. Это секрет, который будет использоваться REST-вызовами в продакшене на Шаге 5. Относитесь к нему как к паролю от базы данных.

Flow с цифровой подписью нужно собирать в Кабинете

Если list_subscription_technologies вернёт технологию с кодом DSI, DSN или DSS, не включайте её id в technology_ids при вызове create_flow. Flow с цифровой подписью имеют ограничения со стороны удостоверяющего центра и идентификации подписанта, которые MCP-сценарий создания не валидирует — собранный через MCP Flow будет тихо некорректным.

Соберите Flow с цифровой подписью в Кабинете. После этого интегратор может получить его id через list_flows(), прочитать через get_flow(flow_id=…) и использовать его api_key для подключения REST в продакшене.

4. Smoke-тест Flow#

Перед тем как встраивать REST-код в приложение клиента, убедитесь, что новый Flow работает целиком:

Создайте разовую сессию через MCP: create_flow_session(flow_api_key="<api_key потока>") → возвращает { session_id, technologies }.
Пройдите интерфейс верификации в браузере по адресу https://remote.biometric.kz/flow/<session_id>.
Получите результат через MCP: get_flow_session_light_result(session_id="<session_id>"). Проверьте status (на чистом прохождении ожидается FINISHED), overall_result, каждый блок результата по технологиям, и failure_reasons[] при сбое.

После smoke-теста роль MCP в интеграции практически завершена.

5. Встраивание Flow в приложение клиента#

Трафик в продакшене идёт через REST. Агент-интегратор пишет в репозитории клиента два бэкенд-обработчика и один фронтенд-хук:

POST /kyc/start — вызывает POST https://kyc.biometric.kz/api/v1/flows/session/create/ с телом { "api_key": "<api_key потока>" }, сохраняет полученный session_id по id конечного пользователя и возвращает фронтенду URL-редирект или session_id.
Фронтенд открывает интерфейс верификации — выберите Flow Remote для веба, Flow Widget для встраивания в SPA или Flow WebView для нативного мобильного приложения.
GET /kyc/return (или POST для пинга от виджета / webview) — достаёт session_id из серверной привязки (не из query-строки) и вызывает GET https://kyc.biometric.kz/api/v1/flows/session/result/light/?session_id=...&flow_api_key=.... Ответ — авторитативное решение.

Полные форматы REST-запросов, примеры кода и таблица session.status находятся в Flow Remote.

MCP-инструменты#

Инструмент	Назначение
`get_organization(api_key)`	Идентичность и статус организации.
`list_subscription_technologies()`	Технологии, которые организация может встроить в Flow, с правилами сочетания.
`list_flows(limit, offset)`	Постраничный список Flow, видимых вызывающему.
`get_flow(flow_id)`	Один Flow с его `flow_config` и конфигом каждой технологии.
`create_flow(request_data)`	Создать новый Flow (диалоговый — использует elicitation-ы для переопределений по технологиям).
`update_flow(request_data)`	PATCH-обновление существующего Flow.
`create_flow_session(flow_api_key)`	Smoke-тест сессии для Flow (только на этапе интеграции).
`get_flow_session(session_id)`	Структурированный вид сессии без URL медиа.
`get_flow_session_light_result(session_id)`	Вид сессии с короткоживущими подписанными URL для снятых медиа.
`update_flow_session_status(session_id, request_data)`	Вручную перевести сессию в `APPROVED` или `DECLINED` (для внутренних инструментов ревью).
`list_flow_session_reviews(session_id)`	Аудит-журнал ревью сессии.
`create_flow_session_review(session_id, request_data)`	Добавить свободную `MESSAGE`-запись ревью к сессии.

MCP-ресурсы#

URI	Назначение
`kyc://reference/flow-config-defaults`	Текущие значения по умолчанию для каждого поля `flow_config`.
`kyc://reference/technology-config-defaults`	Текущие значения по умолчанию для каждого блока конфига технологии.
`kyc://reference/document-recognition-countries`	Активные страны, допустимые в `doc_recognition_config.allowed_countries`.
`kyc://reference/document-recognition-document-types`	Активные типы документов, допустимые в `doc_recognition_config.allowed_document_types`.

Интеграция AI-агентом одним промптом#

Весь описанный выше путь — подключение → открытие возможностей → проектирование → smoke-тест → встраивание — оформлен как готовый системный промпт, который интегратор может передать AI-агенту кодирования. Вставьте его в Claude Code / Cursor / Codex, и агент проведёт всю интеграцию без избыточного ручного контроля.

См. Промпт для AI-интеграции.