KYC Through an MCP Server: The Practical Guide

Know Your Customer (KYC) checks are the most common identity operation on the Didit platform, and the official Model Context Protocol (MCP) server at https://mcp.didit.me/mcp makes running them as natural as a conversation. Point an AI agent — Claude Desktop, Claude Code, Cursor, ChatGPT, or any MCP-capable client — at the hosted endpoint, authenticate with "Log in with Didit", and the agent can walk through the full KYC lifecycle: discover your organization and application, pick the right workflow, mint a hosted verification session, hand the link to your user, and poll the decision. This guide walks through that sequence tool by tool, covers the 10 session statuses and what to do at each one, and shows the equivalent REST calls for readers who want the backend path.

Key takeaways

• The Didit MCP server exposes 115 tools across 11 categories over Streamable HTTP at https://mcp.didit.me/mcp. It is hosted or self-hosted, and the MCP layer itself is free.
• Authentication is OAuth 2.1 + Proof Key for Code Exchange (PKCE) with Dynamic Client Registration. There is no API key for the hosted MCP server — the agent authenticates as the signed-in user and inherits that user's console permissions.
• A full KYC verification — ID document check, passive liveness, face match, and IP analysis — costs $0.33, with 500 free verifications per month and sub-2-second p99 inference. The workflow can include additional checks like AML screening ($0.20) or custom questionnaires ($0.10).
• The agent runs a KYC session in five tools: discover your org and app, select a workflow, create the session, read the V3-array decision, and update the session status to approve, decline, or request resubmission.
• 10 session statuses tell the agent what to do next: from Not Started through In Progress, In Review, Approved, Declined, Expired, Abandoned, Kyc Expired, Resubmitted, and Awaiting User.
• The MCP server powers onboarding for 2,000+ companies in production across 220+ countries and 14,000+ document types, in 48+ languages.

What the Didit MCP server is

The Model Context Protocol (MCP) is an open standard that lets AI agents call external tools through a consistent interface. Didit's implementation at https://mcp.didit.me/mcp is the official MCP server for the identity and fraud platform, published under the MIT license at github.com/didit-protocol/mcp. It uses Streamable HTTP transport — stateless, POST-only, no Server-Sent Events — and exposes 115 tools across 11 categories that cover the full platform: sessions, workflows, verification APIs, transaction monitoring, Anti-Money Laundering (AML) screening, wallet screening, webhooks, cases, reports, and workspace operations.

The hosted authentication uses OAuth 2.1 with PKCE (Proof Key for Code Exchange) and Dynamic Client Registration (DCR). When the agent first connects, it opens a browser for the "Log in with Didit" flow through business.didit.me. The resulting token is scoped to your console user across didit:management and didit:verification — the agent can only do what your role already allows. This is important: there is no API key to paste into an MCP config file for the hosted server. API keys are an REST API concept and are not used in the MCP context.

To connect the hosted endpoint to Claude Desktop or Claude.ai, use the pre-built connector deep link:

Add Didit as a Claude connector

For an overview of the full tool set, see the MCP tools reference and the MCP overview docs.

The KYC sequence — tool by tool

A standard KYC session on Didit bundles your choice of identity checks — ID document verification, passive liveness to confirm the person is physically present, face match to confirm the selfie matches the document portrait, and IP analysis for fraud signals — all for $0.33 when the full bundle is configured. Here is the exact tool sequence an agent follows to create, deliver, and resolve one:

1. Discover your context

Before creating anything, the agent needs to know which organization and application to operate on. Call didit_context_get to list the available organizations and applications the signed-in user has access to. This returns the organization_id and application_id that every subsequent tool call needs.

2. Pick a workflow

Verification workflows define which checks run and how decisions are made. Call didit_workflow_list to fetch the workflows configured for your application. Each workflow exposes its features — OCR (Optical Character Recognition), Liveness, Face Match, AML, questionnaires — so the agent can pick the right one for the verification type needed. For a standard KYC onboarding, the workflow typically includes OCR, Liveness, Face Match, and IP Analysis.

3. Create the session

With the workflow selected, call didit_session_create with the organization_id, workflow_id, and optional external reference (reference_id). You can also specify the language for the hosted verification UI, the redirect URLs the applicant lands on after completion, and any pre-filled data fields. The tool returns a verification_url — a hosted link you send to the applicant. No SDK integration is needed for this path; the applicant just opens the link in their browser, completes the checks, and the agent picks up from there.

