Cepat atau lambat seseorang akan menjatuhkan foto paspor ke obrolan dengan asisten dan memintanya untuk "isi saja formulirnya". Model visi serbaguna akan mencobanya. Mungkin bahkan namanya benar. Yang tidak akan dilakukannya adalah memberi tahu Anda apakah digit pemeriksa (check digit) di zona baca mesin (MRZ) lolos, mengembalikan tanggal dalam satu format yang sama setiap kali, atau mengatakan "saya tidak bisa membaca ini" alih-alih menebak.

Celah itu cocok diisi oleh sebuah alat (tool). Model Context Protocol memungkinkan agen memanggilnya, dan artikel ini menunjukkan cara memberi Claude Desktop, Claude Code, Cursor dan klien lainnya alat pengenalan dokumen, apa yang diterima agen, cara menjaga biaya tetap terbatas, dan apa yang perlu dipikirkan sebelum Anda mengarahkan agen ke dokumen identitas sama sekali.

Ini adalah blog doc.cheap, API di balik server MCP yang dipakai di sini. Server ini berlisensi MIT, dan pertanyaan-pertanyaan seputar penyiapannya berlaku untuk alat apa pun sejenis ini.

Apa yang didapat agen

Servernya adalah @doc-cheap/mcp di npm (MIT, Node 20 atau lebih baru), dan menyediakan tiga alat:

Alat Fungsinya Memakai kredit?
scan_document Mengenali paspor, kartu identitas nasional atau SIM dari foto atau pindaian dan mengembalikan hasil terstruktur Ya, hanya jika dokumen dikenali
check_balance Membaca sisa kredit dan penghitung bulan ini Tidak (hanya baca)
search_docs Mencari di dokumentasi API yang dibundel bersama server, secara offline Tidak (hanya baca)

Setiap alat membawa judul, deskripsi (dua alat yang menyentuh status akun menyebutkan harganya), dan petunjuk perilaku MCP yang dibaca klien sebelum memutuskan apakah perlu bertanya kepada Anda lebih dulu: scan_document ditandai bukan hanya-baca, dua lainnya hanya-baca. Server juga mengirim instruksi yang dibaca model sebelum panggilan apa pun, berisi apa yang dikenalinya dan berapa biaya sebuah panggilan. Selain alat, ada empat prompt (scan_document_to_json, check_document_expiry, batch_scan, explain_error), dan setiap halaman dokumentasi disediakan sebagai resource hanya-baca, misalnya doccheap://docs/reference/fields.

scan_document menjawab dengan hasil lengkap berupa JSON terstruktur plus ringkasan satu baris, misalnya:

Scan 01a0af18-cd8d-7a61-9f2d-4c7b8e105da3: recognized · passport (GRC) · PARADEIGMA ELENI SOFIA · billed · 684 ms

(Pemegangnya adalah spesimen rekaan dari dokumentasi.) JSON di baliknya memuat pemegang dokumen, nomor dokumen dan tanggal dalam ISO 8601, setiap field dengan pita keyakinan (confidence), baris-baris MRZ dengan verdik passed / failed / absent, dan flag billed. Struktur itulah intinya: agen tidak perlu menafsirkan piksel, ia membaca field.

Instalasi: server lokal

Setiap klien di bawah menjalankan server dengan npx. Tanpa kunci, server memakai kunci sandbox publik, yang memberi total 10 dokumen dikenali gratis per alamat IP dan paling banyak 10 request per jam. Itu cukup untuk mencobanya. Mendaftar memberi 20 kredit gratis; setelah itu satu dokumen yang dikenali berharga $0.01.

Claude Desktop, Cursor dan Windsurf membaca blok yang sama, masing-masing di claude_desktop_config.json, ~/.cursor/mcp.json dan ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "doc-cheap": {
      "command": "npx",
      "args": ["-y", "@doc-cheap/mcp"],
      "env": { "DOC_CHEAP_API_KEY": "sk_live_your_key" }
    }
  }
}

Hilangkan baris env untuk menjalankannya dengan kunci sandbox.

Claude Code:

