Er ya da geç biri bir asistanla yaptığı sohbete bir pasaport fotoğrafı bırakır ve "formu doldurur musun" der. Genel amaçlı bir görüntü modeli bunu dener. Belki adı bile doğru bulur. Yapmayacağı şey ise makine tarafından okunabilir bölgenin (MRZ) kontrol hanelerinin tutup tutmadığını söylemek, tarihleri her seferinde tek bir biçimde döndürmek ya da tahmin etmek yerine "bunu okuyamadım" demektir.

Bu boşluk tam bir araç işidir. Model Context Protocol bir ajanın araç çağırmasını sağlar. Bu yazıda Claude Desktop, Claude Code, Cursor ve diğer istemcilere bir belge tanıma aracı vermeyi, ajanın geri ne aldığını, maliyeti nasıl sınırlı tutacağınızı ve bir ajanı kimlik belgelerine yöneltmeden önce neleri düşünmeniz gerektiğini anlatıyoruz.

Burası doc.cheap'in blogu; doc.cheap, burada kullanılan MCP sunucusunun arkasındaki API'dir. Sunucu MIT lisanslıdır ve kurulumla ilgili sorular bu türdeki her araç için geçerlidir.

Ajan ne alır

Sunucu npm'de @doc-cheap/mcp adıyla yayımlanıyor (MIT, Node 20 veya üstü) ve üç araç sunuyor:

Araç Ne yapar Kredi harcar mı?
scan_document Bir fotoğraf ya da taramadan pasaport, ulusal kimlik kartı veya sürücü belgesini tanır ve yapılandırılmış sonucu döndürür Evet, yalnızca bir belge tanındığında
check_balance Kalan kredileri ve bu ayın sayaçlarını okur Hayır (salt okunur)
search_docs Sunucuyla birlikte gelen API belgelerinde çevrimdışı arama yapar Hayır (salt okunur)

Her aracın bir başlığı, bir açıklaması (hesap durumuna dokunan ikisinin açıklaması fiyatı belirtir) ve bir istemcinin size önce sorup sormayacağına karar vermeden okuduğu MCP davranış ipuçları vardır: scan_document salt okunur değil, diğer ikisi salt okunur olarak işaretlidir. Sunucu ayrıca modelin herhangi bir çağrıdan önce okuduğu, neyi tanıdığını ve bir çağrının ne tuttuğunu söyleyen talimatlar gönderir. Araçların üzerine dört prompt (scan_document_to_json, check_document_expiry, batch_scan, explain_error) vardır ve her belge sayfası doccheap://docs/reference/fields gibi salt okunur bir kaynak olarak sunulur.

scan_document, tam sonucu yapılandırılmış JSON olarak ve tek satırlık bir özetle birlikte döndürür, örneğin:

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

(Belgelerdeki uydurma bir örnek belge sahibi.) Arkasındaki JSON'da belge sahibi, belge numarası ve ISO 8601 biçiminde tarihler, güven bandıyla her alan, passed / failed / absent kararıyla MRZ satırları ve bir billed bayrağı bulunur. Asıl mesele bu yapıdır: ajanın pikselleri yorumlaması gerekmez, alanları okur.

Kurulum: yerel sunucu

Aşağıdaki her istemci sunucuyu npx ile başlatır. Anahtar ayarlanmamışsa herkese açık sandbox anahtarını kullanır; bu da IP adresi başına toplamda 10 ücretsiz tanınmış belge ve saatte en fazla 10 istek demektir. Denemek için yeterli. Kayıt olmak 20 ücretsiz kredi verir; sonrasında tanınmış bir belge $0.01 tutar.

Claude Desktop, Cursor ve Windsurf aynı bloğu okur; sırasıyla claude_desktop_config.json, ~/.cursor/mcp.json ve ~/.codeium/windsurf/mcp_config.json dosyalarında:

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

Sandbox anahtarıyla çalıştırmak için env satırını çıkarın.

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 ve Kiro, kendi ayar dosyalarında aynı mcpServers bloğunu kullanır; her birinin yolu MCP rehberinde (İngilizce) yer alıyor. Düzenledikten sonra istemciyi yeniden başlatın: sunucu değişen bir ortamı yalnızca yeni bir başlatmada algılar.

