Обзор и подключение

MCP (Model Context Protocol) позволяет AI-агенту интегратора работать с Biometric.Vision: просматривать подписки организации, создавать и изменять Workflow, а также проводить разовый smoke-тест сессии. MCP-сервер совместим с Claude Code, Cursor и Codex.

В интерфейсе и документации v2 используется термин Workflow. В названиях MCP-инструментов и полей API сохраняется термин flow: например, create_flow, flow_id и flow_config.

Сервер работает по MCP поверх Streamable HTTP:

https://kyc.biometric.vision/mcp/

Для аутентификации используется API-ключ организации в заголовке Authorization: Bearer <YOUR_ORG_API_KEY>. Также поддерживается заголовок X-Org-API-Key: <YOUR_ORG_API_KEY>.

sequenceDiagram
    participant AGENT as AI-агент интегратора
    participant KYC as Biometric.Vision
    participant APP as Приложение клиента
    participant USER as Конечный пользователь

    note over AGENT,KYC: Разовая настройка через MCP
    AGENT->>KYC: Проверить организацию и подписки
    AGENT->>KYC: Создать или изменить Workflow
    AGENT->>KYC: Создать и проверить тестовую сессию

    note over APP,KYC: Production через REST API
    USER->>APP: Начать проверку
    APP->>KYC: Создать сессию Workflow
    KYC-->>APP: session_id
    APP-->>USER: Открыть Remote, Widget или WebView
    APP->>KYC: Получить результат сессии
    KYC-->>APP: Результаты технологий

1. Получение API-ключа организации¶

Скопируйте API-ключ организации из личного кабинета: Настройки → Данные компании → API KEY.

Ключ организации даёт MCP-серверу доступ к настройкам организации. Храните его в локальной конфигурации AI-агента, не добавляйте в репозиторий и не передавайте в production-приложение. Для REST-интеграции приложение использует отдельный API-ключ Workflow, который возвращает create_flow.

2. Подключение MCP-сервера¶

claude mcp add --transport http --scope local kyc \
  https://kyc.biometric.vision/mcp/ \
  --header "Authorization: Bearer <YOUR_ORG_API_KEY>"

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

[mcp_servers.kyc]
url = "https://kyc.biometric.vision/mcp/"
bearer_token_env_var = "KYC_ORG_API_KEY"

export KYC_ORG_API_KEY="<YOUR_ORG_API_KEY>"

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

После подключения вызовите два инструмента:

1. get_organization(api_key="<YOUR_ORG_API_KEY>") — проверяет организацию. Поле status показывает окружение: TEST, DEMO или PRODUCTION.
2. list_subscription_technologies() — возвращает технологии, доступные организации, включая их id, code и name.

Если подключение не работает:

4. Проектирование Workflow¶

Workflow задаёт набор и порядок технологий, которые проходит конечный пользователь. Перед созданием Workflow:

1. Получите доступные технологии через list_subscription_technologies().
2. Определите бизнес-сценарий, страны пользователей, необходимые проверки и допустимый уровень сложности для пользователя.
3. Согласуйте с владельцем продукта состав и порядок технологий.
4. Прочитайте справочные MCP-ресурсы с актуальными значениями по умолчанию и допустимыми идентификаторами.

5. Создание Workflow¶

Передавайте в technology_ids UUID из ответа list_subscription_technologies() в требуемом порядке выполнения. Короткие коды технологий для этого поля не подходят.

Минимальный вызов:

{
  "request_data": {
    "name": "kyc-production",
    "display_name": "KYC verification",
    "technology_ids": [
      "<TECHNOLOGY_UUID_1>",
      "<TECHNOLOGY_UUID_2>"
    ],
    "flow_config": {
      "success_redirect_url": "https://example.com/kyc/return",
      "failure_redirect_url": "https://example.com/kyc/return"
    }
  }
}

Если конфигурация указана не для всех технологий, create_flow предложит выбрать между настройками по умолчанию и индивидуальными переопределениями:

• decline — применить значения по умолчанию ко всем технологиям;
• accept — последовательно настроить технологии;
• cancel — отменить создание Workflow.

Если передать technology_configs для всех технологий и задать display_name, дополнительные вопросы не появятся. Ответ create_flow содержит:

• id — UUID Workflow;
• api_key — API-ключ Workflow для создания production-сессий через REST API.

Сохраните api_key в менеджере секретов backend. Не передавайте его в браузер или мобильное приложение.

6. Smoke-тест¶

Перед подключением production-кода проверьте Workflow целиком:

1. Вызовите create_flow_session(flow_api_key="<WORKFLOW_API_KEY>") и сохраните session_id.
2. Пройдите проверку по адресу https://remote.biometric.vision/flow/<session_id>.
3. Вызовите get_flow_session_light_result(session_id="<SESSION_ID>").
4. Проверьте status, overall_result, результаты каждой технологии и failure_reasons при ошибке.

После smoke-теста подключите Workflow к приложению через Remote Workflow, Widget Workflow или WebView Workflow. Production-приложение создаёт сессии и получает результаты через REST API.

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

Готовая инструкция для агента находится на странице Промпт для AI-интеграции.