Scope & izin peran
Konektor bekerja dengan scopedidit:management dan didit:verification (satu lagi, didit:staff, ditampilkan tetapi hanya berlaku untuk akun staf Didit). Kedua batas ini ditegakkan pada setiap panggilan: token membawa scope yang Anda setujui, dan di dalam batas tersebut, peran konsol Anda menentukan apa yang dapat Anda lakukan. Akses efektif adalah irisan keduanya, sehingga hanya menyetujui didit:verification tetap menutup permukaan manajemen, bahkan untuk OWNER.
Setiap tool dipetakan ke satu izin backend (read:sessions, write:workflows, delete:lists, dan seterusnya; referensi tool mencantumkannya per tool). Server melakukan pemeriksaan awal terhadap izin tersebut menggunakan izin organisasi yang dikembalikan oleh introspeksi token, dikendalikan oleh MCP_PERMISSION_MODE:
MCP tidak pernah melampaui peran Anda. Respons
403 pada satu tool berarti peran Anda tidak memiliki izin tersebut, bukan berarti seluruh koneksi gagal.
Resolusi lintas aplikasi & organisasi
API manajemen Didit dibatasi per aplikasi (/organization/{org}/application/{app}/…). MCP menentukan scope untuk Anda:
- Satu organisasi + aplikasi → ditentukan otomatis; Anda tidak perlu memasukkan ID.
- Beberapa aplikasi → tool lintas aplikasi (
didit_session_search,didit_transaction_search,didit_case_search,didit_vendor_user_search,didit_vendor_business_search,didit_workflow_search,didit_analytics) menggabungkan hasil dari semua aplikasi dalam satu panggilan, dengan setiap baris diberi tandaorganization_id/application_id. - Tool daftar per aplikasi (
didit_session_list,didit_transaction_list,didit_case_list,didit_vendor_user_list,didit_vendor_business_list,didit_workflow_list) otomatis mencakup semua aplikasi jika Anda tidak menentukan salah satunya, sehingga permintaan sederhana “tampilkan daftar sesi saya” tetap berfungsi meskipun Anda memiliki banyak aplikasi. Berikanorganization_id+application_iduntuk mempersempit ke satu aplikasi.
didit_context_get untuk melihat semua organisasi dan aplikasi Anda (beserta ID-nya) dalam satu panggilan. Tool ini juga melaporkan mode setiap aplikasi (live atau sandbox), jadi jangan pernah menebak lingkungan dari nama aplikasi; didit_session_create menerima sandbox_scenario pada aplikasi sandbox untuk uji coba yang tidak ditagih.
Isi katalog yang di-hosting
Konektor yang di-hosting memberi Anda 169 tool. Konektor ini juga mencantumkan 17 tool Investigator, yang hanya dapat digunakan setelah Investigator diaktifkan untuk organisasi Anda. Dua tool lainnya,didit_org_top_up (checkout Stripe) dan didit_org_reveal_application_api_key (rahasia mentah), disembunyikan dari tools/list setiap pemanggil yang diautentikasi dengan OAuth. Lima tool pengaturan akun (didit_account_*) sama sekali dikecualikan dari server jarak jauh dan menolak dijalankan di sana, karena konektor jarak jauh tidak boleh menerima kredensial sebagai argumen tool. Server stdio lokal menyertakan semuanya, total 193.
Setiap tool yang tercantum membawa anotasi MCP (readOnlyHint, destructiveHint, openWorldHint, sebuah title) dan outputSchema, serta label _meta["anthropic/toolGroup"] yang menyebutkan area tool tersebut (Sessions, Workflows & Questionnaires, Transactions (AML), dan seterusnya). Klien seperti Claude menggunakan anotasi ini untuk membagi tool konektor menjadi grup hanya-baca, tulis, dan destruktif.
Alur kerja bercabang
Alur kerja sederhana berupa daftar fitur datar. Untuk logika bersyarat (menolak berdasarkan status, mengarahkan berdasarkan kolom hasil ekstraksi, membatasi langkah berdasarkan kecocokan, atau menambahkan permintaan Document AI), MCP menggunakan graf node Didit (struktur yang sama dengan editor visual di konsol). Graf berbentuk{ start_node, nodes }. Setiap node berupa feature, branch, status (terminal), action, atau webhook. Aturan cabang mendukung operator, termasuk fuzzy_match (untuk kolom string, dengan ambang kemiripan score 0–100) pada kolom hasil ekstraksi seperti kyc.extra_fields.profession. Node fitur DOCUMENT_AI meminta dokumen, misalnya bukti dana.
Mengedit alur kerja yang sudah ada (direkomendasikan)
Alur kerja nyata memiliki konfigurasi fitur yang besar. Daftar izindocuments_allowed untuk OCR bisa mencapai 150 KB lebih, ditambah daftar POA dan daftar negara untuk telepon. Karena itu, jangan membaca seluruh graf lalu mengirim ulangnya. Sebagai gantinya, edit dengan operasi kecil:
1
Temukan & periksa
didit_workflow_search { workflow_id } menemukannya di semua aplikasi Anda. didit_workflow_get_graph mengembalikan struktur dengan konfigurasi besar yang diringkas (tidak pernah melampaui batas; berikan include_config: true untuk nilai mentah). didit_workflow_get_field_definitions mencantumkan kolom yang bisa dijadikan cabang beserta operator yang valid.2
Edit dengan operasi
didit_workflow_edit_graph menerima beberapa operasi kecil, yaitu set_next, set_node, set_branches, dan merge_node_config. MCP mengambil graf lengkap di sisi server, menerapkan operasi tersebut, memvalidasinya, otomatis membuat draf, lalu menyimpannya. Daftar izin Anda dipertahankan byte demi byte dan tidak pernah dikirim dalam permintaan. Jika validasi gagal, hasilnya applied: false dan tidak ada yang disimpan.3
Tinjau & publikasikan
Draf tetap bisa ditinjau sampai Anda
publish (di konsol atau melalui didit_workflow_publish). Versi aktif tidak pernah tersentuh.next node OCR ke cabang baru, lalu tambahkan cabang, node terminal Declined, dan langkah DOCUMENT_AI (yang next-nya kembali ke langkah berikutnya yang asli). 10 node lainnya beserta daftar izinnya tidak diubah.
“Setelah verifikasi identitas, jika ditolak, tolak; jika profesi ≈ ‘Software Engineer’ (≥80%), minta bukti dana; lalu lanjutkan.” → satu nodebranch:kyc.status == Declined→ node statusDeclined;kyc.extra_fields.professionfuzzy_match“Software Engineer” skor 80 → nodeDOCUMENT_AIuntuk bukti dana; dan jalur lainnya kembali ke alur kerja.
Cabang selalu memerlukan lainnya yang eksplisit. Jalur penangkap-semua (jalur yang diambil saat tidak ada kondisi yang cocok) harus berupa cabang dengan
rules kosong, misalnya { "id": "else", "rules": [], "goto": "<liveness>" }, bukan next polos dari node cabang. MCP (dan backend) otomatis mengubah next node cabang menjadi cabang lainnya, sehingga cabang tidak pernah tampil sebagai edge yang ambigu tanpa lainnya yang terlihat.didit_workflow_validate_graph lalu didit_workflow_set_graph (graf lengkap), atau biarkan didit_workflow_build_graph menyusun graf lengkap dari spesifikasi fitur sederhana tanpa menyimpannya. Bahkan didit_workflow_create biasa disimpan sebagai graf node yang sama. MCP menyusun daftar features Anda menjadi node fitur yang dirangkai, diakhiri node status keputusan otomatis, sehingga fitur benar-benar berjalan. Secara default alur kerja dipublikasikan. Berikan status: "draft" untuk menyimpannya tanpa publikasi. Lihat Create Workflow → cabang dan alur kerja berbasis node untuk bentuk JSON lengkapnya.
Cabang alasan skip NFC dengan MCP
Untuk graf baru, mintalah:“Buat alur kerja draf dengan verifikasi identitas diikuti NFC. JikaAgen harus memanggilnfc.skip_reasonbernilaiDEVICE_WITHOUT_NFCatauDOCUMENT_WITHOUT_CHIP, tempatkan sesi dalam peninjauan; jika tidak, setujui. Pertahankan lainnya yang eksplisit dan validasi graf sebelum menyimpan.”
didit_workflow_get_field_definitions, didit_workflow_validate_graph, lalu didit_workflow_set_graph. Untuk alur kerja yang sudah ada, mintalah:
“Edit alur kerjaAgen harus memanggil26d33c04…: setelah node NFC-nya, arahkan nilai apa pun dari tujuh nilainfc.skip_reasonyang dikenal ke dalam peninjauan, dan pertahankan jalur NFC yang berhasil sebagai lainnya yang eksplisit. Simpan sebagai draf; jangan publikasikan.”
didit_workflow_search, didit_workflow_get_graph, didit_workflow_get_field_definitions, lalu didit_workflow_edit_graph. Alat edit menerapkan operasi kecil di sisi server, sehingga node yang tidak terkait dan daftar izin besar tetap dipertahankan. Lihat Create Workflow → Cabang berdasarkan alasan NFC tidak berjalan untuk ketujuh nilai tersebut, aturan equals dan in, perilaku null, serta graf lengkap yang berurutan.
Konfigurasi fitur dan daftar izin
config pada node fitur membatasi apa yang diterimanya. didit_workflow_get_feature_config_schema mengembalikan setiap kunci yang diterima tiap fitur, beserta tipe dan nilai defaultnya. Kedua alat katalog (didit_workflow_get_id_verification_methods_catalog dan didit_workflow_get_kyb_registry_catalog) menjawab pertanyaan yang ditentukan oleh server dan diperlukan oleh konfigurasi. Daftar izin OCR kanonis berbentuk per negara → per dokumen → objek: { "<ISO3>": { "<CODE>": { "enabled": 1 } } } (misalnya { "ESP": { "P": { "enabled": 1 } } }). MCP menormalkan bentuk yang lebih praktis sebelum validasi, sehingga Anda tidak perlu menulis struktur itu secara manual:
poa_languages_allowed pada PROOF_OF_ADDRESS memiliki prinsip yang sama. Berikan array bahasa (["es"]) atau peta ({ "es": 1 }). Penyederhanaan ini berlaku di mana pun Anda memberikan konfigurasi fitur ke MCP: fitur pada didit_workflow_create, serta config node pada set_graph, edit_graph, dan validate_graph.
Bentuk respons (kontrak V3)
Setiap tool mengembalikan JSON apa adanya dari endpoint REST yang mendasarinya. Ada dua hal yang perlu diketahui:- Tool sinkron (alur kerja, penagihan,
verify_*yang berdiri sendiri, pengelolaan daftar) mengembalikan hasil akhirnya secara langsung, sehingga dapat langsung ditindaklanjuti pada giliran yang sama. - Pembuatan sesi bersifat asinkron.
didit_session_createmengembalikanurlyang harus diselesaikan pengguna. Keputusan tiba melalui webhook atau melaluididit_session_get_decision.
node_id untuk setiap entri (id_verifications[], liveness_checks[], face_matches[], aml_screenings[], poa_verifications[], phone_verifications[], email_verifications[], database_validations[], reviews[], serta KYB registry_checks[], document_verifications[], key_people_checks[]). Lihat Model data dan Status verifikasi.
Menangani webhook
Biarkan webhook mengirimkan keputusan akhir ke backend Anda, alih-alih melakukan polling dari agen:- Agen memanggil
didit_webhook_createsekali denganlabel,urlHTTPS publik Anda,webhook_version: "v3", dansubscribed_events(biasanya["status.updated", "data.updated"]). Respons menyamarkan rahasia penandatanganan, begitu puladidit_webhook_getdandidit_webhook_list. Salin rahasia tersebut dari Webhook di konsol, lalu simpan sebagaiDIDIT_WEBHOOK_SECRET. - Backend Anda memverifikasi header X-Signature-V2 kanonis pada setiap pengiriman:
shortenFloats→sortKeys→JSON.stringify(unicode tanpa escape) → HMAC-SHA256 →timingSafeEqual. Tolak jikaabs(now − X-Timestamp) > 300detik. - Deduplikasi berdasarkan
event_id. Kembalikan2xxdalam 5 detik, dan pindahkan pekerjaan berat ke antrean. - Didit mencoba ulang pada
5xx/404hingga 2 kali (sekitar 1 menit, lalu sekitar 4 menit), kemudian membuang pengiriman tersebut. Putar ulang pengiriman yang gagal dari tab Pengiriman di konsol.
Transport dan endpoint
Endpoint ini mendukung dua era: klien yang menetapkan versi protokol 2026-07-28 atau yang lebih baru pada setiap pesan akan melewati handshake
initialize dan dapat memanggil server/discover. Setiap klien yang lebih lama (Claude Code, Cursor, klien berbasis SDK) menggunakan handshake Streamable HTTP standar tanpa perubahan. CORS terbuka, sehingga klien berbasis browser (connector web Claude, MCP Inspector) dapat mengakses /mcp dan dokumen penemuan lintas origin. Batas body JSON adalah 25 MB, cukup untuk input file base64 berukuran 15 MB.
Pemecahan masalah
Agen memanggil tool dan mendapat 403 atau missing_scope
Agen memanggil tool dan mendapat 403 atau missing_scope
Peran Anda di organisasi tersebut tidak memiliki izin yang dibutuhkan tool (misalnya
READER yang mencoba menulis). Error missing_scope menyebutkan izin tersebut. Jika semua tool gagal, sambungkan ulang atau jalankan ulang Log in with Didit. (MCP hanya menggunakan Bearer/OAuth. x-api-key ditolak oleh semua tool, jadi kunci API tidak akan memperbaiki 403.)Operasi penulisan atau penghapusan tidak dijalankan
Operasi penulisan atau penghapusan tidak dijalankan
Tool destruktif memerlukan konfirmasi di klien Anda. Setujui pemanggilan tersebut, atau periksa apakah prompt konfirmasi tool tidak ditolak otomatis.
didit_session_delete, didit_session_batch_delete dan didit_org_reveal_application_api_key juga memerlukan confirm: true pada argumen tool. Tanpa itu, pemanggilan ditolak sebelum apa pun dijalankan.'organization_id is required' atau tidak ada hasil
'organization_id is required' atau tidak ada hasil
Kemungkinan Anda memiliki beberapa aplikasi. Gunakan tool
*_search (yang mencakup semuanya) atau jalankan didit_context_get, lalu berikan organization_id / application_id yang Anda inginkan.Browser tidak terbuka untuk proses masuk (di-hosting)
Browser tidak terbuka untuk proses masuk (di-hosting)
Beberapa klien (Windsurf, Zed) terhubung melalui perantara
mcp-remote. Pastikan npx -y mcp-remote@latest https://mcp.didit.me/mcp ada di konfigurasi. Buka kembali klien untuk memicu ulang handshake OAuth.Tool tidak muncul di klien
Tool tidak muncul di klien
Pastikan server sudah terhubung (sebagian besar klien menampilkan indikator status) dan Anda telah menyelesaikan Log in with Didit. Mulai ulang host MCP setelah mengedit konfigurasinya.
didit_org_top_up dan didit_org_reveal_application_api_key tidak pernah ditampilkan di konektor yang di-hosting.VS Code (atau klien lain) tidak bisa menemukan OAuth atau tidak pernah membuka browser
VS Code (atau klien lain) tidak bisa menemukan OAuth atau tidak pernah membuka browser
Pastikan Anda mengarah ke
https://mcp.didit.me/mcp, bukan ke origin https://mcp.didit.me saja. Metadata resource disajikan di /.well-known/oauth-protected-resource/mcp, dibatasi ke path tersebut (dengan salinan di root origin untuk klien yang mencarinya di sana). Jika Anda melakukan hosting mandiri, biasanya ini berarti MCP_RESOURCE_URI diatur ke origin, bukan ke URL transport lengkap. Lihat Hosting mandiri.Unggahan file ditolak
Unggahan file ditolak
Pada endpoint yang di-hosting, kirim file sebagai
*_base64 (base64 mentah atau URL data:). *_path hanya berfungsi pada server stdio lokal. File dibatasi maksimal 15 MB dan harus berupa PNG, JPG, WebP, GIF, BMP, ICO atau PDF berdasarkan isinya, bukan hanya ekstensinya.Keamanan
MCP bertindak dengan izin yang sebenarnya Anda miliki dan dapat mengubah resource produksi. Pastikan “review tool calls before running” tetap aktif di klien Anda, terutama untuk tool Write dan Destructive. MCP sendiri tidak menyimpan rahasia apa pun dalam konfigurasi Anda (ia menggunakan Masuk dengan Didit), menyamarkan kunci API dan rahasia penandatanganan webhook dalam output tool, menyembunyikan tool isi saldo dan kunci mentah dari katalog yang di-hosting, dan tidak pernah menerima kredensial akun sebagai argumen tool di server jarak jauh. Setiap pemanggilan tool dicatat di log audit server beserta pemanggil, tool, dan keputusan izinnya.Injeksi prompt
Tool Didit mengembalikan apa yang diketik atau diunggah pengguna Anda, seperti nama, teks dokumen, dan jawaban kuesioner. Orang yang sedang diverifikasi mengendalikan teks tersebut, sehingga mereka dapat menulis instruksi untuk agen Anda ke dalam nama atau dokumen, dan server mengembalikan kolom tersebut sebagaimana terekam. Agen tidak dapat membedakan teks itu dari instruksi Anda sendiri secara andal, sehingga perlakukan setiap hasil tool sebagai data:- Biarkan persetujuan tool aktif untuk tool Write dan Destructive, dan baca apa yang akan dilakukan agen sebelum Anda menyetujuinya.
- Masuk sebagai anggota dengan peran yang sesuai dengan pekerjaannya. Agen yang hanya membaca sesi dapat menggunakan anggota dengan peran
READER, dan backend menolak semua operasi penulisan agen, apa pun yang dicobanya. - Coba agen atau prompt baru pada aplikasi sandbox terlebih dahulu.
- Jangan pernah menyetujui atau menolak verifikasi karena teks di dalam verifikasi tersebut memintanya. Andalkan keputusan, peringatannya, dan peninjauan Anda sendiri.
Data pribadi
Hasil tool dapat memuat data pribadi seperti nama, tanggal lahir, nomor dokumen, dan tautan ke gambar, dan klien MCP Anda mengirimkannya ke model yang digunakannya. Sebelum menghubungkan aplikasi produksi, pastikan perjanjian Anda dengan penyedia AI mencakup data ini, atau bekerja pada aplikasi sandbox.Hosting mandiri
Server yang di-hosting dibangun dari github.com/didit-protocol/mcp (MIT). Clone repositori tersebut dan jalankan dengan Docker atau Node. Server ini selalu melakukan autentikasi sebagai pengguna Didit (tidak ada mode kunci API), pada kedua transport. Langkah pengaturan tersedia di Instalasi → hosting mandiri.Variabel lingkungan
.env.example di repositori adalah templat yang dapat disalin, dan ARCHITECTURE.md menjelaskan pemisahan resource server dan authorization server. Saat boot, server HTTP mengambil dokumen discovery dari authorization server dan menggunakan URL yang dikonfigurasi jika server tersebut tidak dapat dijangkau.
Referensi tool
Setiap tool, dikelompokkan per area.
Contoh
Prompt dan percakapan end-to-end.