Kurulum: barındırılan sunucu

İstemciniz bir komut başlatmak yerine bir URL'ye bağlanıyorsa, aynı üç araç Streamable HTTP üzerinden, oturum açma gerektirmeden https://mcp.doc.cheap/mcp adresinde barındırılıyor. Anahtar bir başlıkta gider: X-Doc-Cheap-Api-Key ya da Authorization: Bearer (ikisi birden gönderilirse adlandırılmış başlık kazanır); anahtar yoksa sandbox anahtarı kullanılır.

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" }
    }
  }
}

Claude Desktop'ta ve claude.ai'de bunu Settings → Connectors altında, o URL ile özel bir bağlayıcı (custom connector) olarak ekleyin.

Barındırılan sunucu makinenizdeki dosyaları göremez; bu yüzden orada scan_document görüntüyü image_base64 ya da herkese açık bir image_url olarak alır.

Yerel dosyalar ve URL'ler bilinçli olarak sınırlandırılmıştır

Bir araç argümanını model seçer ve bir model bir şeylere ikna edilebilir. Bu yüzden yerel sunucu rastgele yolları okumaz:

  • image_path, siz DOC_CHEAP_IMAGE_ROOT değerini tek bir dizine ayarlayana kadar kapalıdır. Yollar önce sembolik bağlantılar üzerinden çözümlenir; .. ya da dizinin dışını gösteren bir bağlantı reddedilir. Var olmayan bir dosya ile sınırların dışındaki bir dosya aynı mesajı alır; böylece araç, bir dosyanın var olup olmadığını yoklamak için kullanılamaz.
  • image_url mutlaka https: olmalı, yalnızca herkese açık adreslere çözümlenmelidir (loopback, özel, link-local ve benzeri aralıklar reddedilir); en fazla üç yönlendirmeyi, her adımı yeniden kontrol ederek izler ve 25 MB ile sınırlıdır.

Daha önce bir ajan için dosya okuyan bir araç bağladıysanız, onu bu listeyle karşılaştırın. "Model yalnızca makul yollar geçirir" bir güvenlik sınırı değildir.

Maliyeti sınırlı tutmak

İki özellik, ajan kullanımını öngörülebilir kılar:

  1. Yalnızca tanınan belgeler ücretlendirilir. Bir çağrı, belge türü belirlendiğinde ve veri gerçekten çıkarıldığında ücretlendirilir: kontrol haneleri tutan bir MRZ, en az beş basılı alan ya da doğru çözülmüş bir barkod. Belge bulunamaması, okunamayan bir görüntü, desteklenmeyen bir tür, bir iç hata ya da bir zaman aşımı ücretsizdir. Sonucun billed bayrağı her seferinde hangisinin olduğunu söyler. Sandbox anahtarında hiçbir ücret alınmaz; bayrak o zaman aynı taramanın canlı bir anahtarda ücretlendirilip ücretlendirilmeyeceğini söyler.
  2. Yeniden denemeler ücretsiz hale getirilebilir. scan_document bir idempotency_key kabul eder; canlı bir anahtarda, aynı anahtarla yapılan bir tekrar, yeniden ücret almak yerine saklanan ilk sonucu döndürür. Anahtarsız bir yeniden deneme ikinci bir taramadır. Tekrar, saklanan sonucu döndürür; yani retain_hours: 0 ile tekrarlanabilir yeniden denemeler ya biri ya öbürüdür.

Pratikte:

  • Bir toplu işten önce ajana check_balance çağırtın. Sunucunun kendi talimatları modele bunu yapmasını söyler ve batch_scan prompt'u işe bununla başlar. Sandbox anahtarında bakiye null olur ve araç sıfırlar göstermek yerine bakiye olmadığını söyler.
  • Yalnızca salt okunur araçları otomatik onaylayın. Örneğin Kiro'nun yapılandırması "autoApprove": ["check_balance", "search_docs"] destekler. Harcama yapan araç o olduğu için scan_document aracını bir onay isteminin arkasında bırakın.
  • Ajanın bilgiye kendisi bakmasına izin verin. search_docs, birlikte gelen belgeler üzerinde çevrimdışı çalışır; bu yüzden "unsupported_document ne anlama gelir" sorusu hiçbir şeye mal olmaz ve modelin hafızasına dayanmaz.

