# Trulioo KYB agent guide

Accurate as of 2026-09-10.

> **Early access.** Security controls are in place. Tool names, input fields, and
> documentation may change as we incorporate feedback.

Use this guide to help a developer connect Trulioo MCP, complete one business
verification in sandbox, and retrieve the report. Stay within the KYB workflow described
here. Do not introduce other product areas or undocumented tools.

The developer reference is <https://mcp.trulioo.com/developer/>. The live MCP connection is
the authority for available tools and their schemas.

## Your job

Guide the developer one step at a time:

1. Check whether Trulioo is already connected.
2. Connect through OAuth only when needed and confirm the session is in sandbox.
3. Select a configured KYB package, country, and safe test entity.
4. Confirm the selected test business and search only when the returned schema requires it.
5. Start verification and handle a non-terminal result.
6. Retrieve the completed report.

Explain what happened after each tool call. Do not silently move from sandbox to live.

## Step 1 - check the connection

Look for `trulioo_*` tools on your own connection.

- If none exist, continue to "Connect when needed."
- If they exist, call `trulioo_health` and `trulioo_capabilities`.
- Read the session mode from the response.
- Tell the developer whether the session is `sandbox` or `live` before running a
  verification.

If the health response reports an authentication error, ask the developer to reconnect
through OAuth. Do not guess why authentication failed.

## Step 2 - connect when needed

The hosted endpoint is:

```text
https://mcp.trulioo.com/mcp
```

Use the setup that matches the developer's client.

Claude Code:

```bash
claude mcp add --transport http trulioo https://mcp.trulioo.com/mcp
```

OpenAI Codex:

```bash
codex mcp add trulioo --url https://mcp.trulioo.com/mcp
```

For ChatGPT, Cursor, or another current MCP client, add the hosted endpoint as a remote
MCP server.

The client opens the OAuth consent flow. Ask the developer to choose sandbox. The client
manages registration, PKCE, tokens, refresh, and MCP session headers.

After the connection completes, call `trulioo_health` again and confirm `sandbox` before
continuing.

## Step 3 - understand the business input

Ask for the country of registration. Do not collect a business name or registration
identifier for the sandbox exercise before checking the safe test catalogue.

Call `config_discover_account` and `config_describe_context` before requesting additional
fields. Use their returned schemas and country requirements instead of recalling field
names from memory.

Select the package and country from those responses, then call
`config_list_test_entities` with the exact `package_id`, `country_code`, and
`surface: "kyb"` before any `kyb_search` or `kyb_verify` call.

Read the response before continuing:

- If `available` is `false`, read `availability` and `session`, explain why this
  credential has no runnable test catalogue, and stop. Do not retry or change
  `package_id`; reconnect with a sandbox credential when the session mode is wrong.
- If `seeding_request` is present, show its support request and stop. Repeating the call
  cannot seed an entity.
- Otherwise, choose one entry from `test_personas`. Use its `tool` exactly and pass its
  `data_fields` object unchanged. Do not copy `label`, `outcome`, `note`, or
  `example_prompt` into the verification input.

The selected persona is the business input for this sandbox exercise. Do not ask the
developer for arbitrary business data when a runnable test persona is available.
If the developer already has a known registration identifier, treat it as context only;
do not substitute it for the catalogue's exact `data_fields` in this sandbox run.

## Step 4 - confirm the test business

Show the selected persona's `label`, `outcome`, and `example_prompt`, then ask the
developer to confirm that this is the safe test business to run.

If the returned `tool` is `kyb_verify`, continue directly to verification. Call
`kyb_search` only when the returned persona or live tool schema explicitly requires a
search first; use the returned fields rather than reconstructing them from prose.
Use `kyb_registration_lookup` only when the schema directs you to confirm the selected
test entity's registration type or jurisdiction format; do not replace the catalogue's
returned value.

Read `search_summary`:

- `candidate_count` tells you how many candidates were found.
- `has_results` tells you whether search returned candidates.
- `top_matches` contains the candidates to review.

Do not use the top-level `RecordStatus` to decide whether search found a business.

If search returns:

- **No candidates:** ask the developer to check the country, spelling, and known
  registration details. Do not start verification.
- **One candidate:** show the candidate and ask the developer to confirm it.
- **Multiple candidates:** call `kyb_disambiguate_candidate`. A client with interactive
  selection can ask directly. Otherwise, show the numbered options and ask the developer
  to choose.

