Didit MCP: avanzado, problemas y autoalojamiento

Scopes y permisos de rol

El conector funciona con los scopes didit:management y didit:verification (hay un tercero, didit:staff, que se anuncia pero solo es relevante para las cuentas del personal de Didit). Ambos límites se aplican en cada llamada: el token lleva los scopes que aprobaste y, dentro de ellos, tu rol en la consola decide lo que puedes hacer. El acceso efectivo es la intersección de ambos, así que si apruebas solo didit:verification, las funciones de gestión siguen cerradas incluso para un OWNER. Cada herramienta corresponde a un permiso del backend (read:sessions, write:workflows, delete:lists, etc.; la referencia de herramientas lo indica para cada herramienta). El servidor comprueba ese permiso de antemano con los permisos de la organización que devuelve la introspección del token, según el valor de MCP_PERMISSION_MODE:

Modo	Comportamiento
`shadow` (predeterminado)	Se listan todas las herramientas; una llamada que tu rol no puede hacer llega al backend, que responde `403`. El resultado queda registrado en el registro de auditoría del servidor.
`enforce`	Las herramientas que tu rol no puede ejecutar no aparecen en `tools/list`; llamar a una devuelve un error `missing_scope` que indica el permiso.
`off`	Sin comprobación previa.

El MCP nunca va más allá de lo que permite tu rol. Un 403 en una herramienta significa que a tu rol le falta ese permiso, no que haya fallado toda la conexión.

Resolución entre aplicaciones y organizaciones

La API de gestión de Didit funciona por aplicación (/organization/{org}/application/{app}/…). El MCP resuelve el ámbito por ti:

Una sola organización y aplicación → se resuelve automáticamente; nunca pasas IDs.
Varias aplicaciones → las herramientas entre aplicaciones (didit_session_search, didit_transaction_search, didit_case_search, didit_vendor_user_search, didit_vendor_business_search, didit_workflow_search, didit_analytics) agregan los datos de todas ellas en una sola llamada, y cada fila lleva su organization_id / application_id.
Las herramientas de listado por aplicación (didit_session_list, didit_transaction_list, didit_case_list, didit_vendor_user_list, didit_vendor_business_list, didit_workflow_list) abarcan automáticamente todas las aplicaciones cuando no especificas ninguna, así que un simple “lista mis sesiones” funciona aunque tengas muchas aplicaciones. Pasa organization_id + application_id para limitarlo a una sola aplicación.

Usa didit_context_get para ver todas tus organizaciones y aplicaciones (y sus IDs) en una sola llamada. También indica el mode de cada aplicación (live o sandbox), así que nunca deduzcas el entorno a partir del nombre de una aplicación; didit_session_create acepta un sandbox_scenario en las aplicaciones de sandbox para hacer pruebas sin facturación.

Qué contiene el catálogo alojado

El conector alojado te ofrece 169 herramientas. También lista 17 herramientas de Investigator, que solo funcionan cuando Investigator está activado para tu organización. Otras dos herramientas, didit_org_top_up (checkout de Stripe) y didit_org_reveal_application_api_key (secreto en claro), están ocultas del tools/list de cualquier cliente autenticado con OAuth. Las cinco herramientas de configuración de cuenta (didit_account_*) están excluidas por completo de los servidores remotos y se niegan a ejecutarse en ellos, porque un conector remoto nunca debe recibir credenciales como argumentos de una herramienta. Un servidor stdio local las conserva todas, 193 en total. Cada herramienta listada lleva anotaciones MCP (readOnlyHint, destructiveHint, openWorldHint, un title), un outputSchema y una etiqueta _meta["anthropic/toolGroup"] que indica su área (Sessions, Workflows & Questionnaires, Transactions (AML), etc.). Clientes como Claude usan las anotaciones para dividir las herramientas del conector en grupos de solo lectura, de escritura y destructivas.

Flujos con ramificaciones

