Server MCP di OCR per passaporti, per agenti di IA

Cosa riceve il tuo agente

Questa è la differenza che conta. Uno strumento OCR che restituisce una pagina di testo dà al modello qualcosa da analizzare di nuovo, e un modello a cui si chiede di rianalizzare una data prima o poi ne inventerà una. Questo strumento restituisce i campi già separati:

• Il titolare: nomi, cognome, data di nascita, sesso, cittadinanza.
• Il documento: tipo, paese, Stato di emissione, numero, serie, data di rilascio, data di scadenza, se è scaduto e quanti giorni restano.
• Ogni campo trovato, ciascuno con il proprio livello di confidenza, letto separatamente dalla zona a lettura ottica (MRZ) e dalla zona visiva stampata, così il modello può vedere che le due letture coincidono invece di darlo per scontato.
• La zona a lettura ottica con un verdetto (superata, non superata o assente), con il motivo e le righe stesse.
• Un riepilogo di una riga che l'assistente può mostrarti mentre lavora.

Gli errori tornano come una riga leggibile in un blocco di errore, mai come un risultato vuoto e silenzioso: l'assistente può agire di conseguenza e mostrartelo. Un rifiuto dell'API mantiene la formulazione dell'API stessa, il suo codice di errore e il link alla pagina che lo spiega.

Installalo nel tuo client

Aggiungi il blocco alla configurazione MCP del tuo client e riavvialo. Imposta DOC_CHEAP_API_KEY sulla tua chiave, oppure omettilo e verrà usata la chiave pubblica della sandbox.

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

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

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

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

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

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

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

• Riavvia il client dopo aver aggiunto il blocco. È il client ad avviare il server, quindi una configurazione o un ambiente modificati vengono recepiti solo a un nuovo avvio.
• Senza DOC_CHEAP_API_KEY il server ripiega sulla chiave pubblica della sandbox: le scansioni rientrano allora nella sua quota gratuita e non c'è alcun saldo da riportare. È il modo più rapido per vederlo funzionare.
• Impostazioni facoltative: DOC_CHEAP_DOCS_BASE (a cosa rimandano i risultati di ricerca), DOC_CHEAP_DOCS_DIR (quale copia della documentazione consultare) e DOC_CHEAP_IMAGE_ROOT (vedi le protezioni più sotto).

Oppure collegati al server ospitato

Gli stessi tre strumenti sono ospitati su https://mcp.doc.cheap/mcp tramite Streamable HTTP, così un client che si collega a un URL non deve installare nulla. Nessun login: invia la tua chiave come X-Doc-Cheap-Api-Key o come Authorization: Bearer (se invii entrambe, prevale l'header con il nome dedicato), oppure non inviarne nessuna e verrà usata la chiave pubblica della sandbox. Il server ospitato non può leggere file sulla tua macchina, quindi riceve l'immagine in base64 o come URL https.

https://mcp.doc.cheap/mcp

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

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

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

In Claude Desktop e su claude.ai, aggiungilo in Settings, Connectors, come connettore personalizzato con l'URL https://mcp.doc.cheap/mcp; senza chiave funziona con la chiave della sandbox.

I tre strumenti

• scan_document riceve l'immagine come image_base64, image_path o image_url, e le stesse opzioni di una chiamata diretta, tra cui expect_country, return_portrait, reference e idempotency_key.
• search_docs legge una copia della documentazione distribuita insieme al server, quindi risponde senza alcuna rete: l'agente può consultare il vocabolario dei campi o un codice di errore senza spendere una chiamata.
• check_balance richiede una chiave con un account alle spalle. Con la chiave pubblica della sandbox dice chiaramente che non c'è alcun saldo, invece di rispondere con degli zeri che sembrano una lettura.
• Ogni strumento dichiara uno schema di output e restituisce contenuto strutturato conforme, così un agente può usare i campi senza analizzare testo.
• Ogni pagina della documentazione è anche una risorsa che l'agente può leggere, e quattro prompt (leggere un documento in JSON, verificare una data di scadenza, scansionare un lotto, spiegare un codice di errore) avviano le attività più comuni in un solo passo.

Quanto costa

$0.01 per documento riconosciuto. Tariffa fissa, per ogni account, a qualsiasi volume: un solo numero e nulla da negoziare. Un documento viene addebitato solo quando è stato riconosciuto: una scansione che non trova nulla, non riesce a leggere l'immagine o non riesce a identificarne il tipo risponde con il suo verdetto e non costa nulla. Ogni risultato dice di quale caso si tratta, così l'agente, e tu, sapete sempre se quella chiamata ha speso qualcosa.

Prima di avere un account: la chiave pubblica della sandbox esegue 10 documenti riconosciuti gratuiti per indirizzo IP in totale, al massimo 10 richieste all'ora qualunque sia la risposta, e la registrazione aggiunge 20 crediti. Un credito è un centesimo, e un centesimo è un documento.

Il riconoscimento richiede circa 275 ms di mediana in produzione, e ogni risultato riporta i propri tempi, così un ciclo di un agente può pianificare su un numero reale.

Lo stesso prezzo, la stessa chiave e la stessa struttura di risposta di una chiamata diretta: come funziona l'addebito e il confronto con le alternative.

Cosa segnala il server

Per impostazione predefinita il server non invia segnalazioni da nessuna parte: la segnalazione degli errori è disattivata finché non imposti tu stesso un endpoint, e senza di esso la libreria di tracciamento non viene nemmeno caricata.

Due protezioni da conoscere

Il server gira sulla tua macchina con i tuoi privilegi, e i suoi argomenti li sceglie un modello. Per questo due di essi sono recintati:

image_base64 non ha nessuno di questi vincoli, perché chi chiama possiede già i byte: ecco perché ogni rifiuto descritto sopra rimanda a questa opzione.