Vai al contenuto principale

​
Scope e autorizzazioni dei ruoli

Il connettore funziona con gli scope didit:management e didit:verification (un terzo, didit:staff, è indicato ma ha effetto solo per gli account dello staff di Didit). Entrambi i limiti sono applicati a ogni chiamata: il token contiene gli scope che hai approvato e, entro questi limiti, il tuo ruolo nella console decide cosa puoi fare. L’accesso effettivo è l’intersezione dei due, quindi approvare solo didit:verification tiene chiusa la superficie di gestione anche per un OWNER. Ogni strumento corrisponde a una singola autorizzazione lato backend (read:sessions, write:workflows, delete:lists e così via; il riferimento degli strumenti elenca l’autorizzazione per ogni strumento). Il server verifica in anticipo tale autorizzazione con le autorizzazioni dell’organizzazione restituite dall’introspezione del token; questa verifica è controllata da MCP_PERMISSION_MODE: L’MCP non concede mai più di quanto consenta il tuo ruolo. Un 403 su uno strumento significa che il tuo ruolo non ha quell’autorizzazione, non che l’intera connessione sia fallita.

​
Risoluzione cross-app e dell’organizzazione

L’API di gestione di Didit è limitata per applicazione (/organization/{org}/application/{app}/…). L’MCP risolve l’ambito al posto tuo:
  • Una sola organizzazione e una sola applicazione → risolte automaticamente; non devi mai passare gli ID.
  • Più applicazioni → gli strumenti cross-app (didit_session_search, didit_transaction_search, didit_case_search, didit_vendor_user_search, didit_vendor_business_search, didit_workflow_search, didit_analytics) aggregano i dati di tutte le applicazioni in un’unica chiamata, con ogni riga etichettata con il proprio organization_id / application_id.
  • Gli strumenti di elenco per applicazione (didit_session_list, didit_transaction_list, didit_case_list, didit_vendor_user_list, didit_vendor_business_list, didit_workflow_list) coprono automaticamente tutte le applicazioni quando non ne specifichi una, quindi una semplice richiesta “elenca le mie sessioni” funziona anche con molte applicazioni. Passa organization_id + application_id per limitare il risultato a una sola applicazione.
Usa didit_context_get per vedere tutte le tue organizzazioni e applicazioni (con i relativi ID) in una sola chiamata. Restituisce anche la mode di ogni applicazione (live o sandbox), quindi non dedurre mai l’ambiente dal nome di un’applicazione; didit_session_create accetta un sandbox_scenario sulle applicazioni sandbox per test non fatturati.

​
Cosa contiene il catalogo ospitato

Il connettore ospitato ti mette a disposizione 169 strumenti. Elenca inoltre 17 strumenti Investigator, che funzionano solo dopo che Investigator è stato attivato per la tua organizzazione. Altri due strumenti, didit_org_top_up (checkout Stripe) e didit_org_reveal_application_api_key (segreto in chiaro), sono nascosti da tools/list di ogni chiamante autenticato tramite OAuth. I cinque strumenti di configurazione dell’account (didit_account_*) sono esclusi dai server remoti e rifiutano di essere eseguiti lì, perché un connettore remoto non deve mai ricevere credenziali come argomenti di uno strumento. Un server stdio locale li mantiene tutti, per un totale di 193. Ogni strumento elencato include le annotazioni MCP (readOnlyHint, destructiveHint, openWorldHint, un title) e un outputSchema, oltre a un’etichetta _meta["anthropic/toolGroup"] che indica la sua area (Sessions, Workflows & Questionnaires, Transactions (AML) e così via). Client come Claude usano le annotazioni per suddividere gli strumenti del connettore in gruppi di sola lettura, di scrittura e distruttivi.

​
Workflow con rami condizionali

I workflow semplici sono un elenco piatto di funzionalità. Per la logica condizionale (rifiutare in base a uno stato, instradare in base a un campo estratto, subordinare un passaggio a una corrispondenza o aggiungere una richiesta Document AI), l’MCP usa il grafo dei nodi di Didit, cioè la stessa struttura del builder visuale della console. Un grafo è { start_node, nodes }; ogni nodo è una feature, un branch, uno status (terminale), una action o un webhook. Le regole dei rami supportano operatori tra cui fuzzy_match (per i campi di tipo stringa, con una soglia di somiglianza score da 0 a 100) sui campi estratti come kyc.extra_fields.profession. Un nodo di funzionalità DOCUMENT_AI richiede documenti, ad esempio la prova dei fondi.

​
Modifica di un workflow esistente (consigliato)