claude mcp add-json doc-cheap '{"command":"npx","args":["-y","@doc-cheap/mcp"],"env":{"DOC_CHEAP_API_KEY":"sk_live_your_key"}}'

VS Code:

code --add-mcp '{"name":"doc-cheap","command":"npx","args":["-y","@doc-cheap/mcp"]}'

Gemini CLI dan Kiro memakai blok mcpServers yang sama di file pengaturannya masing-masing; panduan MCP memuat path setiap klien. Mulai ulang klien setelah menyunting: server hanya membaca perubahan environment saat diluncurkan dari awal.

Instalasi: server yang di-hosting

Jika klien Anda terhubung ke URL alih-alih menjalankan perintah, tiga alat yang sama di-hosting di https://mcp.doc.cheap/mcp lewat Streamable HTTP, tanpa login. Kunci dikirim di header, X-Doc-Cheap-Api-Key atau Authorization: Bearer (header bernama yang menang jika keduanya dikirim); tanpa kunci, kunci sandbox yang dipakai.

Claude Code:

claude mcp add --transport http doc-cheap https://mcp.doc.cheap/mcp --header "Authorization: Bearer sk_live_your_key"

Cursor:

{
  "mcpServers": {
    "doc-cheap": {
      "url": "https://mcp.doc.cheap/mcp",
      "headers": { "Authorization": "Bearer sk_live_your_key" }
    }
  }
}

Di Claude Desktop dan claude.ai, tambahkan lewat Settings → Connectors sebagai konektor kustom dengan URL tersebut.

Server yang di-hosting tidak bisa melihat file di mesin Anda, jadi di sana scan_document menerima gambar sebagai image_base64 atau sebagai image_url publik.

File lokal dan URL sengaja dipagari

Argumen alat dipilih oleh model, dan model bisa dibujuk melakukan macam-macam. Karena itu server lokal tidak membaca sembarang path:

  • image_path nonaktif sampai Anda mengatur DOC_CHEAP_IMAGE_ROOT ke satu direktori. Path lebih dulu diselesaikan melalui symlink, dan .. atau tautan yang mengarah ke luar direktori ditolak. File yang tidak ada dan file di luar batas mendapat pesan yang sama, sehingga alat ini tidak bisa dipakai untuk menyelidiki apakah sebuah file ada.
  • image_url harus https:, hanya boleh mengarah ke alamat publik (loopback, privat, link-local dan rentang sejenis ditolak), mengikuti paling banyak tiga redirect dengan setiap lompatan diperiksa ulang, dan dibatasi 25 MB.

Jika Anda pernah memasang alat pembaca file untuk agen, bandingkan dengan daftar ini. "Model hanya akan mengirim path yang masuk akal" bukanlah batas keamanan.

Menjaga biaya tetap terbatas

Dua sifat membuat penggunaan oleh agen bisa diprediksi:

  1. Hanya dokumen yang dikenali yang ditagih. Sebuah panggilan dikenai biaya ketika jenis dokumen berhasil ditentukan dan data benar-benar diekstrak: MRZ yang digit pemeriksanya lolos, setidaknya lima field tercetak, atau barcode yang terdekode dengan benar. Tidak ada dokumen, gambar tidak terbaca, jenis tidak didukung, galat internal atau timeout tidak dikenai biaya. Flag billed pada hasil menyatakan mana yang terjadi, setiap kali. Pada kunci sandbox tidak ada yang ditagih sama sekali, dan flag itu lalu menyatakan apakah pindaian yang sama akan ditagih pada kunci live.
  2. Percobaan ulang bisa dibuat gratis. scan_document menerima idempotency_key; pada kunci live, pengulangan dengan kunci yang sama mengembalikan hasil pertama yang tersimpan alih-alih menagih lagi. Percobaan ulang tanpa kunci adalah pindaian kedua. Pengulangan mengembalikan hasil yang tersimpan, jadi retain_hours: 0 dan percobaan ulang yang bisa diputar ulang hanya bisa dipilih salah satu.