Los flujos de verificación (workflows) sencillos son una lista plana de funciones. Para la lógica condicional (rechazar según un estado, enrutar según un campo extraído, condicionar un paso a una coincidencia, añadir una solicitud de Document AI), el MCP trabaja con el grafo de nodos de Didit, que es la misma estructura del editor visual de la consola. Un grafo es { start_node, nodes }; cada nodo es de tipo feature, branch, status (terminal), action o webhook. Las reglas de las ramas admiten operadores como fuzzy_match (campos de texto, con un umbral de similitud score de 0 a 100) sobre campos extraídos como kyc.extra_fields.profession, y un nodo de función DOCUMENT_AI solicita documentos (por ejemplo, una prueba de fondos).

Editar un flujo existente (recomendado)

Los flujos reales incluyen configuraciones de funciones grandes: una lista de documentos permitidos documents_allowed de OCR puede superar los 150 KB, además de las listas de prueba de domicilio y las de países de teléfono. Por eso, no leas el grafo completo para reenviarlo después. Edítalo con operaciones pequeñas:

Localiza e inspecciona

didit_workflow_search { workflow_id } lo encuentra en todas tus aplicaciones. didit_workflow_get_graph devuelve la estructura con las configuraciones grandes resumidas (nunca se desborda; pasa include_config: true para obtener los valores sin procesar); didit_workflow_get_field_definitions enumera los campos sobre los que se puede ramificar y los operadores válidos.

Edita con operaciones

didit_workflow_edit_graph recibe unas pocas operaciones pequeñas (set_next, set_node, set_branches, merge_node_config) y el MCP obtiene el grafo completo en el servidor, las aplica, valida el resultado, crea automáticamente un borrador y lo guarda. Tus listas de permitidos se conservan byte a byte y nunca pasan por la solicitud. Si la validación falla, devuelve applied: false (no se guarda nada).

Revisa y publica

Sigue siendo un borrador revisable hasta que ejecutes publish (en la consola o con didit_workflow_publish). La versión en producción nunca se modifica.

Por ejemplo, para insertar una rama después de la verificación de identidad que se reincorpore a tu flujo existente, solo envías esto: redirige el next del nodo de OCR a una rama nueva y añade la rama, un nodo terminal Declined y un paso DOCUMENT_AI (cuyo next apunta de vuelta al paso siguiente original). Los otros 10 nodos, y sus listas de permitidos, no se tocan.

“Después de la verificación de identidad, si se rechazó, rechaza; si la profesión ≈ ‘Software Engineer’ (≥80%), solicita una prueba de fondos; después, continúa.” → un nodo branch: kyc.status == Declined → un nodo de estado Declined; kyc.extra_fields.profession fuzzy_match “Software Engineer” con una puntuación de 80 → un nodo DOCUMENT_AI de prueba de fondos → y una ruta si no que vuelve al flujo.

Una rama siempre necesita una ruta «si no» explícita. La ruta por defecto (la que se toma cuando no se cumple ninguna condición) debe ser una rama con rules vacío, por ejemplo { "id": "else", "rules": [], "goto": "<liveness>" }, y no el next sin más del nodo de rama. El MCP (y el backend) convierten automáticamente el next de un nodo de rama en una rama «si no», de modo que una rama nunca se muestra como una conexión ambigua sin una ruta «si no» visible.

Para crear un flujo nuevo desde cero, usa didit_workflow_validate_graph y después didit_workflow_set_graph (grafo completo), o deja que didit_workflow_build_graph arme un grafo completo a partir de una especificación sencilla de funciones sin guardarlo. Incluso un didit_workflow_create simple se guarda como este mismo grafo de nodos: el MCP convierte tu lista features en nodos de función encadenados que terminan en un estado de decisión automática, para que las funciones se ejecuten de verdad (por defecto lo publica; pasa status: "draft" para dejarlo sin publicar). Consulta Crear flujo → flujos con ramificaciones y basados en nodos para ver la estructura JSON completa.

Ramas según el motivo de omisión de NFC con MCP

Para un grafo nuevo, pide:

“Crea un flujo en borrador con verificación de identidad seguida de NFC. Si nfc.skip_reason es DEVICE_WITHOUT_NFC o DOCUMENT_WITHOUT_CHIP, envía la sesión a En revisión; en caso contrario, apruébala. Mantén una rama «si no» explícita y valida el grafo antes de guardarlo.”