I workflow reali contengono configurazioni di funzionalità molto grandi: una lista di valori consentiti OCR documents_allowed può superare i 150 KB, oltre alle liste POA e alle liste di paesi per i numeri di telefono. Quindi non leggere l’intero grafo per poi rinviarlo. Modificalo invece con piccole operazioni:
1

Individua e ispeziona

didit_workflow_search { workflow_id } trova il workflow in tutte le tue app. didit_workflow_get_graph restituisce la struttura con le configurazioni grandi riassunte (non supera mai i limiti di dimensione; passa include_config: true per i valori grezzi). didit_workflow_get_field_definitions elenca i campi su cui è possibile creare rami e gli operatori validi.
2

Modifica con operazioni

didit_workflow_edit_graph accetta poche piccole operazioni: set_next, set_node, set_branches, merge_node_config. L’MCP recupera il grafo completo lato server, applica le operazioni, lo valida, crea automaticamente una bozza e la salva. Le tue liste di valori consentiti vengono conservate byte per byte e non passano mai nella richiesta. Se la validazione fallisce, viene restituito applied: false e non viene salvato nulla.
3

Verifica e pubblica

Resta una bozza da verificare finché non la pubblichi con publish (nella console o tramite didit_workflow_publish). La versione attiva non viene mai modificata.
Per esempio, per inserire un ramo dopo la verifica dell’identità che si ricongiunge alla tua pipeline esistente, devi solo riconfigurare il next del nodo OCR verso un nuovo ramo e aggiungere il ramo, un nodo terminale Declined e un passaggio DOCUMENT_AI il cui next punta di nuovo al passaggio successivo originale. Gli altri 10 nodi e le loro liste di valori consentiti restano invariati.
“Dopo la verifica dell’identità, se è stata rifiutata, rifiuta; se professione ≈ ‘Software Engineer’ (≥80%), richiedi la prova dei fondi; poi continua.” → un nodo branch: kyc.status == Declined → un nodo di stato Declined; kyc.extra_fields.profession fuzzy_match “Software Engineer” con un punteggio di 80 → un nodo DOCUMENT_AI per la prova dei fondi → e un percorso altrimenti che torna nella pipeline.
Un ramo richiede sempre un altrimenti esplicito. Il catch-all (il percorso seguito quando nessuna condizione corrisponde) deve essere un ramo con rules vuoto, ad esempio { "id": "else", "rules": [], "goto": "<liveness>" }, e non il next nudo del nodo ramo. L’MCP (e il backend) convertono automaticamente il next di un nodo ramo in un ramo altrimenti, così un ramo non viene mai mostrato come un collegamento ambiguo senza un altrimenti visibile.
Per costruire un nuovo workflow da zero, usa didit_workflow_validate_graph seguito da didit_workflow_set_graph (grafo completo), oppure lascia che didit_workflow_build_graph assembli un grafo completo da una specifica semplice di funzionalità senza salvarlo. Anche un semplice didit_workflow_create viene salvato come questo stesso grafo di nodi: l’MCP trasforma il tuo elenco features in nodi di funzionalità concatenati che terminano con uno stato di decisione automatica, così le funzionalità vengono effettivamente eseguite. Per impostazione predefinita il workflow viene pubblicato; passa status: "draft" per mantenerlo non pubblicato. Vedi Create Workflow → workflow con rami e basati su nodi per la struttura JSON completa.

​
Rami per i motivi di mancata esecuzione NFC con MCP

Per un nuovo grafo, chiedi:
“Crea una bozza di workflow con la verifica dell’identità seguita da NFC. Se nfc.skip_reason è DEVICE_WITHOUT_NFC o DOCUMENT_WITHOUT_CHIP, invia la sessione a In Review; altrimenti approvala. Mantieni un ramo altrimenti esplicito e valida il grafo prima di salvarlo.”
L’agente deve chiamare didit_workflow_get_field_definitions, didit_workflow_validate_graph, poi didit_workflow_set_graph. Per un workflow esistente, chiedi:
“Modifica il workflow 26d33c04…: dopo il suo nodo NFC, indirizza uno qualsiasi dei sette valori noti di nfc.skip_reason verso In Review e mantieni il percorso NFC riuscito esistente come altrimenti esplicito. Salva una bozza; non pubblicarla.”
L’agente deve chiamare didit_workflow_search, didit_workflow_get_graph, didit_workflow_get_field_definitions, poi didit_workflow_edit_graph. Lo strumento di modifica applica piccole operazioni lato server, quindi conserva i nodi non correlati e le liste di valori consentiti grandi. Vedi Create Workflow → Ramo per capire perché NFC non è stato eseguito per i sette valori, le regole equals/in, il comportamento dei valori null e un grafo completo ordinato.