Dalam praktiknya:

  • Minta agen memanggil check_balance sebelum satu batch. Instruksi server sendiri menyuruh model melakukannya, dan prompt batch_scan melakukannya lebih dulu. Dengan kunci sandbox, saldonya null, dan alat itu menyatakan tidak ada saldo alih-alih menampilkan nol.
  • Setujui otomatis hanya alat yang hanya-baca. Konfigurasi Kiro, misalnya, mendukung "autoApprove": ["check_balance", "search_docs"]. Biarkan scan_document tetap di balik konfirmasi, karena alat itulah yang memakai kredit.
  • Biarkan agen mencari sendiri. search_docs bekerja offline terhadap dokumentasi yang dibundel, jadi pertanyaan "apa arti unsupported_document" tidak memakan biaya dan tidak bergantung pada ingatan model.

Privasi: pertanyaan yang perlu diajukan sebelum melakukannya

Dokumen identitas termasuk data paling sensitif yang ada, dan agen menambah pihak dalam alurnya. Berikut apa yang berlaku di sisi API, dan apa yang bergantung pada penyiapan Anda.

Di sisi API (sebagaimana didokumentasikan):

  • Gambar yang diunggah disimpan di memori selama request berlangsung dan tidak pernah ditulis ke penyimpanan permanen.
  • Hasil pengenalan disimpan agar bisa dibaca kembali nanti, selama jangka waktu yang diatur di akun (24 jam, 7 hari, 30 hari atau satu tahun). Bawaan untuk akun baru adalah satu tahun. Per panggilan, retain_hours: 0 tidak menulis baris apa pun, dan scan_document juga menerima retain_hours. Jika agen hanya butuh jawabannya sekali, aturlah.
  • Pemrosesan dilakukan di Uni Eropa. Data tidak dipakai untuk melatih model.
  • return_portrait: false menghilangkan images.main_photo, potongan foto pemegang dokumen. Potongan seluruh halaman tetap dikembalikan, begitu pula salinan kedua wajah yang samar yang dicetak di halaman pada sebagian dokumen.

Di sisi Anda:

  • Hasilnya masuk ke konteks model. Apa pun yang dikembalikan scan_document (nama, nomor, tanggal) kini ada di percakapan, dan diproses oleh penyedia LLM mana pun yang menjalankan klien Anda, di bawah ketentuan penyedia tersebut. Ini melekat pada setiap alat MCP, bukan khusus alat ini.
  • Cara gambar dikirim itu penting. Dengan image_path di server lokal, server membaca file dan mengirimnya langsung ke API. Dengan image_base64, byte gambar berada di argumen pemanggilan alat milik model. Jika Anda ingin pikselnya tetap di luar konteks model, gunakan direktori lokal yang dipagari.
  • Ini pengenalan, bukan verifikasi. Grup authenticity pada hasil bernilai not_checked. MRZ yang lolos berarti zona itu terbaca dan konsisten secara internal, bukan bahwa dokumennya asli. Tidak ada langkah liveness atau pencocokan wajah. Jika kasus penggunaan Anda adalah KYC, ini satu masukan, bukan keputusannya.
  • Gunakan dokumen sintetis selama membangun. Spesimen dan MRZ hasil generator sudah cukup untuk merangkai semuanya.

Sesi singkat

Setelah server terpasang, prompt seperti "Baca pindaian paspor ini dan beri tahu saya apakah paspor ini kedaluwarsa dalam enam bulan ke depan" dengan spesimen sintetis terlampir sudah cukup. Agen yang berperilaku baik akan memanggil scan_document, membaca document.expiry_date dan document.days_remaining dari hasilnya, dan menjawab berdasarkan field tersebut, bukan berdasarkan kesannya terhadap gambar. Jika pindaian kembali sebagai unreadable, agen semestinya mengatakannya dan meminta foto yang lebih baik, dan Anda tidak ditagih untuk itu.

Perilaku terakhir itulah alasan sebenarnya untuk memakai alat di sini: agen mendapat "tidak bisa dibaca" yang eksplisit, alih-alih godaan untuk mengisi celah.

Tautan

Jika Anda membangun sesuatu dengannya, atau menemukan klien yang tidak berjalan dengan konfigurasi di atas, tulis ke admin@doc.cheap.

Setiap pernyataan tentang doc.cheap dan server MCP-nya telah diperiksa terhadap kodenya.