> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Didit MCP: avanzado, problemas y autoalojamiento > Didit MCP avanzado: roles y permisos, uso entre apps, catálogo alojado, flujos con ramas, webhooks, transporte, errores 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](https://docs.didit.me/es/integration/mcp/tools.md) 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: **1. 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. **2. 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). **3. 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. > [!NOTE] > > **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": "" }`, 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](https://docs.didit.me/es/management-api/workflows/create.md) 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](https://docs.didit.me/es/management-api/workflows/create.md#ramificar-según-el-motivo-por-el-que-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: `{ "": { "": { "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](https://docs.didit.me/es/reference/data-models.md) y [Estados de verificación](https://docs.didit.me/es/integration/verification-statuses.md). *** ## 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: 1. 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`. 2. 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. 3. Elimina duplicados por `event_id`. Devuelve `2xx` en un máximo de **5 segundos**; traslada el trabajo pesado a una cola. 4. 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](https://docs.didit.me/es/integration/webhooks.md). *** ## 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 > [accordion] 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). > [accordion] 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. > [accordion] '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. > [accordion] 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. > [accordion] 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. > [accordion] 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](#autoalojamiento). > [accordion] 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](https://docs.didit.me/es/integration/sandbox-testing.md). * 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](https://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](https://docs.didit.me/es/integration/mcp/installation.md#alojamiento-propio). ```bash theme={null} 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= 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. *** > [card] [Referencia de herramientas](https://docs.didit.me/es/integration/mcp/tools.md) > > Todas las herramientas, agrupadas por área. > [card] [Ejemplos](https://docs.didit.me/es/integration/mcp/examples.md) > > Prompts y conversaciones de principio a fin. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.