​
Configurazioni delle funzionalità e liste di valori consentiti

La config di un nodo di funzionalità limita ciò che accetta. didit_workflow_get_feature_config_schema restituisce ogni chiave accettata da ciascuna funzionalità, con tipi e valori predefiniti. I due strumenti di catalogo (didit_workflow_get_id_verification_methods_catalog, didit_workflow_get_kyb_registry_catalog) rispondono alle domande lato server da cui dipende una configurazione. La lista di valori consentiti OCR canonica è organizzata per paese, poi per documento, poi con un oggetto: { "<ISO3>": { "<CODE>": { "enabled": 1 } } } (ad esempio { "ESP": { "P": { "enabled": 1 } } }). L’MCP normalizza forme più semplici prima della validazione, così non devi scrivere a mano questa struttura: PROOF_OF_ADDRESS con poa_languages_allowed segue la stessa logica: passa un array di lingue (["es"]) o una mappa ({ "es": 1 }). Queste comodità si applicano ovunque fornisci all’MCP una configurazione di funzionalità: le funzionalità in didit_workflow_create e le config dei nodi in set_graph, edit_graph e validate_graph.

​
Forma della risposta (contratto V3)

Ogni tool restituisce il JSON originale dell’endpoint REST sottostante. Due aspetti da tenere presenti:
  • I tool sincroni (workflow, fatturazione, verify_* standalone, gestione delle liste) restituiscono il risultato finale direttamente nella risposta: agisci in base ad esso nello stesso turno.
  • La creazione della sessione è asincrona: didit_session_create restituisce un url che l’utente deve completare; la decisione arriva tramite webhook oppure tramite didit_session_get_decision.
Le chiavi delle decisioni sono sempre array al plurale con un node_id per ogni voce (id_verifications[], liveness_checks[], face_matches[], aml_screenings[], poa_verifications[], phone_verifications[], email_verifications[], database_validations[], reviews[], oltre ai registry_checks[], document_verifications[] e key_people_checks[] della verifica KYB). Vedi Modelli di dati e Stati della verifica.

​
Gestione dei webhook

Fai in modo che un webhook consegni la decisione finale al tuo backend, invece di interrogare l’agente con polling:
  1. L’agente chiama didit_webhook_create una sola volta con una label, il tuo url HTTPS pubblico, webhook_version: "v3" e subscribed_events (tipicamente ["status.updated", "data.updated"]). La risposta maschera il segreto di firma, così come didit_webhook_get e didit_webhook_list; copialo da Webhooks nella console e memorizzalo come DIDIT_WEBHOOK_SECRET.
  2. Il tuo backend verifica l’header canonico X-Signature-V2 su ogni consegna: shortenFloats → sortKeys → JSON.stringify (unicode non escapato) → HMAC-SHA256 → timingSafeEqual. Rifiuta la richiesta se abs(now − X-Timestamp) > 300 secondi.
  3. Deduplica in base a event_id. Restituisci 2xx entro 5 secondi; sposta le operazioni pesanti in una coda.
  4. Didit ritenta in caso di 5xx / 404 fino a 2 volte (dopo circa 1 minuto, poi dopo circa 4 minuti), quindi scarta la consegna; ripeti quelle non riuscite dalla scheda Deliveries nella console.
L’agente deve solo configurare il ricevitore; non resta in ascolto autonomamente. Contratto completo: Webhook.

​
Trasporto ed endpoint

L’endpoint è compatibile con due generazioni: i client che fissano una versione del protocollo 2026-07-28 o successiva in ogni messaggio saltano l’handshake initialize e possono chiamare server/discover; ogni client precedente (Claude Code, Cursor, client basati su SDK) usa l’handshake standard di Streamable HTTP senza modifiche. Il CORS è aperto, quindi i client basati su browser (il connettore web di Claude, MCP Inspector) possono raggiungere /mcp e i documenti di discovery da origini diverse. Il limite del corpo JSON è 25 MB, sufficiente per un input di file in base64 da 15 MB.

​
Risoluzione dei problemi

