KYC a través de un servidor MCP: la guía práctica

Las verificaciones de Conozca a su Cliente (KYC) son la operación de identidad más común en la plataforma Didit, y el servidor oficial del Protocolo de Contexto del Modelo (MCP) en https://mcp.didit.me/mcp hace que ejecutarlas sea tan natural como una conversación. Apunte un agente de IA — Claude Desktop, Claude Code, Cursor, ChatGPT o cualquier cliente compatible con MCP — al endpoint alojado, autentíquese con "Iniciar sesión con Didit", y el agente podrá recorrer el ciclo de vida completo de KYC: descubrir su organización y aplicación, elegir el flujo de trabajo correcto, acuñar una sesión de verificación alojada, entregar el enlace a su usuario y consultar la decisión. Esta guía explica esa secuencia herramienta por herramienta, cubre los 10 estados de sesión y qué hacer en cada uno, y muestra las llamadas REST equivalentes para los lectores que desean la ruta de backend.

Puntos clave

• El servidor Didit MCP expone 115 herramientas en 11 categorías a través de HTTP Streamable en https://mcp.didit.me/mcp. Está alojado o se autoaloja, y la capa MCP en sí es gratuita.
• La autenticación es OAuth 2.1 + Proof Key for Code Exchange (PKCE) con registro dinámico de clientes. No hay clave API para el servidor MCP alojado: el agente se autentica como el usuario que ha iniciado sesión y hereda los permisos de consola de ese usuario.
• Una verificación KYC completa — verificación de documentos de identidad, prueba de vida pasiva, coincidencia facial y análisis de IP — cuesta 0,33 $, con 500 verificaciones gratuitas al mes y inferencia p99 en menos de 2 segundos. El flujo de trabajo puede incluir verificaciones adicionales como la detección AML (0,20 $) o cuestionarios personalizados (0,10 $).
• El agente ejecuta una sesión KYC en cinco herramientas: descubre tu organización y aplicación, selecciona un flujo de trabajo, crea la sesión, lee la decisión de la matriz V3 y actualiza el estado de la sesión para aprobar, rechazar o solicitar el reenvío.
• 10 estados de sesión le dicen al agente qué hacer a continuación: desde No Iniciado hasta En Progreso, En Revisión, Aprobado, Rechazado, Caducado, Abandonado, KYC Caducado, Reenviado y Esperando Usuario.
• El servidor MCP impulsa la incorporación de más de 2000 empresas en producción en más de 220 países y más de 14 000 tipos de documentos, en más de 48 idiomas.

Qué es el servidor Didit MCP

El Protocolo de Contexto del Modelo (MCP) es un estándar abierto que permite a los agentes de IA llamar a herramientas externas a través de una interfaz consistente. La implementación de Didit en https://mcp.didit.me/mcp es el servidor MCP oficial para la plataforma de identidad y fraude, publicado bajo la licencia MIT en github.com/didit-protocol/mcp. Utiliza transporte HTTP Streamable — sin estado, solo POST, sin Eventos Enviados por el Servidor — y expone 115 herramientas en 11 categorías que cubren la plataforma completa: sesiones, flujos de trabajo, API de verificación, monitoreo de transacciones, detección de lavado de dinero (AML), detección de billeteras, webhooks, casos, informes y operaciones de espacio de trabajo.

La autenticación alojada utiliza OAuth 2.1 con PKCE (Proof Key for Code Exchange) y Registro Dinámico de Clientes (DCR). Cuando el agente se conecta por primera vez, abre un navegador para el flujo de "Iniciar sesión con Didit" a través de business.didit.me. El token resultante tiene un alcance limitado a su usuario de consola en didit:management y didit:verification — el agente solo puede hacer lo que su rol ya permite. Esto es importante: no hay clave API para pegar en un archivo de configuración MCP para el servidor alojado. Las claves API son un concepto de API REST y no se utilizan en el contexto de MCP.

Para conectar el endpoint alojado a Claude Desktop o Claude.ai, use el enlace profundo del conector preconstruido:

Agregar Didit como conector de Claude

Para una descripción general del conjunto completo de herramientas, consulte la referencia de herramientas MCP y la documentación general de MCP.