El agente debe llamar a didit_workflow_get_field_definitions, didit_workflow_validate_graph y después a didit_workflow_set_graph. Para un flujo existente, pide:

“Edita el flujo 26d33c04…: después de su nodo NFC, envía cualquiera de los siete valores conocidos de nfc.skip_reason a En revisión y conserva la ruta existente para un NFC exitoso como la rama «si no» explícita. Guarda un borrador; no lo publiques.”

El agente debe llamar a didit_workflow_search, didit_workflow_get_graph, didit_workflow_get_field_definitions y después a didit_workflow_edit_graph. La herramienta de edición aplica operaciones pequeñas en el servidor, por lo que conserva los nodos no relacionados y las listas de permitidos grandes. Consulta Crear flujo → Ramificar según por qué no se ejecutó NFC para ver los siete valores, las reglas equals/in, el comportamiento con valores nulos y un grafo completo ordenado.

Configuraciones de funciones y listas de permitidos

El config de un nodo de función restringe lo que acepta. didit_workflow_get_feature_config_schema devuelve todas las claves que admite cada función, con sus tipos y valores por defecto, y las dos herramientas de catálogo (didit_workflow_get_id_verification_methods_catalog, didit_workflow_get_kyb_registry_catalog) responden a las preguntas controladas por el servidor de las que depende una configuración. La lista canónica de permitidos de OCR se organiza por país → por documento → objeto: { "<ISO3>": { "<CODE>": { "enabled": 1 } } } (por ejemplo, { "ESP": { "P": { "enabled": 1 } } }). El MCP normaliza formatos más cómodos por ti antes de validar, así que no tienes que escribir esa estructura a mano:

Puedes pasar	Se normaliza a
Un array de tipos de documento: `["PASSPORT"]`	ese documento para todos los países (solo pasaporte en todo el mundo)
Nombres o códigos de documento: `PASSPORT`/`P`, `NATIONAL_ID`/`ID`, `DRIVER_LICENSE`/`DL`, `RESIDENCE_PERMIT`/`RP` (también `SSC`, `HIC`, `TC`)	el código canónico
Una clave de país `"ALL"`: `{ "ALL": { "P": 1 } }`	se aplica a todos los países
Indicadores escalares: `{ "ESP": { "P": 1 } }`	`{ "ESP": { "P": { "enabled": 1 } } }`
Omitirlo por completo	todos los documentos, todos los países

El poa_languages_allowed de PROOF_OF_ADDRESS funciona igual: pasa un array de idiomas (["es"]) o un mapa ({ "es": 1 }). Estas facilidades se aplican siempre que le das al MCP una configuración de función: las funciones de didit_workflow_create y los config de los nodos en set_graph / edit_graph / validate_graph.

Forma de la respuesta (contrato V3)

Cada herramienta devuelve el JSON literal del endpoint REST subyacente. Hay dos cosas que debes saber:

Las herramientas síncronas (flujos, facturación, verify_* independientes, gestión de listas) devuelven su resultado final en línea: actúa sobre él en el mismo turno.
La creación de sesiones es asíncrona: didit_session_create devuelve una url que el usuario debe completar; la decisión llega por webhook o mediante didit_session_get_decision.

Las claves de la decisión son siempre arrays en plural con un node_id por entrada (id_verifications[], liveness_checks[], face_matches[], aml_screenings[], poa_verifications[], phone_verifications[], email_verifications[], database_validations[], reviews[], además de los de KYB registry_checks[], document_verifications[], key_people_checks[]). Consulta Modelos de datos y Estados de verificación.

Gestión de webhooks

Deja que un webhook entregue la decisión final a tu backend en lugar de consultarla periódicamente desde el agente:

