mcp-onfido

@codespar/mcp-onfido

MCP server for Onfido — global identity verification and KYC.

Onfido is the identity verification layer behind Revolut, N26, Uber, and hundreds of regulated fintechs. One API covers 195+ countries and the full KYC flow: applicant → document → live photo → check (runs verification) → reports.

Second entry in CodeSpar's identity category alongside Unico (BR-first KYC). Pair them: Unico for Brazilian users (CPF + Receita Federal biometric pool), Onfido when the flow touches non-LatAm users.

Tools (20)

Tool	Purpose
create_applicant	Create an Onfido applicant — the person record that documents, live photos, and checks attach to.
retrieve_applicant	Retrieve an applicant by id.
update_applicant	Update fields on an existing applicant.
upload_document	Upload an identity document image for an applicant.
retrieve_document	Retrieve document metadata by id.
upload_live_photo	Upload a live photo (selfie) for an applicant, used by facial_similarity_photo reports.
retrieve_live_photo	Retrieve a live photo record by id.
create_check	Run a verification check on an applicant.
retrieve_check	Retrieve a check by id.
list_checks	List all checks for a given applicant.
retrieve_report	Retrieve an individual report by id.
delete_applicant	Soft-delete an applicant.
list_documents	List all documents uploaded for a given applicant.
download_document	Download the raw binary of an uploaded document.
list_live_photos	List all live photos (selfies) uploaded for a given applicant.
resume_check	Resume a check that was paused (typically awaiting_applicant or paused states).
list_reports	List the reports contained within a given check.
create_workflow_run	Start an Onfido Studio workflow run.
retrieve_workflow_run	Retrieve a workflow run by id.
generate_sdk_token	Mint a short-lived SDK token for embedding the Onfido Web / iOS / Android SDKs in your frontend.

Flow

create_applicant
    -> upload_document  (front, and back if driving_licence / national_identity_card)
    -> upload_live_photo
    -> create_check      report_names=["document","facial_similarity_photo","watchlist_standard"]
    -> retrieve_check    (poll until status = complete)
    -> retrieve_report   (for each report id to get the detailed breakdown)

Install

npm install @codespar/mcp-onfido

Environment

ONFIDO_API_TOKEN="..."    # API token (required, secret)
ONFIDO_REGION="eu"        # Optional. 'eu' | 'us' | 'ca'. Defaults to api.onfido.com.

Authentication

Onfido uses a non-Bearer header format:

Authorization: Token token=<ONFIDO_API_TOKEN>

The server handles this automatically.

Regional hosts

Region	Host
Default	https://api.onfido.com
EU	https://api.eu.onfido.com
US	https://api.us.onfido.com
CA	https://api.ca.onfido.com

All requests target API version v3.6 (current stable).

Multipart uploads

upload_document and upload_live_photo accept files as base64-encoded strings. Pass the bytes in file, with file_name and content_type:

{
  "applicant_id": "a1b2c3...",
  "type": "passport",
  "file": "<base64-encoded bytes>",
  "file_name": "passport.jpg",
  "content_type": "image/jpeg"
}

The server wraps it as multipart/form-data before sending.

Note: Onfido increasingly recommends capturing live photos via their SDK rather than API upload. Direct /live_photos upload may be restricted on some accounts — use the SDK flow when in doubt.

Run

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-onfido

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-onfido

When to pick Onfido vs Unico

Signal	Pick
User is Brazilian, need CPF validation + biometric match against Receita Federal	Unico
User is outside LatAm, or flow is global	Onfido
Regulated fintech needing AML watchlist + PEP screening globally	Onfido
Travel / gig marketplace onboarding across 20+ countries	Onfido

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT