Overview and setup

MCP (Model Context Protocol) lets an integrator's AI agent work with Biometric.Vision: inspect the organization's subscriptions, create and update Workflows, and run a one-time session smoke test. The MCP server works with Claude Code, Cursor, and Codex.

The v2 interface and documentation use the term Workflow. MCP tool and API field names retain flow, for example create_flow, flow_id, and flow_config.

The server uses MCP over Streamable HTTP:

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

Authenticate with the organization API key in the Authorization: Bearer <YOUR_ORG_API_KEY> header. The X-Org-API-Key: <YOUR_ORG_API_KEY> header is also supported.

sequenceDiagram
    participant AGENT as Integrator AI agent
    participant KYC as Biometric.Vision
    participant APP as Customer application
    participant USER as End user

    note over AGENT,KYC: One-time setup through MCP
    AGENT->>KYC: Verify organization and subscriptions
    AGENT->>KYC: Create or update Workflow
    AGENT->>KYC: Create and inspect test session

    note over APP,KYC: Production through REST API
    USER->>APP: Start verification
    APP->>KYC: Create Workflow session
    KYC-->>APP: session_id
    APP-->>USER: Open Remote, Widget, or WebView
    APP->>KYC: Retrieve session result
    KYC-->>APP: Technology results

1. Get the organization API key¶

Copy the organization API key from the dashboard: Settings → Company details → API KEY.

The organization key gives the MCP server access to the organization's settings. Keep it in the AI agent's local configuration, do not commit it to the repository, and do not pass it to the production application. The application uses a separate Workflow API key for REST integration, returned by create_flow.

2. Connect the MCP server¶

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. Verify the connection¶

After connecting, call two tools:

1. get_organization(api_key="<YOUR_ORG_API_KEY>") verifies the organization. The status field identifies the environment as TEST, DEMO, or PRODUCTION.
2. list_subscription_technologies() returns the technologies available to the organization, including their id, code, and name.

If the connection does not work:

4. Design the Workflow¶

A Workflow defines the technologies an end user completes and their order. Before creating a Workflow:

1. Retrieve the available technologies with list_subscription_technologies().
2. Define the business case, user countries, required checks, and acceptable user friction.
3. Confirm the technology composition and order with the product owner.
4. Read the MCP reference resources for current defaults and valid identifiers.

5. Create the Workflow¶

Pass the UUIDs returned by list_subscription_technologies() to technology_ids in execution order. Short technology codes are not valid for this field.

Minimal call:

{
  "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"
    }
  }
}

If configurations are not supplied for every technology, create_flow asks whether to use defaults or provide individual overrides:

• decline applies defaults to every technology;
• accept configures the technologies in sequence;
• cancel aborts Workflow creation.

If technology_configs is supplied for every technology and display_name is set, no additional prompts appear. The create_flow response contains:

• id: the Workflow UUID;
• api_key: the Workflow API key used to create production sessions through the REST API.

Store api_key in the backend secret manager. Never pass it to a browser or mobile application.

6. Run a smoke test¶

Before wiring production code, test the complete Workflow:

1. Call create_flow_session(flow_api_key="<WORKFLOW_API_KEY>") and save the session_id.
2. Complete verification at https://remote.biometric.vision/flow/<session_id>.
3. Call get_flow_session_light_result(session_id="<SESSION_ID>").
4. Inspect status, overall_result, each technology result, and failure_reasons if the session failed.

After the smoke test, connect the Workflow to the application through Remote Workflow, Widget Workflow, or WebView Workflow. The production application creates sessions and retrieves results through the REST API.

MCP tools¶

A ready-to-use agent instruction is available on the AI integration prompt page.