El agente invoca una sola vez didit_webhook_create con un label, tu url HTTPS pública, webhook_version: "v3" y subscribed_events (normalmente ["status.updated", "data.updated"]). La respuesta oculta el secreto de firma, al igual que didit_webhook_get y didit_webhook_list; cópialo desde Webhooks en la consola y guárdalo como DIDIT_WEBHOOK_SECRET.
Tu backend verifica el encabezado canónico X-Signature-V2 en cada entrega: shortenFloats → sortKeys → JSON.stringify (unicode sin escapar) → HMAC-SHA256 → timingSafeEqual. Rechaza la entrega si abs(now − X-Timestamp) > 300 segundos.
Elimina duplicados por event_id. Devuelve 2xx en un máximo de 5 segundos; traslada el trabajo pesado a una cola.
Didit reintenta ante 5xx / 404 hasta 2 veces (~1 min y después ~4 min) y luego descarta la entrega; vuelve a enviar las fallidas desde la pestaña Deliveries de la consola.

El agente solo necesita configurar el receptor; no escucha por sí mismo. Contrato completo: Webhooks.

Transporte y endpoints

Endpoint	Propósito
`POST https://mcp.didit.me/mcp`	El endpoint MCP (Streamable HTTP). `GET` y `DELETE` responden `405`: el servidor no tiene estado, crea una instancia nueva del servidor por cada solicitud y no mantiene ningún stream iniciado por el servidor ni ninguna sesión que cerrar.
`GET https://mcp.didit.me/healthz`	Comprobación de estado: `{ "status": "ok", "service": "didit-mcp-server", "version": "5.1.1" }`.
`GET https://mcp.didit.me/.well-known/oauth-protected-resource/mcp`	Metadatos de recurso protegido según RFC 9728 (también se sirven en la raíz del origen).

El endpoint admite dos generaciones del protocolo: los clientes que fijan en cada mensaje una versión del protocolo 2026-07-28 o posterior omiten el handshake initialize y pueden invocar server/discover; todos los clientes anteriores (Claude Code, Cursor, clientes basados en SDK) usan sin cambios el handshake estándar de Streamable HTTP. CORS está abierto, por lo que los clientes basados en navegador (el conector web de Claude, MCP Inspector) pueden acceder a /mcp y a los documentos de descubrimiento desde otros orígenes. El límite del cuerpo JSON es de 25 MB, suficiente para un archivo de entrada de 15 MB en base64.

Solución de problemas

El agente llama a una herramienta y recibe un 403 o missing_scope

Tu rol en esa organización no tiene el permiso que necesita la herramienta (por ejemplo, un READER que intenta escribir); el error missing_scope indica cuál es. Si fallan todas las herramientas, vuelve a conectarte o repite Log in with Didit. (El MCP solo admite Bearer/OAuth: todas las herramientas rechazan una x-api-key, así que una clave de API no resolverá un 403).

Una operación de escritura o eliminación no se ejecutó

Las herramientas destructivas requieren confirmación en tu cliente. Aprueba la llamada o comprueba que el aviso de confirmación de la herramienta no se esté denegando automáticamente. didit_session_delete, didit_session_batch_delete y didit_org_reveal_application_api_key necesitan además confirm: true en los argumentos de la herramienta; sin él, la llamada se rechaza antes de que se ejecute nada.

'organization_id is required' o no hay resultados

Probablemente tienes varias aplicaciones. Usa una herramienta *_search (que abarca todo) o ejecuta didit_context_get y pasa el organization_id / application_id que quieras.

El navegador no se abrió para iniciar sesión (alojado)

Algunos clientes (Windsurf, Zed) se conectan a través del puente mcp-remote: asegúrate de que npx -y mcp-remote@latest https://mcp.didit.me/mcp esté en la configuración. Vuelve a abrir el cliente para iniciar de nuevo el handshake de OAuth.

Las herramientas no aparecen en el cliente

Confirma que el servidor se conectó (la mayoría de los clientes muestran un indicador de estado) y que completaste Log in with Didit. Reinicia el host MCP después de editar su configuración. didit_org_top_up y didit_org_reveal_application_api_key nunca aparecen en el conector alojado.

VS Code (u otro cliente) no puede detectar OAuth o nunca abre un navegador