Il tuo ruolo in quell’organizzazione non ha il permesso richiesto dal tool (ad esempio un READER che tenta una scrittura); l’errore missing_scope lo indica. Se tutti i tool falliscono, riconnettiti o riesegui Log in with Didit. (L’MCP supporta solo Bearer/OAuth: un x-api-key viene rifiutato da tutti i tool, quindi una chiave API non risolve un 403.)
I tool distruttivi richiedono una conferma nel tuo client. Approva la chiamata oppure verifica che il prompt di conferma del tool non venga rifiutato automaticamente. didit_session_delete, didit_session_batch_delete e didit_org_reveal_application_api_key richiedono inoltre confirm: true negli argomenti del tool; senza di esso la chiamata viene rifiutata prima che venga eseguito alcunché.
Probabilmente hai più app. Usa un tool *_search (che copre tutto) oppure esegui didit_context_get e passa l’organization_id / application_id che ti interessa.
Alcuni client (Windsurf, Zed) si connettono tramite il bridge mcp-remote: assicurati che npx -y mcp-remote@latest https://mcp.didit.me/mcp sia presente nella configurazione. Riapri il client per riavviare l’handshake OAuth.
Verifica che il server sia connesso (la maggior parte dei client mostra un indicatore di stato) e che tu abbia completato Log in with Didit. Riavvia l’host MCP dopo aver modificato la sua configurazione. didit_org_top_up e didit_org_reveal_application_api_key non sono mai elencati nel connettore ospitato.
Assicurati di puntare a https://mcp.didit.me/mcp, non alla sola origine https://mcp.didit.me: i metadati della risorsa sono serviti in /.well-known/oauth-protected-resource/mcp, limitati a quel percorso (con una copia alla radice dell’origine per i client che la cercano lì). Se usi l’hosting autonomo, di solito significa che MCP_RESOURCE_URI è impostato sull’origine invece che sull’URL di trasporto completo; vedi Self-hosting.
Sull’endpoint ospitato invia il file come *_base64 (base64 grezzo oppure un URL data:); *_path funziona solo su un server stdio locale. I file sono limitati a 15 MB e devono essere PNG, JPG, WebP, GIF, BMP, ICO o PDF in base al contenuto, non solo in base all’estensione.

​
Sicurezza

L’MCP agisce con le tue autorizzazioni reali e può modificare risorse in produzione. Mantieni attivo “review tool calls before running” nel tuo client, soprattutto per gli strumenti Write e Destructive. L’MCP stesso non memorizza nessun segreto nella tua configurazione (usa Accedi con Didit), oscura le chiavi API e i segreti di firma dei webhook nell’output degli strumenti, nasconde gli strumenti di ricarica e quelli per le chiavi grezze dal catalogo ospitato e non accetta mai credenziali dell’account come argomenti degli strumenti su un server remoto. Ogni chiamata a uno strumento viene scritta nel registro di audit del server insieme al chiamante, allo strumento e all’esito del controllo delle autorizzazioni.

​
Prompt injection

Gli strumenti di Didit restituiscono ciò che i tuoi utenti hanno digitato o caricato, come nomi, testo dei documenti e risposte ai questionari. La persona sottoposta a verifica controlla quel testo, quindi può scrivere istruzioni rivolte al tuo agente in un nome o in un documento, e il server restituisce quei campi così come sono stati acquisiti. Un agente non riesce in modo affidabile a distinguere quel testo dalle tue istruzioni, quindi tratta ogni risultato di uno strumento come dato:
  • Mantieni attiva l’approvazione degli strumenti Write e Destructive, e leggi ciò che l’agente sta per fare prima di approvarlo.
  • Accedi come membro il cui ruolo corrisponde al lavoro da svolgere. Un agente che legge soltanto le sessioni può usare un membro READER, e il backend rifiuta le sue operazioni di scrittura qualunque cosa tenti l’agente.
  • Prova prima un nuovo agente o un nuovo prompt su un’applicazione sandbox.
  • Non approvare né rifiutare mai una verifica perché il testo al suo interno lo dice. Affidati alla decisione, agli avvisi e alla tua revisione.

​
Dati personali

I risultati degli strumenti possono includere dati personali come nomi, date di nascita, numeri di documento e link alle immagini, e il tuo client MCP li invia al modello che utilizza. Prima di collegare un’applicazione in produzione, verifica che il tuo accordo con il fornitore di AI copra questi dati, oppure lavora su un’applicazione sandbox.

​
Self-hosting

Il server ospitato è costruito a partire da github.com/didit-protocol/mcp (MIT). Clonalo ed eseguilo con Docker o Node; si autentica sempre come utente di Didit (non esiste una modalità con chiave API), in entrambi i trasporti. I passaggi di configurazione sono nella pagina Installazione → self-hosting.

​
Variabili d’ambiente

Il file .env.example nel repository è un modello da copiare, e ARCHITECTURE.md spiega la separazione tra server delle risorse e server di autorizzazione. All’avvio il server HTTP recupera il documento di discovery del server di autorizzazione e, se non è raggiungibile, usa gli URL configurati.

Riferimento degli strumenti

Ogni strumento, raggruppato per area.

Esempi

Prompt e conversazioni end-to-end.
Ultima modifica il 7 novembre 2026