Never select the first or highest-ranked candidate without confirmation.

## Step 5 - verify the confirmed business

Call the selected persona's `tool` only after the test business has been confirmed. For
the KYB catalogue this is `kyb_verify`; pass the selected persona's exact `data_fields`
with the selected `package_id` and `country_code`.

Explain these response fields:

- `transaction_id` identifies this verification.
- `record_id` identifies the resulting record.
- `status` is `match`, `review`, or `nomatch`.
- `is_terminal` tells you whether processing is complete.
- `next_action` tells you what to do next.

Store the transaction and record identifiers. Branch on the response:

- `match`: continue to report retrieval when the result is terminal.
- `review`: pause automation and tell the developer that review is required.
- `nomatch`: stop the verification path and present `next_action`.
- `is_terminal: false`: continue to the polling step. Do not restart `kyb_verify`.

Errors are returned as typed results. Read the result before treating the call as failed.

### Handle a non-terminal result

Call `kyb_get_partial_result` with the transaction identifier when verification is still
running.

Show the developer the latest available fields, `is_terminal`, and `next_action`.
Continue polling only while the result is not terminal. Keep the retry loop bounded. If a
result contains `retry_after_seconds`, wait for that interval before retrying.

Do not interpret a non-terminal response as `nomatch`.

## Step 6 - retrieve the report

After verification is terminal, call `kyb_get_report`.

The response is either:

- A structured report.
- A PDF resource descriptor containing `record_id`, `report_available`, `content_type`,
  and `resource_uri`.

Tell the developer to store the report reference with the transaction identifier. If
`report_available` is false, report that clearly instead of inventing a download path.

For an older transaction, use `transaction_lookup` to resolve a TransactionID or
TransactionRecordID before retrieving its status or report.

## Move an approved integration to live

Complete the sandbox workflow first. For live verification, the developer receives a
Trulioo `client_id` and `client_secret`. These credentials are used only to bootstrap a
short-lived MCP access token.

Store the credentials in a secret manager or protected environment variables:

```bash
export TRULIOO_CLIENT_ID="your-client-id"
export TRULIOO_CLIENT_SECRET="your-client-secret"
```

Exchange them at the public token endpoint:

```bash
# curl sends Authorization: Basic base64(client_id:client_secret)
curl -sS -X POST https://mcp.trulioo.com/oauth/token \
  -u "$TRULIOO_CLIENT_ID:$TRULIOO_CLIENT_SECRET" \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials'
```

The response contains `access_token`, `token_type: Bearer`, and `expires_in`. Configure
the live MCP connection to send:

```text
Authorization: Bearer <access_token>
```

Use the bearer token on `https://mcp.trulioo.com/mcp`, initialize the MCP session, and
confirm that `trulioo_health` reports `live` before running a verification.

Never send `client_secret` to `/mcp`, put it in a URL, or expose it in logs or chat. The
bootstrap does not return a refresh token. Re-run it after token expiry or a `401`
response.

## Common problems

- **Expected tool is missing:** call `trulioo_capabilities` and
  `config_discover_account`. Use only tools returned by the connection.
- **Sandbox authentication error:** reconnect through the browser OAuth flow.
- **Live authentication error:** check the `client_id` and `client_secret`, then re-run
  the `/oauth/token` bootstrap. Do not retry rejected credentials in a loop.
- **Search returned no candidates:** confirm country, spelling, and registration details.
- **Search returned several candidates:** use `kyb_disambiguate_candidate`; do not guess.
- **Verification is still running:** call `kyb_get_partial_result`; do not restart it.
- **Status is `review`:** pause and route the result for human review.
- **Usage limit response:** follow `retry_after_seconds`.
- **Report is unavailable:** keep the transaction and record identifiers and state that
  the report is not yet available.

## Rules for the guiding agent

- Use only the KYB tools and support tools named in this guide.
- Call `tools/list` when a tool name or schema is uncertain.
- Do not translate examples from a REST API into MCP requests.
- Do not invent input fields, result fields, candidates, statuses, or reports.
- Do not expose bearer tokens or regulated business data in logs or chat summaries.
- Confirm the session mode before verification.
- Ask the developer to confirm the business before calling `kyb_verify`.
- Keep the developer informed about the current step and the next action.