La secuencia KYC — herramienta por herramienta

Una sesión KYC estándar en Didit agrupa su elección de verificaciones de identidad — verificación de documentos de identidad, prueba de vida pasiva para confirmar que la persona está físicamente presente, coincidencia facial para confirmar que la selfie coincide con el retrato del documento y análisis de IP para señales de fraude — todo por 0,33 $ cuando se configura el paquete completo. Aquí está la secuencia exacta de herramientas que sigue un agente para crear, entregar y resolver una:

1. Descubra su contexto

Antes de crear cualquier cosa, el agente necesita saber en qué organización y aplicación operar. Llame a didit_context_get para listar las organizaciones y aplicaciones disponibles a las que tiene acceso el usuario que ha iniciado sesión. Esto devuelve el organization_id y el application_id que necesita cada llamada de herramienta subsiguiente.

2. Elija un flujo de trabajo

Los flujos de trabajo de verificación definen qué verificaciones se ejecutan y cómo se toman las decisiones. Llame a didit_workflow_list para obtener los flujos de trabajo configurados para su aplicación. Cada flujo de trabajo expone sus características — OCR (reconocimiento óptico de caracteres), prueba de vida, coincidencia facial, AML, cuestionarios — para que el agente pueda elegir el adecuado para el tipo de verificación necesaria. Para una incorporación KYC estándar, el flujo de trabajo suele incluir OCR, prueba de vida, coincidencia facial y análisis de IP.

3. Cree la sesión

Con el flujo de trabajo seleccionado, llame a didit_session_create con el workflow_id y, opcionalmente, su propia referencia externa en vendor_data. El alcance de la organización y la aplicación se resuelven automáticamente cuando no son ambiguos, por lo que rara vez los pasa. También puede establecer el language para la interfaz de usuario de verificación alojada, una callback a la que el solicitante regresa, y datos prellenados a través de contact_details o expected_details. La herramienta devuelve una url — un enlace alojado que envía al solicitante. No se necesita integración de SDK para esta ruta; el solicitante simplemente abre el enlace en su navegador, completa las verificaciones y el agente continúa desde allí.

4. Lea la decisión

Una vez que el solicitante completa las verificaciones, llame a didit_session_get_decision con el ID de sesión. Esto devuelve una decisión de matriz plural V3: una cadena de status, un objeto de decision con veredicto y puntuación de riesgo, y resultados por característica (datos OCR, confianza de la prueba de vida, similitud de coincidencia facial, etc.). El agente lee el veredicto para determinar la siguiente acción.

5. Actúe según la decisión

Llame a didit_session_update_status para establecer el estado de la sesión según el veredicto de la decisión:

• Aprobado — todas las verificaciones pasaron. Establezca el estado en approved para finalizar.
• Rechazado — las verificaciones fallaron o se detectó fraude. Establezca el estado en declined.
• Reenviado — los documentos no estaban claros o el solicitante necesita volver a intentarlo. Establezca el estado en resubmitted para permitir otro intento.

Ese es todo el viaje de ida y vuelta de KYC en cinco herramientas, todo desde una solicitud en lenguaje natural.

Los 10 estados de sesión

Las sesiones de Didit pasan por un ciclo de vida de 10 estados. Un agente configurado para monitorear las sesiones debe manejar cada uno:

• No Iniciado — la sesión fue creada pero el solicitante no ha abierto el enlace de verificación. Aún no se necesita ninguna acción.
• En Progreso — el solicitante abrió el enlace y está pasando por las verificaciones. El agente debe esperar.
• En Revisión — las verificaciones automatizadas terminaron con una puntuación límite; la sesión necesita revisión manual. Notifique a un oficial de cumplimiento humano.
• Aprobado — todas las verificaciones pasaron. Complete la incorporación.
• Rechazado — las verificaciones fallaron. Rechace al solicitante o inicie una nueva verificación con diferentes documentos.
• Caducado — la sesión caducó antes de completarse. Ofrezca una nueva sesión.
• Abandonado — el solicitante cerró el flujo antes de terminar. Envíe un recordatorio o un nuevo enlace.
• KYC Caducado — una sesión de reverificación periódica ha caducado. Señale para una nueva incorporación.
• Reenviado — el solicitante volvió a enviar después de que se le pidieran mejores datos. Vuelva a ejecutar didit_session_get_decision para obtener el nuevo veredicto.
• Esperando Usuario — la sesión está en pausa esperando que el solicitante proporcione información o documentos adicionales.