Asegúrate de apuntar a https://mcp.didit.me/mcp y no al origen sin ruta https://mcp.didit.me: los metadatos del recurso se sirven en /.well-known/oauth-protected-resource/mcp, con ámbito limitado a esa ruta (con una copia en la raíz del origen para los clientes que la consultan allí). Si usas tu propio alojamiento, esto suele significar que MCP_RESOURCE_URI está configurado con el origen en lugar de la URL de transporte completa; consulta Autoalojamiento.

Se rechaza la subida de un archivo

Con el endpoint alojado, envía el archivo como *_base64 (base64 sin procesar o una URL data:); *_path solo funciona en un servidor stdio local. Los archivos tienen un límite de 15 MB y deben ser PNG, JPG, WebP, GIF, BMP, ICO o PDF por su contenido, no solo por su extensión.

Seguridad

El MCP actúa con tus permisos reales y puede modificar recursos en producción. Mantén activada en tu cliente la opción “review tool calls before running”, sobre todo para las herramientas de Escritura y Destructivas. El propio MCP no guarda ningún secreto en tu configuración (usa Log in with Didit), oculta las claves de API y los secretos de firma de webhooks en la salida de las herramientas, retira del catálogo alojado las herramientas de recarga y de claves sin procesar, y nunca acepta credenciales de cuenta como argumentos de herramientas en un servidor remoto. Cada llamada a una herramienta queda registrada en el registro de auditoría del servidor con quién la hizo, la herramienta y el resultado de la comprobación de permisos.

Inyección de prompts

Las herramientas de Didit devuelven lo que tus usuarios escribieron o subieron, como nombres, texto de documentos y respuestas a cuestionarios. La persona que se está verificando controla ese texto, así que puede escribir instrucciones dirigidas a tu agente en un nombre o en un documento, y el servidor devuelve esos campos tal como se capturaron. Un agente no puede distinguir con fiabilidad ese texto de tus propias instrucciones, así que trata cada resultado de una herramienta como datos:

Mantén activa la aprobación de herramientas para las herramientas de Escritura y Destructivas, y lee lo que el agente va a hacer antes de aprobarlo.
Inicia sesión como un miembro cuyo rol se ajuste a la tarea. Un agente que solo lee sesiones puede usar un miembro READER, y el backend rechaza sus operaciones de escritura intente lo que intente el agente.
Prueba primero cualquier agente o prompt nuevo en una aplicación de sandbox.
Nunca apruebes ni rechaces una verificación porque lo indique un texto dentro de esa verificación. Básate en la decisión, sus advertencias y tu propia revisión.

Datos personales

Los resultados de las herramientas pueden incluir datos personales como nombres, fechas de nacimiento, números de documento y enlaces a imágenes, y tu cliente MCP los envía al modelo que utiliza. Antes de conectar una aplicación en producción, comprueba que tu acuerdo con tu proveedor de IA cubre estos datos, o trabaja con una aplicación de sandbox.

Autoalojamiento

El servidor alojado se construye a partir de github.com/didit-protocol/mcp (MIT). Clónalo y ejecútalo con Docker o Node; siempre se autentica como un usuario de Didit (no existe un modo con clave de API), en cualquiera de los dos transportes. Los pasos de configuración están en Instalación → autoalojamiento.

git clone https://github.com/didit-protocol/mcp.git && cd mcp

# Docker (recommended) — serves /mcp + /healthz on port 3000
docker build -t didit-mcp . && docker run -p 3000:3000 --env-file .env didit-mcp

# …or with Node
npm install && npm run build
node dist/http.js                                          # hosted HTTP/OAuth
DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js  # stdio (headless)

Variables de entorno