Gizlilik: bunu yapmadan önce sorulacak sorular

Kimlik belgeleri, verinin olabileceği kadar hassas türüdür ve bir ajan, akışa yeni taraflar ekler. API tarafında neyin geçerli olduğu ve neyin sizin kurulumunuza bağlı olduğu aşağıda.

API tarafında (belgelendiği şekliyle):

  • Yüklenen görüntü istek süresince bellekte tutulur ve asla kalıcı depolamaya yazılmaz.
  • Tanıma sonucu, sonradan geri okunabilmesi için hesapta ayarlanan bir süre boyunca (24 saat, 7 gün, 30 gün ya da bir yıl) saklanır. Yeni bir hesabın varsayılanı bir yıldır. Çağrı başına retain_hours: 0 hiçbir satır yazmaz ve scan_document da retain_hours kabul eder. Ajanın yanıta yalnızca bir kez ihtiyacı varsa bunu ayarlayın.
  • İşleme Avrupa Birliği'nde gerçekleşir. Veriler model eğitmek için kullanılmaz.
  • return_portrait: false, belge sahibinin fotoğrafının kırpması olan images.main_photo alanını dışarıda bırakır. Sayfanın tamamının kırpması yine döner; bazı belgelerin sayfaya bastığı yüzün soluk ikinci kopyası da öyle.

Sizin tarafınızda:

  • Sonuç modelin bağlamına girer. scan_document ne döndürürse (adlar, numaralar, tarihler) artık sohbetin içindedir ve istemcinizi çalıştıran LLM sağlayıcısı hangisiyse onun tarafından, o sağlayıcının koşullarıyla işlenir. Bu, bu araca özgü değil, her MCP aracının doğasında vardır.
  • Görüntünün nasıl taşındığı önemlidir. Yerel sunucuda image_path ile sunucu dosyayı okur ve doğrudan API'ye gönderir. image_base64 ile görüntünün baytları modelin araç çağrısı argümanlarında yer alır. Piksellerin modelin bağlamı dışında kalmasını istiyorsanız, sınırlandırılmış bir yerel dizin kullanın.
  • Bu tanımadır, doğrulama değil. Sonucun authenticity grubu not_checked der. Tutan bir MRZ, bölgenin okunduğu ve kendi içinde tutarlı olduğu anlamına gelir, belgenin gerçek olduğu anlamına değil. Canlılık (liveness) ya da yüz eşleştirme adımı yoktur. Kullanım senaryonuz KYC ise bu, kararın kendisi değil, girdilerden biridir.
  • Geliştirirken sentetik belgeler kullanın. Örnek belgeler ve üretilmiş MRZ'ler her şeyi bağlamak için yeterlidir.

Kısa bir oturum

Sunucu kurulduktan sonra, ekine sentetik bir örnek belge koyduğunuz "Bu pasaport taramasını oku ve önümüzdeki altı ay içinde süresinin dolup dolmayacağını söyle" gibi bir prompt yeterlidir. İyi davranan bir ajan scan_document çağırır, sonuçtan document.expiry_date ve document.days_remaining değerlerini okur ve görüntüden edindiği izlenime göre değil, bu alanlara göre yanıt verir. Tarama unreadable dönerse, bunu söylemeli ve daha iyi bir fotoğraf istemelidir; bunun için de sizden ücret alınmamıştır.

Burada bir araç kullanmanın asıl nedeni bu son davranıştır: ajan, bir boşluğu doldurma cazibesi yerine açık bir "okunamadı" alır.

Bağlantılar

Bununla bir şey geliştirirseniz ya da yukarıdaki yapılandırmanın çalışmadığı bir istemci bulursanız, admin@doc.cheap adresine yazın.

doc.cheap ve MCP sunucusu hakkındaki her ifade, onların koduyla karşılaştırılarak kontrol edildi.