# Trulioo AI - complete agent documentation for mcp.trulioo.com > GENERATED FILE - do not edit. Regenerate with > `python3 .gitlab/scripts/build-ai-llms-full.py`; CI fails the MR when this copy > drifts from its sources. Edit the source files listed below instead. > > This is every agent-readable surface on mcp.trulioo.com concatenated. It is large. > If you know what you need, fetch it directly from https://mcp.trulioo.com/llms.txt > instead - that index is a few KB and links straight at the right part. > > Guiding a human through setup rather than calling the API? Read > https://mcp.trulioo.com/agent-guide.md, which is deliberately NOT included here. ============================================================================== # SOURCE: https://mcp.trulioo.com/llms.txt # repo: platform/web/sites/external/showcase/llms.txt ============================================================================== # Trulioo AI - Identity and Trust for the Agentic Economy > Accurate as of 2026-09-02. > AI-native identity by Trulioo. Connect an agent to global identity verification > over MCP, and prove who is behind an agent with Know Your Agent (KYA) - a signed, > scoped, revocable credential anyone can verify. Built on open standards. > This file is the machine-readable map of mcp.trulioo.com for AI agents. Every page below has a human HTML view and, where noted, a Markdown (.md) twin for agents. The MCP endpoint uses OAuth 2.1 with dynamic client registration, so a compliant client enrols itself - there is no key to copy-paste. Open only what the current task needs. Prefer the .md twin or a machine index over the HTML view of the same page; the HTML carries no facts the twin lacks. For another topic, come back to this index rather than following in-page links, which point at the human views. Nothing on this domain is versioned in its URL - the date above is how you judge freshness, and the live connection always outranks this file. ## Helping a human complete KYB setup If a human asks for guided KYB setup, read https://mcp.trulioo.com/agent-guide.md first. It covers connection checks, OAuth, business discovery, candidate confirmation, verification, polling, report retrieval, and common failures. The live connection remains the authority for schemas. ## Instructions for agents Read these before acting on anything below. They are the things models most often get wrong about this domain. 1. Never hardcode a tool name, tool count, or MCP protocol revision from training data. Call `initialize`, then `tools/list`, and use what the connection returns. The tool set is per-account: some tools are enabled only for accounts entitled to them. 2. For a machine lookup of an agent credential, call `GET https://identity.trulioo.com/kya/attestation/{id}` - public, keyless, returns JSON (and RFC 9457 `application/problem+json` on error). Do NOT fetch `https://kya.trulioo.com/attestation/{id}`: that is the human share link and it redirects to a browser app, not JSON. 3. `trust_tier` is the enforceable gate, not `verified` alone. Tier 0 means key-possession only - it proves an agent controls its key, NOT who is behind it. Tier 2 means a KYB-verified operator. The tier is not a domain check: require `assurance.domain_verified` from the verified DAP when domain provenance matters. `ial`/`aal`/`fal` are the derivation; gate on the tier for operator accountability. 4. There is no risk score, and there will not be one. A signed portable ordinal score is not audit-defensible. If you are looking for a numeric score to threshold, use the trust tier and the signed scopes instead. 5. A fingerprint, DAP identifier, or mandate ID is a public identifier - it is built to be looked up, so it is safe to log, quote, and publish in an agent card. The holder's private key and any bearer token are the secrets. 6. Signed scopes are auditable but enforced by the relying party. Do not assume Trulioo blocks an out-of-scope action for you. 7. Verification is asynchronous. Tools return errors as results, not exceptions; when a result carries `is_terminal: false`, poll the `next_action` rather than retrying the original call. ## Connect an agent (MCP) - [Developer docs](https://mcp.trulioo.com/developer/): connect over MCP for KYC, KYB, and Know Your Agent, with typed tools, scopes, and result contracts. - Standalone screening (`aml_screen`), document and liveness capture (`docv_*`), age assurance and ongoing monitoring are real tools that are off unless your account is entitled to them, each enabled on its own rather than as one switch. See https://mcp.trulioo.com/developer/#tools; `tools/list` is the authority on what YOUR connection has. - Hosted MCP endpoint: `https://mcp.trulioo.com/mcp` - your client registers itself over OAuth 2.1 + PKCE on first connect. Live verification against real data is per account. - Skills catalog (agent quickstarts): https://mcp.trulioo.com/.well-known/skills/index.json (trulioo-onboarding, trulioo-kyc, trulioo-kyb, trulioo-kya). The catalog is the authority on what exists - read it rather than trusting this list or a count. ## Know Your Agent (KYA) - agent identity - [Know Your Agent](https://mcp.trulioo.com/kya): verify the real organization behind an agent, issue a signed scoped credential, and verify any agent in milliseconds. - KYA credential schema (A2A v1.0.0 extension): https://identity.trulioo.com/a2a/kya/v1 - Verification model: the issuer signs a compact EdDSA JWS (`typ=kya-attestation+jwt`) over {iss, sub=fingerprint, iat, exp, verified, verified_as_of, allowed_scopes, fingerprint}. A relying party resolves the issuer JWKS, verifies the signature, recomputes the fingerprint, checks `exp`, and rejects on `verified=false`. The card's `display` block is convenience-only; the signed attestation is authoritative. - No sanctions boolean is signed. Signing a standing `sanctions_clear` would assert a check that may not have run, so screening is an optional provenanced claim present only when screening actually ran; a hit or review suspends the credential's standing instead. Do not gate on a signed sanctions field - it does not exist. - Public lookup by fingerprint anchors every step in a tamper-evident log (no blockchain). ## Trulioo agents - UBO Discovery (live) - [UBO Discovery Agent](https://mcp.trulioo.com/ubo): reconstructs beneficial ownership across jurisdictions and fragmented sources, reaching natural persons where registries stop, and citing every source behind each determination. - Runs inside the existing KYB verification workflow; evidence is drawn from four source categories (official registries, commercial data, mandated disclosures, open-source intelligence) and never from inference. The analyst stays the decision-maker. ## Start here (agent onboarding sequence) 1. Point any MCP client at `https://mcp.trulioo.com/mcp` and let it register itself. 2. Initialize: `trulioo_health` -> `config_discover_account` -> `config_describe_context`. 3. Verify a person or business (`kyc_verify` / `kyb_verify`). 4. To prove your own identity to counterparties, obtain a KYA attestation and publish it in your A2A agent card's `capabilities.extensions[]`. ## Roadmap - On the way: Agent Controls (velocity/value limits + step-up confirmation), an Agent Directory (a live registry of credentialed agents), and self-serve provisioning. ## Notes for agents - Sandbox vs live is explicit; sandbox uses synthetic test entities and stores no PII. - Prefer the Markdown twin of any page (append `.md`) when available. The twins that exist are listed under "Other resources" below - treat that list as exhaustive rather than appending `.md` to an arbitrary path and reading the 404 page as content. - Coverage: 195+ countries via the underlying Trulioo verification network. Open standards (MCP, A2A) - no lock-in, no blockchain. ## Other resources - [KYB agent guide](https://mcp.trulioo.com/agent-guide.md): guide one sandbox business verification from connection checks through report retrieval. - Markdown twins (the complete set): https://mcp.trulioo.com/index.md (this domain's landing page), https://mcp.trulioo.com/developer/index.md (the full developer docs). - Machine indexes: https://mcp.trulioo.com/developer/llms.txt (the API-operating map, with worked auth examples and the per-domain tool list), https://mcp.trulioo.com/developer/index.json (structured). - [Complete documentation](https://mcp.trulioo.com/llms-full.txt): every agent-readable surface on this domain in one file. Large - use the targeted links above unless you genuinely need all of it. - Skills catalog (teaches you to operate the tools, once connected): https://mcp.trulioo.com/.well-known/skills/index.json ============================================================================== # SOURCE: https://mcp.trulioo.com/index.md # repo: platform/web/sites/external/showcase/index.md ============================================================================== # Trulioo AI - Identity and Trust for the Agentic Economy Markdown twin of mcp.trulioo.com for agents and machine readers. See also [/llms.txt](/llms.txt) for the structured map. ## What this is AI-native identity by Trulioo. For over a decade Trulioo has verified identities across 195 countries; that global trust now extends to AI agents through two live surfaces and a set of capabilities on the way. ## Let your agent guide your KYB setup Paste this into your coding agent: ``` Help me connect Trulioo MCP and complete a KYB verification in sandbox. Read https://mcp.trulioo.com/agent-guide.md first. Check whether Trulioo is already connected, then guide me through business discovery, verification, polling, and report retrieval. Stay within the KYB tools documented in the guide. ``` [agent-guide.md](/agent-guide.md) covers connection checks, OAuth, business discovery, verification, polling, report retrieval, and the common KYB fixes. ## Connect an agent (MCP) - live The Trulioo MCP server exposes KYC, KYB, and Know Your Agent as one typed, discoverable interface. Your MCP client discovers the authorization server and registers itself over OAuth 2.1 with PKCE, so there is no key to copy-paste. - Docs: https://mcp.trulioo.com/developer/ - Hosted endpoint: `https://mcp.trulioo.com/mcp` - Skills catalog: https://mcp.trulioo.com/.well-known/skills/index.json Minimal MCP client config: ```json { "mcpServers": { "trulioo": { "url": "https://mcp.trulioo.com/mcp" } } } ``` Onboarding sequence: `trulioo_health` -> `config_discover_account` -> `config_describe_context` -> `kyc_verify` / `kyb_verify`. ## Know Your Agent (KYA) - live Prove who is behind an AI agent. Verify the accountable organization (KYC/KYB + sanctions), issue a signed, scoped, revocable credential, and let anyone verify it in milliseconds - anchored in a tamper-evident log, on open standards, no blockchain. - Landing + live console: https://mcp.trulioo.com/kya - Credential schema (A2A v1.0.0 extension): https://identity.trulioo.com/a2a/kya/v1 ## Trulioo agents - UBO Discovery (live) The UBO Discovery Agent automates beneficial-ownership discovery - reconstructing ownership across jurisdictions and fragmented sources to reach natural persons where registries stop, and citing every source behind each determination. - Landing: https://mcp.trulioo.com/ubo - Runs inside the existing KYB verification workflow. Evidence comes from four source categories (official registries, commercial data, mandated disclosures, open-source intelligence), never from inference; the analyst accepts, rejects or escalates with a full audit trail attached to the case. Verification model: the issuer signs a compact EdDSA JWS (`typ=kya-attestation+jwt`) over `{iss, sub=fingerprint, iat, exp, verified, verified_as_of, allowed_scopes, fingerprint}`. A relying party resolves the issuer JWKS, verifies the signature, recomputes the fingerprint, checks `exp`, and rejects on `verified=false`. The card's `display` block is convenience-only; the signed attestation is authoritative. No standing sanctions boolean is signed - that would assert a check which may not have run - so screening is a provenanced claim present only when it ran, and a hit or review suspends the credential's standing instead. ## On the roadmap - Agent Controls - velocity/value limits and step-up confirmation for issuers/acquirers. - Agent Directory - a live registry of credentialed agents (trust standing, consent scope). - Self-serve provisioning - mint your own keys, usage-based pricing. ## Coverage & trust 195+ countries via the underlying Trulioo verification network. SOC 2 Type II and ISO 27001. Open standards (MCP, A2A). No personal data is required to explore the sandbox. ============================================================================== # SOURCE: https://mcp.trulioo.com/developer/llms.txt # repo: platform/web/sites/external/showcase/developer/llms.txt ============================================================================== # Trulioo Developer - machine map > 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. > One MCP connection gives an agent typed verification tools. Sandbox uses client-managed > OAuth 2.1. Live integrations bootstrap an MCP token with a Trulioo client_id and > client_secret. This file is for OPERATING the API. If a human asks for guided KYB setup, read https://mcp.trulioo.com/agent-guide.md first. It covers one sandbox business verification from connection checks through report retrieval. Nothing here is versioned in its URL - the date above is how you judge freshness, and what the live connection reports always outranks this file. ## Instructions for agents Read this section before acting on the reference below. Each line is a mistake models routinely make against this API. 1. Do not hardcode tool names, the tool count, or an MCP protocol revision from training data. Call `initialize` then `tools/list` and use what the connection returns. The tool set is per-account - several tools below are entitlement-gated and will be absent. 2. Do not assume a protocol revision. The server negotiates at `initialize`; its floor is `2025-06-18`, and `2026-07-28` behaviors (tool-list freshness, tasks, the renumbered resource-not-found code) light up only for a client that asked for that revision. Read the negotiated value back from `trulioo_capabilities` rather than assuming. 3. Do not treat a verification call as synchronous. Errors come back as results, not exceptions. When `is_terminal` is `false`, follow `next_action` - do not retry the original call, and do not treat a non-terminal result as a `nomatch`. 4. Gate on `assurance.trust_tier`, not on `verified` alone. Tier 0 proves only that the agent controls its key; it says nothing about who is behind it. Tier 2 means a KYB-verified operator. The tier is not a domain check: require `assurance.domain_verified` from the verified DAP when domain provenance matters. 5. There is no risk score. A signed portable ordinal score is not audit-defensible, so none is issued. Use the trust tier and the signed scopes. 6. Do not gate on a signed `sanctions_clear` - the field was removed from the signed attestation (ADR-P-022), because signing a standing sanctions boolean asserts a check that may not have run. Screening is an optional provenanced claim present only when it actually ran; a hit or review suspends standing via `status_reference`. 7. Call `kya_possession_challenge` before `kya_issue_mandate` for a keyed card. The possession proof carries a single-use nonce and the issuer rejects a proof without a fresh one. On a software key, AAL2 is earned by that possession proof, not by tier - a bare replayable Web Bot Auth signature is AAL1 even at tier 2. 8. A fingerprint, DAP identifier, or mandate ID is a public lookup key, not a secret; log and publish them freely. The holder's private key and your access token are the secrets. 9. Enforce scopes yourself. `allowed_scopes` is signed and auditable, but Trulioo does not block an out-of-scope action on your behalf. 10. Never put document images or biometric data on the MCP stream. Capture stays off the protocol; a verification tool takes attributes, never an image. ## Hosted MCP endpoint - URL: https://mcp.trulioo.com/mcp - Transport: MCP streamable HTTP - Sandbox auth: client-managed OAuth 2.1 + PKCE - Live auth: exchange client_id and client_secret at POST https://mcp.trulioo.com/oauth/token, then use the returned bearer token on /mcp - Discovery: tools/list, resources/list, prompts/list return typed schemas at runtime - Post-initialize header: MCP-Protocol-Version: 2025-06-18 on notifications/initialized, tools/list, and every tools/call request after negotiating that revision ## Authentication (full worked examples: /developer#auth) ### Sandbox connection Claude Code, Cursor, Codex, ChatGPT, and other current MCP clients manage OAuth 2.1 + PKCE. 1. Add https://mcp.trulioo.com/mcp as a remote MCP server. 2. Complete the browser consent flow. 3. Choose sandbox. 4. Return to the client. It initializes the session and discovers the available tools. Let the client manage sandbox registration, PKCE, tokens, refresh, and MCP session headers. - Sandbox uses the same endpoint, tools, and schemas. Results carry a test_mode block. - Scopes: verify (run verifications) and read (fetch records, statuses, and reports). - Usage limits apply during early access. Follow retry_after_seconds before retrying and contact Trulioo before increasing production traffic. ### Live integration with client credentials Store client_id and client_secret in a secret manager. Bootstrap a short-lived MCP token: ```bash export TRULIOO_CLIENT_ID="your-client-id" export TRULIOO_CLIENT_SECRET="your-client-secret" # 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. Set TOKEN to the returned access_token and use Authorization: Bearer $TOKEN on /mcp. Never send client_secret to /mcp or log it. No refresh token is returned; re-run the bootstrap after expiry or a 401 response. ## Machine index - Structured index: https://mcp.trulioo.com/developer/index.json - KYA A2A extension schema: https://identity.trulioo.com/a2a/kya/v1/schema.json - KYA card example: https://identity.trulioo.com/a2a/kya/v1/card.example.json - Issuer signing keys (DAP verification): https://identity.trulioo.com/.well-known/jwks.json ## Tools by domain (call tools/list for the exact set on your connection) - KYC: kyc_verify, kyc_get_status, kyc_get_record - KYB: kyb_verify, kyb_search, kyb_get_report, kyb_registration_lookup, kyb_get_partial_result, kyb_disambiguate_candidate - Retrieval by transactionId: transaction_lookup (resolve a TransactionID or TransactionRecordID to the record + identity, KYC or KYB) - PER-ACCOUNT families, OFF unless your account is entitled to them, each enabled on its own. They are real and supported; they are simply absent from tools/list until your deployment has them. Ask Trulioo for the families you need rather than coding around them, and read the result from tools/list: getting one family does not get you the rest. - Standalone screening: aml_screen - Document + liveness capture: docv_create_session, docv_get_result, docv_cancel_session, docv_create_mobile_handoff. The session flow keeps images and biometric data OFF the MCP stream - never put them on it. - Age assurance: age_check (from a known DOB). age_estimate_biometric is declared but returns NotImplemented until biometric estimation ships - do not build against it. - Ongoing monitoring: monitoring_enroll, monitoring_get_alert, monitoring_refresh, monitoring_cancel, monitoring_get_enrollment - Post-KYB research, OFF unless the account is entitled to it: kyb_run_follow_up starts an explicitly approved, bounded ownership or Deep Research follow-up from a terminal KYB verification; kyb_get_research polls Deep Research and ubo_get_graph polls the ownership graph. Direct research and ownership starts are retired. - tools/list and config_discover_account are the authority on what YOUR connection has. Do not hardcode the lists above and do not synthesize a tool name that is not on them - there is no raw passthrough, so a tool that is absent is not reachable by another route. - KYA: kya_admission_challenge (mint a short-lived challenge bound to one privileged target tool), kya_possession_challenge (mint the single-use nonce first), kya_issue_mandate, kya_card_fingerprint (pre-flight: the fingerprint a build WOULD get, without registering or attesting - costs nothing but is KEYED, not public, because it is a build-time utility rather than a relying-party read), kya_verify_agent, kya_verify_web_bot_auth, kya_lookup, kya_verify_protocol, kya_supersede_agent (rotate/reissue), kya_retire_agent (revoke standing) - KYA relying-party half: kya_verify_mandate (for a credential a counterparty PRESENTED to you - signature, issuer, window, and with freshness=central_fresh revocation. Use this, not kya_get_mandate, when somebody hands you a credential: reading a mandate by an id lifted out of an unverified document trusts the document to describe itself. The optional amount is ADVISORY and never changes valid; amount_advisory.within=null means UNANSWERABLE, never a pass), kya_get_mandate (status, window, signed scope - a max_amount of null means UNCAPPED, never a cap of zero), kya_record_spend (record a settled spend, which is what makes a day/total ceiling answerable at all - settlement_id is the DE-DUPLICATION key, so a replay with the same amount returns recorded=false and counts once while the same id with a DIFFERENT amount is refused 409 rather than overwritten; recording is NOT enforcement, it moves no money and blocks nothing), kya_mandate_spend (read the ledger - totals per currency, the declared ceiling, the headroom left; remaining=null is NOT zero, it means no headroom to speak of: uncapped, or a per-transaction cap, which limits each purchase rather than depleting), kya_revoke_mandate (records a reason; the capability rails fail closed on the next verify, the A2A discovery tier is OfflineOk by design and lags), kya_revocations (with each status-list index). Four need NO account, because Halo serves the same routes anonymously: kya_transparency_sth (the signed tree head every proof hangs from), kya_inclusion_proof (RFC 6962 - verify the audit path with transparency_log's verify_inclusion_hashed, NOT verify_inclusion: the served leaf_hash is already hashed and hashing it twice reports a sound log as broken), kya_status_list (the signed revocation bitstring), kya_rails (what each protocol rail requires), kya_assess_readiness (measure public agent-facing documents and return reason codes, not a score), kya_assess_artifact (submit one immutable release or exact Git commit for tenant-scoped multi-collector assessment), kya_assessment_status (read lifecycle and frozen collector coverage; partial, failed, canceled, expired, and unavailable never mean clean; no vendor score, grade, or rank is exposed), kya_register_artifact, kya_publish_artifact, and kya_revoke_artifact (register, publish, or permanently revoke an immutable software-artifact release). One more needs an account and verifies something that is not a credential: kya_verify_client (fetch and validate the Client ID Metadata Document at an OAuth client's https client_id, the registration mechanism MCP 2026-07-28 asks for; returns the document's origin, its redirect_uris, whether it publishes a key, any KYA operator claim it carries, and TWO tier fields - record_trust_tier is about the URL, request_trust_tier_ceiling is the most a request carrying that client_id could reach, and they must not be collapsed. The carried attestation is never verified here: follow up with kya_lookup on the fingerprint, because the issuer is the source of truth and the document is not) - Config/meta: config_discover_account, config_describe_context, config_list_test_entities (list safe test subjects for this session), trulioo_health, trulioo_capabilities, trulioo_getting_started, webhook_journal - Interactive UI (per account, SEP-1865 MCP Apps): render_app_verdict (host-rendered ui:// verdict card) - Workflow prompts: kyc_onboarding_workflow, kyb_due_diligence_workflow. prompts/list is the authority on the set your connection offers. ## Protocol (negotiated per connection; floor 2025-06-18, max draft 2026-07-28) - The revision is negotiated at `initialize`. Features below apply only to a client that asked for the revision that carries them; everything degrades to the floor behavior. - Tasks extension (io.modelcontextprotocol/tasks): kyc_verify and kyb_verify return a Task to a tasks-capable client; poll tasks/get. Long-running operations retain stateless next_action long-poll continuations. In-memory task mirroring remains a compatibility path, not an authorization dependency. - MCP Apps extension (io.modelcontextprotocol/ui): host-rendered ui:// surfaces, gated by TRULIOO_ENABLE_MCP_APPS. - MRTR elicitation (SEP-2322): kyb_disambiguate_candidate returns input_required to a supporting client; text fallback otherwise. ## Result contract - Verification tools return typed results (status: match|review|nomatch, is_terminal, next_action). - Errors are returned as results, not thrown. is_terminal:false means poll. ## KYB workflow and responses - kyb_search: returns search_summary with candidate_count, has_results, and top_matches. Confirm a candidate before verification. - kyb_registration_lookup: returns supported registration-number types or jurisdictions of incorporation. Use them to format search or verification input. - kyb_disambiguate_candidate: returns resolved, candidate_index, and the selected candidate, or numbered options for clients without interactive selection. Continue after confirmation. - kyb_verify: returns transaction_id, record_id, status, is_terminal, and next_action. Branch on status and follow next_action when the result is not terminal. - kyb_get_partial_result: returns the latest available fields plus is_terminal and next_action. Continue polling only while the result is not terminal. - kyb_get_report: returns report JSON, or a PDF descriptor with record_id, report_available, content_type, and resource_uri. Store the report reference with the transaction. - transaction_lookup: returns the matching record and identity context for a TransactionID or TransactionRecordID. ## Know Your Agent (DAP) - Issue: kya_issue_mandate (verify org -> register agent -> sign scoped attestation -> anchor). - The agent's own Ed25519 key is the identity anchor; a build fingerprint binds the credential to the code. - Publish: attestation JWS under A2A card capabilities.extensions[] (uri https://identity.trulioo.com/a2a/kya/v1). - Verify: kya_verify_agent, or check the JWS against the issuer JWKS (public, keyless). - Scopes are signed + auditable but enforced by the relying party, not Trulioo. ## Verify a DAP / attestation - Integration path: call the MCP tool kya_verify_agent with the agent card (validates signature, fingerprint, expiry and standing; add requested_action to check scope). - Public keyless primitives (issuer, identity.trulioo.com, no account): - GET https://identity.trulioo.com/kya/attestation/{dap} - look up standing by Digital Agent Profile. This is the authoritative machine endpoint: JSON, and RFC 9457 application/problem+json on error. https://kya.trulioo.com/attestation/{dap} is the human share link and serves the browser app at that same URL (a 200 HTML rewrite, not a redirect) - do not parse it. - GET https://identity.trulioo.com/.well-known/jwks.json - issuer signing keys to verify a JWS yourself. - A verifier checks: JWS signature vs the pinned issuer key by kid (alg from key, never token), fingerprint vs agent key+card, exp, verified, assurance.trust_tier against your minimum, and the signed allowed_scopes. No sanctions boolean is signed (see instruction 6). Scopes are enforced by the relying party. ## Install - Claude Code (tools only): claude mcp add --transport http trulioo https://mcp.trulioo.com/mcp - OpenAI Codex: codex mcp add trulioo --url https://mcp.trulioo.com/mcp - ChatGPT: add https://mcp.trulioo.com/mcp by URL (OAuth on the consent screen) ## Docs - Developer home: https://mcp.trulioo.com/developer/ - Verify demo (live agent-card console): https://mcp.trulioo.com/kya - This page as markdown (full docs, ~31KB): https://mcp.trulioo.com/developer/index.md - Domain map: https://mcp.trulioo.com/llms.txt - Guiding a human through KYB setup: https://mcp.trulioo.com/agent-guide.md - Everything in one file: https://mcp.trulioo.com/llms-full.txt ## Install the skills into yourself - Catalog: https://mcp.trulioo.com/.well-known/skills/index.json - trulioo-onboarding, trulioo-kyc, trulioo-kyb, trulioo-kya, carrying the per-domain operating detail this map summarizes. Read the catalog for what exists; do not hardcode a skill count any more than a tool count. - Other agents with a skill system: install from the catalog. Without one: fold the skill bodies into your global custom instructions and treat the catalog as the source of truth, not a copy you pasted once. - ASK THE HUMAN before writing to their config locations. A skill install edits files they own. ============================================================================== # SOURCE: https://mcp.trulioo.com/developer/index.md # repo: platform/web/sites/external/showcase/developer/index.md ============================================================================== # Trulioo Developer > **Early access.** Security controls are in place. Tool names, input fields, and > documentation may change as we incorporate feedback. > > One MCP connection gives any agent KYC, KYB, and Know Your Agent (KYA): a signed, > scoped Digital Agent Profile (DAP) so anyone can prove the organization behind an agent. > Sandbox uses client-managed OAuth 2.1. Live integrations bootstrap an MCP access token > with an approved Trulioo `client_id` and `client_secret`. This is the human docs page rendered as markdown for agents. ## Let your agent guide your KYB setup Paste this into your coding agent: ``` Help me connect Trulioo MCP and complete a KYB verification in sandbox. Read https://mcp.trulioo.com/agent-guide.md first. Check whether Trulioo is already connected, then guide me through business discovery, verification, polling, and report retrieval. Stay within the KYB tools documented in the guide. ``` [agent-guide.md](/agent-guide.md) is a focused early access guide for connection checks, OAuth, business search, optional candidate confirmation, verification, polling, and report retrieval. ## Quickstart: zero to verified 1. **Connect the MCP server** - point any MCP client at the hosted endpoint. It discovers the authorization server and registers itself, so there is no key to copy-paste. 2. **Call a verification tool** - run `kyc_verify` or `kyb_verify` against synthetic test entities; branch on the typed result. 3. **Give your agent an identity** - verify the organization behind the agent, then mint a signed, scoped attestation with `kya_issue_mandate`. 4. **Let anyone verify it** - publish the attestation in your A2A card; any party checks it against the issuer JWKS, no key needed. ### I want to... | Goal | Do this | |---|---| | Verify a person | `kyc_verify` | | Verify a business | `kyb_verify` | | Screen a name on its own | `aml_screen` - per-account | | Capture a document or a selfie | `docv_create_session` - per-account | | Prove who is behind an agent | Know Your Agent (`kya_issue_mandate`) | | Verify another agent's profile | `kya_verify_agent` | | Connect an MCP client | see Client setup | | Authenticate with OAuth | see Authentication | ## The MCP endpoint - URL: `https://mcp.trulioo.com/mcp` - Transport: MCP streamable HTTP - Sandbox auth: client-managed OAuth 2.1 + PKCE. - Live auth: exchange an approved Trulioo `client_id` and `client_secret` at `POST https://mcp.trulioo.com/oauth/token`, then use the returned bearer token on `/mcp`. ## Authentication ### Sandbox connection Claude Code, Cursor, Codex, ChatGPT, and other current MCP clients manage OAuth 2.1 + PKCE for you. 1. Add `https://mcp.trulioo.com/mcp` as a remote MCP server. 2. Complete the browser consent flow when your client opens it. 3. Choose sandbox. 4. Return to the client. It initializes the MCP session and discovers the available tools. Let the client manage registration, PKCE, tokens, refresh, and MCP session headers. Do not copy sandbox tokens into the client configuration. ### Sandbox Sandbox is a session type, not a separate URL - it uses the same endpoint, tools, and schemas. Choose it on the consent screen. - Unbilled by construction: sandbox sends `VerificationType: Demo`, decided in one place for every verify tool, and the mode is pinned in the token - it is not a request parameter and cannot be set per call. An unrecognized mode claim is rejected with `401`; it is never downgraded to sandbox nor inferred from anything in the request. - Results are self-describing: `{"test_mode":{"sandbox":true,"verification_type":"Demo"}}`, and the server's `instructions` at `initialize` states the mode in words. - Some rails answer from an official register even in sandbox (the register source is a server-side configuration; measured at `mcp.trulioo.com`, 2026-08-25, the payload carried `registerSource: "live"`). Then the block reads `"data":"live"` with a notice: the values are real, the call is still unbilled, and it is not a verification you may rely on. Branch on `test_mode.data`, not only `test_mode.sandbox`. - No PII stored. ### Live integration with client credentials Store the approved account's `client_id` and `client_secret` in a secret manager or environment. Exchange them for a short-lived MCP access token: ```bash export TRULIOO_CLIENT_ID="your-client-id" export TRULIOO_CLIENT_SECRET="your-client-secret" # 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 has this shape: ```json { "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600 } ``` Never send `client_secret` to `/mcp`, put it in a URL, or log it. The bootstrap does not return a refresh token. Re-run the bootstrap when the MCP token expires or `/mcp` returns `401`. For raw HTTP, set `TOKEN` to the returned `access_token`, then complete the session handshake: ```bash export TOKEN="eyJ..." HEADER_FILE="$(mktemp)" # 1. Initialize and capture the session id from the response headers. curl -sN -D "$HEADER_FILE" https://mcp.trulioo.com/mcp \ -H "Authorization: Bearer $TOKEN" \ -H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{ "protocolVersion":"2025-06-18","capabilities":{}, "clientInfo":{"name":"my-agent","version":"1.0.0"}}}' export SID="$(awk 'tolower($1) == "mcp-session-id:" {gsub(/\r/, "", $2); print $2}' "$HEADER_FILE")" rm -f "$HEADER_FILE" test -n "$SID" # 2. Tell the server the client is ready; expect 202 with no body. curl -sN -X POST https://mcp.trulioo.com/mcp \ -H "Authorization: Bearer $TOKEN" \ -H "mcp-session-id: $SID" \ -H 'MCP-Protocol-Version: 2025-06-18' \ -H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' # 3. The initialized session can now list or call tools. curl -sN https://mcp.trulioo.com/mcp \ -H "Authorization: Bearer $TOKEN" \ -H "mcp-session-id: $SID" \ -H 'MCP-Protocol-Version: 2025-06-18' \ -H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` ### Scopes `verify` (run verifications, issue KYA credentials) and `read` (fetch records, statuses, reports). Both granted by default; request `read` alone for an analysis-only integration. KYA's public reads (transparency tree head, inclusion proof, status list, rails) need no account and are served anonymously. ### Usage limits Usage limits apply during early access. If a result includes `retry_after_seconds`, wait for that interval before retrying. Contact Trulioo before increasing production traffic. ## Client setup Use the hosted endpoint in your MCP client. The first protected action opens the OAuth consent flow. **Claude Code** ``` claude mcp add --transport http trulioo https://mcp.trulioo.com/mcp ``` **Claude Desktop** - add Trulioo MCP as a remote (custom) connector by URL: `https://mcp.trulioo.com/mcp` (on the plans that support custom connectors). Complete OAuth on the consent screen. **MCP config (JSON)** - any client (Cursor, VS Code, ...): ```json { "mcpServers": { "trulioo": { "url": "https://mcp.trulioo.com/mcp" } } } ``` **OpenAI Codex** ``` codex mcp add trulioo --url https://mcp.trulioo.com/mcp ``` **ChatGPT (Developer mode)** - add `https://mcp.trulioo.com/mcp` by URL and complete OAuth on the consent screen. **Raw JSON-RPC** - discover the tools. Both a bearer token and an initialized session are required; complete the executable three-step Authentication example first: ``` curl -sN https://mcp.trulioo.com/mcp \ -H "Authorization: Bearer $TOKEN" -H "mcp-session-id: $SID" \ -H 'MCP-Protocol-Version: 2025-06-18' \ -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/list"}' ``` ## Tools reference Every capability is a typed, discoverable MCP tool - there is no raw passthrough, so a tool that is not on your connection is not reachable by another route. Call `tools/list` for the exact enabled set: a default progressive connection advertises 17 resident tools and exposes a default union of 42 tools through runtime discovery. Per-account families change that set. Call a tool (bearer token and an initialized session both required - see Authentication): ``` curl -sN https://mcp.trulioo.com/mcp \ -H "Authorization: Bearer $TOKEN" -H "mcp-session-id: $SID" \ -H 'MCP-Protocol-Version: 2025-06-18' \ -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"kyc_verify","arguments":{"country_code":"US","data_fields":{}}}}' ``` **Identity & business:** `kyc_verify`, `kyc_get_status`, `kyc_get_record`, `kyb_verify`, `kyb_search`, `kyb_get_report`, `kyb_registration_lookup`, `kyb_get_partial_result`, `kyb_disambiguate_candidate` **Retrieval by transactionId:** `transaction_lookup` (resolve a TransactionID or TransactionRecordID to the record + identity, KYC or KYB) **Per-account families** - off unless your account is entitled to them, each enabled on its own. They are real and supported; they are simply absent from `tools/list` until your deployment has them. Ask Trulioo for the families you need rather than coding around them, and read the result from `tools/list` - getting one family does not get you the rest: `aml_screen` (standalone sanctions/PEP screening), `docv_create_session`, `docv_get_result`, `docv_cancel_session`, `docv_create_mobile_handoff` (document and liveness capture - the session flow keeps images off the MCP stream), age assurance (`age_check` from a known date of birth; `age_estimate_biometric` is declared but returns `NotImplemented` until biometric estimation ships - do not build against it), and ongoing monitoring (`monitoring_enroll`, `monitoring_get_alert`, `monitoring_refresh`, `monitoring_cancel`, `monitoring_get_enrollment`) **Post-KYB research** - off unless the account is entitled to it: `kyb_run_follow_up` starts an explicitly approved, bounded ownership or Deep Research follow-up from a terminal KYB verification; `kyb_get_research` polls Deep Research and `ubo_get_graph` polls the ownership graph. Direct research and ownership starts are retired. > `tools/list` and `config_discover_account` are the authority on what YOUR connection has. > Do not hardcode this list, and do not synthesize a tool name that is not on it. **Know Your Agent:** `kya_admission_challenge` (mint a short-lived challenge bound to one privileged target tool), `kya_possession_challenge` (mint the single-use nonce a keyed card's possession proof must carry - call it first, `kya_issue_mandate` rejects a proof without a fresh one), `kya_issue_mandate`, `kya_card_fingerprint` (the pre-flight: compute the fingerprint a build WOULD get, without registering or attesting, so you learn whether a change re-mints your identity before you spend an issuance on it - free, but keyed), `kya_verify_agent`, `kya_verify_web_bot_auth`, `kya_lookup`, `kya_verify_protocol`, `kya_supersede_agent` (rotate/reissue), `kya_retire_agent` (revoke standing) The relying-party half - a verifier reads and checks, it does not only verify: `kya_verify_mandate` (for a credential a counterparty PRESENTED to you - signature, issuer, window, and with `freshness: central_fresh` revocation; pass `amount` for an ADVISORY read of the declared ceiling, which never changes `valid`, and where a `within` of `null` means unanswerable rather than a pass), `kya_get_mandate` (status, window, and the signed scope; a `max_amount` of `null` means uncapped, never a cap of zero), `kya_record_spend` (record a settled spend, which is what makes a `day`/`total` ceiling answerable at all - your `settlement_id` is the de-duplication key, so a replay with the same amount returns `recorded: false` and counts once while the same id with a DIFFERENT amount is refused `409`; recording is not enforcement, it moves no money and blocks nothing), `kya_mandate_spend` (read the ledger: totals per currency, the declared ceiling, and the headroom left - a `remaining` of `null` is NOT zero, it means there is no headroom to speak of, either uncapped or a per-transaction cap, which limits each purchase rather than depleting), `kya_revoke_mandate` (with a recorded reason), `kya_revocations`, and four public reads that need no account because Halo serves the same routes anonymously: `kya_transparency_sth` (the signed tree head every proof hangs from), `kya_inclusion_proof` (RFC 6962 - verify the audit path with `verify_inclusion_hashed`, not `verify_inclusion`, because the served `leaf_hash` is already hashed), `kya_status_list` (the signed revocation bitstring, re-signed per request so do not cache it by byte hash), `kya_rails` (what each rail demands before you build for it). Account-backed agent infrastructure checks include `kya_assess_readiness` (measure public agent-facing documents and return reason codes, not a score), `kya_assess_artifact` (submit one immutable release or exact Git commit for a tenant-scoped multi-collector assessment), and `kya_assessment_status` (read its lifecycle and frozen collector coverage). Assessment status is coverage intent, not a verdict: partial, failed, canceled, expired, and unavailable never mean clean, and no vendor score, grade, or rank is exposed. `kya_register_artifact`, `kya_publish_artifact`, and `kya_revoke_artifact` (register, publish, or permanently revoke an immutable software artifact release). One more needs an account and its subject is not a credential: `kya_verify_client` (fetch and validate the Client ID Metadata Document at an OAuth client's https `client_id` - the registration mechanism MCP `2026-07-28` asks for - and get back its origin, its `redirect_uris`, whether it publishes a key, any KYA operator claim it carries, and two tier fields: `record_trust_tier` is about the URL, `request_trust_tier_ceiling` is the most a request carrying that `client_id` could reach. The carried attestation is never verified there; follow up with `kya_lookup` on the fingerprint, because the issuer is the source of truth and the document is not) **Config / meta:** `config_discover_account`, `config_describe_context`, `config_list_test_entities` (list the safe test subjects available to this session), `trulioo_health`, `trulioo_capabilities`, `trulioo_getting_started`, `webhook_journal` **Interactive UI (per account, SEP-1865):** `render_app_verdict` (host-rendered `ui://` verdict card) **Workflow prompts:** `kyc_onboarding_workflow`, `kyb_due_diligence_workflow` (`prompts/list` is the authority on the set your connection offers) ### KYB workflow and responses | Step | Tool | Use it when | Response and next step | |---|---|---|---| | 1 | `kyb_search` | You have a business name but not a confirmed registration identifier. | Returns `search_summary` with `candidate_count`, `has_results`, and `top_matches`. Confirm a candidate before verification. | | As needed | `kyb_registration_lookup` | You need the accepted registration types or jurisdiction details for a country. | Returns supported registration-number types or jurisdictions of incorporation. Use them to format the next request. | | As needed | `kyb_disambiguate_candidate` | Search returns multiple businesses. | Returns `resolved`, `candidate_index`, and the selected `candidate`, or numbered `options` for clients without interactive selection. Continue only after user confirmation. | | 2 | `kyb_verify` | You have confirmed the business and are ready to verify it. | Returns `transaction_id`, `record_id`, `status`, `is_terminal`, and `next_action`. Branch on `status`; follow `next_action` when the result is not terminal. | | While running | `kyb_get_partial_result` | Verification is still running and you need the latest state. | Returns the latest available fields plus `is_terminal` and `next_action`. Continue polling only while the result is not terminal. | | 3 | `kyb_get_report` | Verification is complete and you need the final report. | Returns report JSON, or a PDF descriptor with `record_id`, `report_available`, `content_type`, and `resource_uri`. Store the report reference with the transaction. | | Reference | `transaction_lookup` | You need to retrieve a previous verification from its transaction identifier. | Returns the matching record and identity context for a TransactionID or TransactionRecordID. | ### Shared verification result ```json { "transaction_id": "txn_...", "record_id": "rec_...", "status": "match", // match | review | nomatch "is_terminal": true, // false = poll kyb_get_partial_result "next_action": "none" } ``` - Errors are returned as typed results, not thrown. - `is_terminal:false` means poll rather than assume completion. - Per-upstream circuit breaker: one degraded provider does not take down the others. ## Know Your Agent (DAP) Prove the real organization behind an agent and issue a signed, scoped, revocable Digital Agent Profile that anyone can verify. It rides in the agent's A2A card. 1. **Verify the organization** - KYC/KYB + sanctions on the accountable owner (`/kya/principal/verify`). 2. **Register the agent** - the agent presents its own Ed25519 key; that key is the identity anchor. A build fingerprint binds the credential to the exact agent. 3. **Sign a scoped mandate** - `kya_issue_mandate` mints a short-lived, least-privilege attestation for named scopes (e.g. `purchase`), signed by `identity.trulioo.com`. 4. **Publish it** - the attestation attaches under `capabilities.extensions[]` (uri `https://identity.trulioo.com/a2a/kya/v1`) and is anchored in a tamper-evident log. ```json { "capabilities": { "extensions": [{ "uri": "https://identity.trulioo.com/a2a/kya/v1", "params": { "attestation": "", "display": { "verified": true, "verified_as_of": "", "allowed_scopes": ["purchase"], "issuer": "https://identity.trulioo.com", "fingerprint": "" } } }] } } ``` Scopes are signed and auditable by Trulioo but **enforced by the relying party** - the attestation is a verifiable claim of trust, not an authorization grant on its own. ### Why agent trust has layers 1. **Identity anchor** - the agent holds its own key; everything binds to it. 2. **Integrity & provenance** - a build fingerprint binds the credential to the exact code; code change forces re-attestation. 3. **Authenticity of use** - a possession proof shows the presenter controls the anchor key. 4-5. **Origin & accountability** - KYC/KYB ties the agent to a real, sanctions-screened org; every issuance is anchored in a tamper-evident log. ### Verify an agent (DAP) The critical path: confirm a profile + attestation before trusting an inbound agent. - Integration path (recommended): call the MCP tool `kya_verify_agent` with the agent card - validates signature, fingerprint, expiry, sanctions; add `requested_action` to check the signed scope. The verification logic lives behind MCP, not a public write API. - Public keyless primitives (issuer at identity.trulioo.com, no account): - `GET https://identity.trulioo.com/kya/attestation/{dap}` - look up standing by Digital Agent Profile. - `GET https://identity.trulioo.com/.well-known/jwks.json` - issuer signing keys to verify a JWS yourself. ``` # verify over MCP curl -sN https://mcp.trulioo.com/mcp -H "Authorization: Bearer $TOKEN" -H "mcp-session-id: $SID" -H 'MCP-Protocol-Version: 2025-06-18' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kya_verify_agent","arguments":{"agent_card":{}}}}' # public keyless lookup curl -s https://identity.trulioo.com/kya/attestation/ curl -s https://identity.trulioo.com/.well-known/jwks.json ``` A verifier checks: JWS signature vs the pinned issuer key by kid (alg from key, never the token header); fingerprint vs agent key + card; exp; `verified`; `assurance.trust_tier` against your own minimum; and the signed allowed_scopes. Scopes are enforced by the relying party. No standing sanctions boolean is signed. Signing one would assert a check that may not have run, on a payment-adjacent credential. Screening is an optional provenanced claim carried only when it actually ran, and a hit or review suspends the credential's standing through its `status_reference` - so check standing, not a boolean. ## Orchestration patterns - **Agent as orchestrator** - one agent connects once and calls verification tools mid-task, branching on the typed result. - **Enterprise agent teams** - a fleet shares one MCP connection and one identity layer; each agent carries its own DAP so downstream systems know which accountable org acted. ## Security & honest limits - Schema-enforced inputs (`additionalProperties: false`) - malformed/injected calls rejected before any upstream. - Prompt-injection resistance - tools act only on typed arguments; document/field text is data, never an instruction. - Algorithm pinning - attestation verification pins the alg from the resolved key (EdDSA/ES256 only); `alg:none` and alg-confusion rejected. - Honest limits - a DAP proves identity, integrity, scope and accountability; it does not authorize a payment or guarantee behavior. Scope enforcement is the relying party's. ## Changelog - **2026-09-02** - Added the Authentication section: the 401 + `WWW-Authenticate` discovery entry point, the full OAuth 2.1 + PKCE handshake with worked curl for /register, /authorize and /token, sandbox mechanics (`VerificationType: Demo`, the `test_mode` annotation and its live-data case), session lifetimes, and scopes. Corrected the tool-call examples, which omitted the required bearer token. - **2026-08-03** - Launched the unified /developer surface (consolidates the former MCP + KYA docs); added machine twins (index.md, llms.txt, index.json); documented the full tool set, the KYA/DAP flow, and the Claude Desktop -> production-scale path; canonical endpoint `https://mcp.trulioo.com/mcp`; public setup for Claude Code, OpenAI Codex, and the ChatGPT connector. - **2026-08-02** - KYA A2A card carries the Trulioo-signed attestation (JWS) under capabilities.extensions[]; agent's own key is the identity anchor; public DAP verification via issuer JWKS at identity.trulioo.com/.well-known/jwks.json. - **2026-08-01** - MCP hosted endpoint with self-registering OAuth; typed tools across KYC/KYB/AML/DocV/age/monitoring; approved live access uses OAuth 2.1. ## Links - Developer home (HTML): https://mcp.trulioo.com/developer/ - Verify demo (live agent-card console): https://mcp.trulioo.com/kya - KYA extension schema: https://identity.trulioo.com/a2a/kya/v1/schema.json - Card example: https://identity.trulioo.com/a2a/kya/v1/card.example.json