4. Read the decision

Once the applicant completes the checks, call didit_session_get_decision with the session ID. This returns a V3 plural-array decision: a status string, a decision object with verdict and risk score, and per-feature results (OCR data, liveness confidence, face match similarity, etc.). The agent reads the verdict to determine the next action.

5. Act on the decision

Call didit_session_update_status to set the session status based on the decision verdict:

• Approved — all checks passed. Set status to approved to finalize.
• Declined — checks failed or fraud detected. Set status to declined.
• Resubmitted — documents were unclear or the applicant needs to retry. Set status to resubmitted to allow another attempt.

That is the entire KYC round trip in five tools, all from a natural-language prompt.

The 10 session statuses

Didit sessions move through a lifecycle of 10 statuses. An agent configured to monitor sessions should handle each one:

• Not Started — the session was created but the applicant has not opened the verification link. No action needed yet.
• In Progress — the applicant opened the link and is going through the checks. The agent should wait.
• In Review — the automated checks finished with a borderline score; the session needs manual review. Notify a human compliance officer.
• Approved — all checks passed. Complete onboarding.
• Declined — checks failed. Reject the applicant or start a new verification with different documents.
• Expired — the session expired before completion. Offer a new session.
• Abandoned — the applicant closed the flow before finishing. Send a reminder or a new link.
• Kyc Expired — a periodic re-verification session has expired. Flag for re-onboarding.
• Resubmitted — the applicant re-submitted after being asked for better data. Re-run didit_session_get_decision to get the new verdict.
• Awaiting User — the session is paused waiting for the applicant to provide additional information or documents.

Agent-level controls: lists, blocklists, and ongoing monitoring

Beyond single-session KYC, the MCP server gives agents access to the risk control surface. Use didit_lists_list and didit_lists_entry_create to add declined applicants to blocklists, preventing them from creating new sessions. Use didit_blocklist_get and didit_blocklist_add to screen new session requests before they are created. For ongoing monitoring, after a KYC approval you can run didit_verify_aml for Anti-Money Laundering screening against 1,300+ watchlists at $0.20 per check, and didit_transaction_screen_wallet for crypto wallet screening at $0.15 per check.

Equivalent REST API path

Not every integration runs through an AI agent. If you are building a backend that calls Didit directly via HTTP, the REST API uses x-api-key authentication (your application's secret key from the console). Here is the equivalent KYC session creation via curl:

curl -X POST https://api.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wfl_abc123",
    "reference_id": "user-456",
    "lang": "en",
    "redirect_url": "https://myapp.com/kyc-callback"
  }'

The response includes the session_id and verification_url — the same hosted link the MCP session returns. Poll the decision endpoint and update the status the same way, but via REST. Note the x-api-key header: this is the REST API authentication mechanism and is unrelated to the MCP OAuth flow described above. The REST API is a separate surface; the MCP server never needs or uses an API key.

Pricing and limits

Every Didit feature has published, per-success pricing with no minimums. The MCP server itself is free — there is no charge for connecting or listing tools. You pay only for successful verifications:

• Full KYC bundle (ID + Passive Liveness + Face Match + IP): $0.33
• ID verification (standalone): $0.15
• Passive liveness (standalone): $0.10
• AML screening: $0.20 per check, 1,300+ watchlists
• Wallet screening (KYT): $0.15 per check
• Transaction monitoring: $0.02 per transaction
• Business Verification (KYB): from $2.00 per business

Every feature includes 500 free verifications per month, forever. No time limit, no tier gate. The full KYC bundle at $0.33 is 3-5x cheaper than traditional KYC providers, with sub-2-second p99 inference across 220+ countries and 14,000+ document types.

Getting started

To connect your agent and start running KYC checks in minutes:

1. Open the Claude connector deep link and add Didit as a custom connector.
2. For Claude Code: run claude mcp add --transport http didit https://mcp.didit.me/mcp, then /mcp to authenticate.
3. For Cursor: add {"mcpServers":{"didit":{"url":"https://mcp.didit.me/mcp"}}} to .cursor/mcp.json.
4. Once authenticated, prompt: "Discover my organization and applications, list the KYC workflows, and create a verification session for a new applicant."

The MCP source code is open and MIT-licensed at github.com/didit-protocol/mcp. For a deeper walkthrough of installing the server in different clients, read How to Install the Didit MCP Server in Claude. For the full tool catalog with parameters, see the Didit MCP Tools Reference.