Tools and workflow

The server exposes a small, standard MCP tool set. Read tools never spend credits; the only paid action is skavio_submit_job.

Discovery and accounting (free)

Tool	Purpose
`skavio_capabilities`	Live operations and pricing metadata.
`skavio_pricing`	Currency, credit prices and credit packs.
`skavio_paid_catalog`	Paid operations with per-unit USD price, credit price and the enforced margin band.
`skavio_billing_plans`	Subscription plans (no payment is started).
`skavio_payment_history`	Company payment history.
`skavio_wallet`	Authoritative company credit balance.
`skavio_usage`	Authoritative monthly usage.
`skavio_budgets`	Company and key budget ceilings.
`skavio_adapter_usage`	This adapter's reserved and charged credits.
`skavio_billing_portal`	Authenticated dashboard handoff; no checkout or purchase.

Files (free, but they reserve an upload intent)

Tool	Purpose
`skavio_upload`	Measured multipart upload of a file that an operator has placed in the configured input directory (arguments: `filename`, `idempotency_key`).
`skavio_upload_bytes`	Upload small inline content as base64 (≤ 48 KiB; arguments: `filename`, `data_base64`, `idempotency_key`).
`skavio_download_result`	Download a completed result for the authenticated company (`job_id`, `result_id`).

Uploads have no upstream idempotency guarantee. An upload intent is persisted before dispatch; an uncertain upload is never repeated automatically.

Paid work

Tool	Purpose
`skavio_estimate`	Authoritative, nonbillable quote for a spec.
`skavio_submit_job`	Paid. Reserve a credit cap and dispatch the job.
`skavio_get_job`	Read job state and reconcile credits.
`skavio_list_jobs`	List jobs for the company.
`skavio_cancel_job`	Cancel an unstarted job; running work may still charge.
`skavio_reconcile`	Operator/agent view of ambiguous admissions.
`skavio_cleanup`	Local result retention cleanup.

The paid sequence

Upload — skavio_upload/skavio_upload_bytes returns uploads[0].id.
Estimate — skavio_estimate with the spec and upload_ids.
Submit — skavio_submit_job with the spec, your idempotency_key and

max_credits set to the quote. The reservation is the immutable hard cap and is persisted *before* dispatch, so a crash or restart cannot double-charge.

Poll — skavio_get_job until completed or failed.
Download — skavio_download_result for the signed result.
Reconcile — skavio_adapter_usage and skavio_wallet show the settled

charge.

Submit example

{"spec":{"operation":"document_ocr","upload_ids":["UPLOAD_ID"],"max_credits":8},"idempotency_key":"invoice-batch-2026-10-13-0007"}

Idempotency and recovery

Always pass your own idempotency_key, stable across retries, and reuse the

exact same arguments on retry.

A retry with the same key and identical spec returns the original job; it does

not create or charge a second job.

A retry with the same key and a different spec fails with

idempotency_conflict; it never overwrites the original intent.

If a submit is interrupted, retry the same key. If the outcome is genuinely

unknown, the server keeps a conservative reservation and marks the admission for reconciliation; it never resubmits an ambiguous job.

State, keys, quotes and reservations survive process restart.

What a tool call can never do

Choose a company, role, credential, API base URL or upstream endpoint.
Move funds, top up a wallet, charge a card or start a checkout.
Escape the operator-granted permissions, credit ceilings or rate limits.
Return the upstream Processing API key or your MCP credential.