Variable	Modo	Finalidad
`DIDIT_ACCESS_TOKEN`	stdio	Token de acceso Bearer del usuario para ejecuciones sin interfaz.
`DIDIT_API_BASE_URL`	ambos	Base de la API de verificación (por defecto `https://verification.didit.me/v3`).
`DIDIT_AUTH_BASE_URL`	ambos	Base de la API de autenticación (por defecto `https://apx.didit.me/auth/v2`).
`MCP_PORT`	alojado	Puerto de escucha HTTP (por defecto `3000`).
`MCP_RESOURCE_URI`	alojado	URL pública del transporte, ruta incluida (por ejemplo `https://mcp.example.com/mcp`). La URL de metadatos RFC 9728 se deriva de ella.
`MCP_AUTHORIZATION_SERVER_ORIGIN`	alojado	Origen del servidor de autorización (por defecto `https://business.didit.me`).
`MCP_TOKEN_VERIFY_MODE`	alojado	`introspection` (por defecto; tokens opacos) o `jwks` (tokens de acceso JWT).
`MCP_OAUTH_INTROSPECT_URL`	alojado	Endpoint de introspección RFC 7662.
`MCP_OAUTH_CLIENT_ID` / `MCP_OAUTH_CLIENT_SECRET`	alojado	Credenciales de autenticación básica que el servidor de recursos usa para invocar el endpoint de introspección. Proporciónalas desde un gestor de secretos.
`MCP_SCOPES_SUPPORTED`	alojado	Scopes anunciados en los metadatos (por defecto `didit:management didit:verification`).
`MCP_DEFAULT_ORG` / `MCP_DEFAULT_APP`	ambos	Rellenan automáticamente el scope en despliegues de un solo inquilino.
`DIDIT_AUTH_ISSUER`, `DIDIT_OIDC_DISCOVERY_URL`, `DIDIT_OIDC_AUTHORIZE_URL`, `DIDIT_OIDC_TOKEN_URL`, `DIDIT_OIDC_REGISTRATION_URL`	alojado	Sustituyen los metadatos del servidor de autorización; solo hacen falta cuando publica sus endpoints en un lugar distinto de los predeterminados del origen.
`DIDIT_JWKS_URL`	alojado	JWKS utilizado cuando `MCP_TOKEN_VERIFY_MODE=jwks`.
`MCP_PERMISSION_MODE`	ambos	Comprobación previa de permisos por herramienta: `shadow` (por defecto), `enforce` u `off`.
`MCP_JSON_BODY_LIMIT`	alojado	Límite del cuerpo JSON-RPC (por defecto `25mb`).

.env.example en el repositorio es una plantilla que puedes copiar, y ARCHITECTURE.md explica la separación entre servidor de recursos y servidor de autorización. Al arrancar, el servidor HTTP obtiene el documento de descubrimiento del servidor de autorización y, si no está accesible, recurre a las URL configuradas.

Referencia de herramientas

Todas las herramientas, agrupadas por área.

Ejemplos

Prompts y conversaciones de principio a fin.

Guías

Autenticación

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDK de servidor

Integraciones

Didit MCP: avanzado, problemas y autoalojamiento

Scopes y permisos de rol

Resolución entre aplicaciones y organizaciones

Qué contiene el catálogo alojado

Flujos con ramificaciones

Editar un flujo existente (recomendado)

Ramas según el motivo de omisión de NFC con MCP

Configuraciones de funciones y listas de permitidos

Forma de la respuesta (contrato V3)

Gestión de webhooks

Transporte y endpoints

Solución de problemas

Seguridad

Inyección de prompts

Datos personales

Autoalojamiento

Variables de entorno

Referencia de herramientas

Ejemplos

​Scopes y permisos de rol

​Resolución entre aplicaciones y organizaciones

​Qué contiene el catálogo alojado

​Flujos con ramificaciones

​Editar un flujo existente (recomendado)

​Ramas según el motivo de omisión de NFC con MCP

​Configuraciones de funciones y listas de permitidos

​Forma de la respuesta (contrato V3)

​Gestión de webhooks

​Transporte y endpoints

​Solución de problemas

​Seguridad

​Inyección de prompts

​Datos personales

​Autoalojamiento

​Variables de entorno

Referencia de herramientas

Ejemplos

Scopes y permisos de rol

Resolución entre aplicaciones y organizaciones

Qué contiene el catálogo alojado

Flujos con ramificaciones

Editar un flujo existente (recomendado)

Ramas según el motivo de omisión de NFC con MCP

Configuraciones de funciones y listas de permitidos

Forma de la respuesta (contrato V3)

Gestión de webhooks

Transporte y endpoints

Solución de problemas

Seguridad

Inyección de prompts

Datos personales

Autoalojamiento

Variables de entorno