io.github.lesofi/handinloop-mcp-server

Price a batch of documents BEFORE submitting it (#788). No side effect: nothing is stored, charged, or counted against the free tier. A document costs ceil(pages x the task type's credits_per_page x its line-item multiplier), at least one credit; the multiplier applies when the task type declares a line-item table. The submit charges with the same function, so charged_credits is what the batch costs when every document succeeds and it is submitted in this order this month. A document HandInLoop fails to process (system_error, including after its retries) costs nothing. Args: - task_type: a task type id from handinloop_list_task_types, OR - fields: custom inline fields (priced as a custom extraction). Provide task_type OR fields. - documents: 1..500, each exactly one of: pages (your own page count — cheapest, sends no file), document_base64 (the API counts the pages), or document_url (fetched here, then counted by the API). At most 25 documents may be files (base64 or URL); give pages for the rest. file_name is optional on each. Returns: { task_type, line_items, rate: { credits_per_page, line_item_multiplier }, documents: [{ index, file_name?, pages, credits, free, error? }], pages, credits, free_documents, charged_credits, available_credits, covered, spend: { spent_this_month, cap, overage, overage_credits, blocked }, refused? }. covered false or spend.blocked true means the submit would be refused (402). A file the API could not read is listed under refused, with why, and left out of the totals.

Fetch the validated extraction result for a completed job. Only call once handinloop_get_job_status reports status 'completed' (calling earlier returns an error with the remaining time). Returns: { job_id, task_type, status, fields: [{ name, value, confidence (0..1), human_verified }], line_items?: [...], // for invoice-like documents audit_trail: [{ at, actor: system|ai|human, action }], discrepancies?: [{ field, expected, actual, delta, kind }], // freight audit (#157) proof?: { // the signed Proof Object (#147) job_id, task_type, status, issued_at, fields: [{ name, value, confidence, verified_by: human|ai, verified_at? }], audit_trail: [...], signature?: { algorithm, key_id, value } // absent if signing not configured } } Fields with human_verified=true were confirmed or corrected by a person on your own team, not the AI — treat confidence 1.0 as authoritative. The audit_trail documents every step for compliance purposes; preserve it when storing results. The 'proof' is a portable, verifiable record: pass it downstream so another party can confirm this data's provenance by verifying the Ed25519 signature against HandInLoop's published public key (GET /v1/proof/public-key) — no callback needed. Preserve it intact; verified_by distinguishes human-signed fields from AI-verified ones. It's omitted only if the proof could not be retrieved.

Check the status of a previously submitted extraction job. Statuses: 'queued' (waiting for a worker) -> 'in_review' (being processed: the worker extracting and checking it, then a person if it needs one) -> 'completed' (result ready) | 'rejected' (invalid document). Use estimated_seconds_remaining to pick a sensible polling interval; for scheduled routines, checking on the next run is usually enough. Args: - job_id: id returned by handinloop_submit_extraction_job Returns: { job_id, task_type, status, submitted_at, finished_at?, estimated_seconds_remaining? }

Get a pilot run's live status board — its per-document status and run-level counts (#252). Use after handinloop_submit_pilot_batch to watch the batch clear: documents move queued -> in_review -> completed | rejected. The run is done when counts.completed + counts.rejected == counts.total. in_review covers two stages: the worker still extracting and checking a document, then a person reviewing it. counts.awaiting_human is how many of the in_review documents a person has; the rest (in_review - awaiting_human) are still with the worker. Args: - pilot_run_id: the run to check (must belong to your account). Returns: { pilot_run: { id, name, task_type, status }, items: [{ job_id, file_name?, status, submitted_at, finished_at? }], counts: { total, queued, in_review, awaiting_human, completed, rejected } }

Read one of your saved task types (#583), including its prompt_template, gate and review_policy, which handinloop_list_task_types does not show. Args: - id: the saved task type's id. Returns { id, name, description, output_fields, prompt_template?, gate?, review_policy? }. A built-in type, or an id you have not saved, is not found.

List the document extraction task types the HandInLoop human-in-the-loop platform supports. Call this first to discover valid 'task_type' values for handinloop_submit_extraction_job, and to see which fields each task type returns. Returns: { task_types: [{ id, name, description, output_fields[], hidden? }] }. A type marked hidden: true is retired: do not choose it for new work.

Ask HandInLoop to propose the fields worth extracting from a document — the "what should I extract?" assist. Given a document (and an optional goal), the model suggests a field set you can then pass as 'fields' to handinloop_submit_extraction_job for a custom, human-verified extraction. Synchronous: returns immediately, no job, no human review. Args: - document_url OR document_base64: the document (PDF/image). Exactly one required. - file_name (optional) - goal (optional): focus, e.g. "accounts payable" Returns: { fields: [{ name, description }] }

Save a named custom field set as a reusable task type (#103 Phase B). Once saved, submit against it by passing its returned id as 'task_type' to handinloop_submit_extraction_job — no need to re-send the fields each time. Saved types also appear in handinloop_list_task_types. Saving an existing id updates it. Needs an API key with the 'workflows' scope (#951), which no key has unless an organisation admin or engineer ticked it when making the key: a saved type changes what every later job of the account extracts. Without it the call fails with the missing scope named; ask a person to issue a key with 'workflows' rather than retrying. Args: - fields: [{ name, description? }] — the field set (required, at least one). - name (optional): human name; the id is derived from it if 'id' is omitted. - id (optional): stable handle (lowercase letter then letters/digits/underscores). Must not collide with a built-in. - description (optional). - prompt_template (optional): instructions sent to the extraction model with every document of this type, e.g. "Dates are day-first; ignore the remittance slip." Up to 4000 characters. Omit to keep the saved one; "" clears it. - gate (optional): { critical_fields?: string[], min_confidence?: number } — fields a person must sign off on every document of this type (each must be one of 'fields'), and a confidence floor. A submit's own 'verify' is merged with it, stricter wins. Omit to keep the saved one; {} clears it. Returns the saved TaskType { id, name, description, output_fields, prompt_template?, gate?, review_policy? }. review_policy (#585: the type's confidence threshold and QA sample rate) is read-only here: an organisation admin or engineer sets it in the portal, and a save keeps it.

Submit a document to HandInLoop for extraction with human-in-the-loop validation. AI reads the document and scores every field for confidence first; low-confidence fields are reviewed and corrected by your own team, in a review screen built for it, before delivery. Every decision is signed and recorded. The result is validated data with per-field confidence and a complete audit trail. ASYNC: returns immediately with a job_id and status 'queued'. Human turnaround is minutes to hours in production — poll handinloop_get_job_status (respect estimated_seconds_remaining), then call handinloop_get_job_result once status is 'completed'. Ideal for scheduled/recurring workflows. VERIFIED-ANSWER LOOP (trust contract): declare your bar with 'verify' and hand off with 'callback_url'. - verify.critical_fields: names that MUST be human-verified before you get them back — a critical field the AI returns unverified (or omits) always goes to a human, even at confidence 1.0. Use this for anything you must not act on unchecked (e.g. "total", "bank_account"). - verify.min_confidence (0..1): a stricter per-job bar; any field below it is routed to a human. - callback_url: an https endpoint HandInLoop POSTs the finished result to (with the signed proof embedded), so you can submit and walk away instead of polling. Verify the POST offline via the proof's signature against GET /v1/proof/public-key. Delivery status shows on handinloop_get_job_status under 'callback'. Args: - task_type: one of the ids from handinloop_list_task_types (e.g. "invoice"), OR - fields: for CUSTOM extraction, describe the fields to extract yourself — [{ name, description? }]. Works on ANY document, not just the built-in task types. Provide task_type OR fields. - document_url OR document_base64: the document (PDF/image). Exactly one required. - file_name (optional): original filename for routing and audit - instructions (optional): note for the human reviewer - verify (optional): { critical_fiel…

Submit a batch of documents to an existing HandInLoop pilot run — the agent/API intake for a Shadow-Pilot (#257). A pilot run groups a client's documents for a side-by-side accuracy/turnaround/savings report. Create the run in the portal (app.handinloop.com/pilots) or have a human create it, then pass its 'pilot_run_id' here; every document is stamped with it and joins the run's status board and report. All documents use the run's task type — you don't repeat it. ASYNC and per-document: each document becomes its own extraction job (returns a job_id). One bad document (unfetchable URL, etc.) is reported as a per-item error and never fails the rest of the batch. Poll progress with handinloop_get_pilot_run. Args: - pilot_run_id: the run to submit into (from the portal; must belong to your account). - documents: [{ document_url OR document_base64, source_ref?, file_name? }] (1..200). - document_url is fetched here and sent as content; source_ref is your own id/filename for the doc, used to match it to a ground-truth row for accuracy scoring — set it to the filename you used in your ground-truth CSV. - verification_gate (optional): { critical_fields: string[], min_confidence?: number }. Applied to the run before submitting, so every document in the batch inherits it — critical fields must be human-verified before any result comes back. Only ever makes review stricter. Returns: { pilot_run_id, task_type, accepted, rejected, submitted: [{ source_ref?, file_name?, job_id? , status?, error? }] }