Controles a nivel de agente: listas, listas de bloqueo y monitoreo continuo

Más allá del KYC de una sola sesión, el servidor MCP brinda a los agentes acceso a la superficie de control de riesgos. Use didit_lists_list y didit_lists_entry_create para agregar solicitantes rechazados a listas de bloqueo, evitando que creen nuevas sesiones. Use didit_blocklist_get y didit_blocklist_add para filtrar nuevas solicitudes de sesión antes de que se creen. Para el monitoreo continuo, después de una aprobación KYC, puede ejecutar didit_verify_aml para la detección de lavado de dinero contra más de 1300 listas de vigilancia a 0,20 $ por verificación, y didit_transaction_screen_wallet para la detección de billeteras de criptomonedas a 0,15 $ por verificación.

Ruta equivalente de la API REST

No todas las integraciones se ejecutan a través de un agente de IA. Si está creando un backend que llama a Didit directamente a través de HTTP, la API REST utiliza autenticación x-api-key (la clave secreta de su aplicación desde la consola). Aquí está la creación de sesión KYC equivalente a través de 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",
    "vendor_data": "user-456",
    "language": "en",
    "callback": "https://myapp.com/kyc-callback"
  }'

La respuesta incluye el session_id y la url — el mismo enlace alojado que devuelve la sesión MCP. Consulte el endpoint de decisión y actualice el estado de la misma manera, pero a través de REST. Tenga en cuenta el encabezado x-api-key: este es el mecanismo de autenticación de la API REST y no está relacionado con el flujo OAuth de MCP descrito anteriormente. La API REST es una superficie separada; el servidor MCP nunca necesita ni utiliza una clave API.

Precios y límites

Cada característica de Didit tiene precios publicados, por éxito, sin mínimos. El servidor MCP en sí es gratuito, no hay cargo por conectar o listar herramientas. Solo paga por las verificaciones exitosas:

• Paquete KYC completo (ID + Prueba de vida pasiva + Coincidencia facial + IP): 0,33 $
• Verificación de ID (independiente): 0,15 $
• Prueba de vida pasiva (independiente): 0,10 $
• Detección AML: 0,20 $ por verificación, más de 1300 listas de vigilancia
• Detección de billeteras (KYT): 0,15 $ por verificación
• Monitoreo de transacciones: 0,02 $ por transacción
• Verificación de negocios (KYB): desde 2,00 $ por negocio

Cada característica incluye 500 verificaciones gratuitas al mes, para siempre. Sin límite de tiempo, sin puerta de nivel. El paquete KYC completo a 0,33 $ es 3-5 veces más barato que los proveedores de KYC tradicionales, con inferencia p99 en menos de 2 segundos en más de 220 países y más de 14 000 tipos de documentos.

Para empezar

Para conectar su agente y comenzar a ejecutar verificaciones KYC en minutos:

1. Abra el enlace profundo del conector de Claude y agregue Didit como un conector personalizado.
2. Para Claude Code: ejecute claude mcp add --transport http didit https://mcp.didit.me/mcp, luego /mcp para autenticarse.
3. Para Cursor: agregue {"mcpServers":{"didit":{"url":"https://mcp.didit.me/mcp"}}} a .cursor/mcp.json.
4. Una vez autenticado, solicite: "Descubra mi organización y aplicaciones, liste los flujos de trabajo de KYC y cree una sesión de verificación para un nuevo solicitante".

El código fuente de MCP es abierto y tiene licencia MIT en github.com/didit-protocol/mcp. Para una explicación más detallada de cómo instalar el servidor en diferentes clientes, lea Cómo instalar el servidor Didit MCP en Claude. Para el catálogo completo de herramientas con parámetros, consulte la Referencia de herramientas de Didit MCP.