Langsung ke konten utama

Scope & izin peran

Konektor bekerja dengan scope didit: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 tanda organization_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. Berikan organization_id + application_id untuk mempersempit ke satu aplikasi.
Gunakan 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 izin documents_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.
Misalnya, untuk menyisipkan cabang setelah verifikasi identitas yang tetap tersambung ke alur kerja Anda yang sudah ada, Anda cukup mengirim: arahkan 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 node branch: kyc.status == Declined → node status Declined; kyc.extra_fields.profession fuzzy_match “Software Engineer” skor 80 → node DOCUMENT_AI untuk 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.
Untuk membangun alur kerja baru dari awal, gunakan 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. Jika nfc.skip_reason bernilai DEVICE_WITHOUT_NFC atau DOCUMENT_WITHOUT_CHIP, tempatkan sesi dalam peninjauan; jika tidak, setujui. Pertahankan lainnya yang eksplisit dan validasi graf sebelum menyimpan.”
Agen harus memanggil didit_workflow_get_field_definitions, didit_workflow_validate_graph, lalu didit_workflow_set_graph. Untuk alur kerja yang sudah ada, mintalah:
“Edit alur kerja 26d33c04…: setelah node NFC-nya, arahkan nilai apa pun dari tujuh nilai nfc.skip_reason yang dikenal ke dalam peninjauan, dan pertahankan jalur NFC yang berhasil sebagai lainnya yang eksplisit. Simpan sebagai draf; jangan publikasikan.”
Agen harus memanggil 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_create mengembalikan url yang harus diselesaikan pengguna. Keputusan tiba melalui webhook atau melalui didit_session_get_decision.
Kunci keputusan selalu berupa array jamak dengan 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:
  1. Agen memanggil didit_webhook_create sekali dengan label, url HTTPS publik Anda, webhook_version: "v3", dan subscribed_events (biasanya ["status.updated", "data.updated"]). Respons menyamarkan rahasia penandatanganan, begitu pula didit_webhook_get dan didit_webhook_list. Salin rahasia tersebut dari Webhook di konsol, lalu simpan sebagai DIDIT_WEBHOOK_SECRET.
  2. Backend Anda memverifikasi header X-Signature-V2 kanonis pada setiap pengiriman: shortenFloats → sortKeys → JSON.stringify (unicode tanpa escape) → HMAC-SHA256 → timingSafeEqual. Tolak jika abs(now − X-Timestamp) > 300 detik.
  3. Deduplikasi berdasarkan event_id. Kembalikan 2xx dalam 5 detik, dan pindahkan pekerjaan berat ke antrean.
  4. Didit mencoba ulang pada 5xx / 404 hingga 2 kali (sekitar 1 menit, lalu sekitar 4 menit), kemudian membuang pengiriman tersebut. Putar ulang pengiriman yang gagal dari tab Pengiriman di konsol.
Agen hanya perlu mengonfigurasi penerima webhook; agen tidak mendengarkan sendiri. Kontrak lengkapnya: Webhook.

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

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.)
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.
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.
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.
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.
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.
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.
Terakhir diubah pada 7 November 2026