MCP tools reference

Emboss runs an MCP server at https://api.getemboss.ai/mcp. Connect by signing in, or by sending an Emboss API key as a bearer token. Any MCP client that supports OAuth can sign in with an Emboss account when the client prompts for it, and the twenty-seven tools below become available. See Use Emboss in Claude for the Claude-specific connect steps, or Use Emboss in ChatGPT for other assistants. Anyone can connect and see the tool list without signing in; using any tool needs you to sign in or send an API key.

Connect with an API key

A client that sends its own headers, such as your code or a model provider's API, can skip sign-in: send an Emboss API key (see Authentication) as a bearer token. A connection made with a key has both scopes, is billed to the key's account, and counts against that key's rate limit, the same as the key's own API calls. It is not listed under Connected apps: to end it, revoke or turn off the key on the API Keys page of the dashboard, which takes effect at its next call.

curl https://api.getemboss.ai/mcp \
  -H "Authorization: Bearer sk_yourkey" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Scopes

The connection is granted one or both of two scopes:

forms:read: list_forms, get_form, get_usage, find_form, get_job, get_batch, get_proposal, get_fax.
forms:write: everything else, including create_form, delete_form, fill_form, fill_form_from_context, prepare_form, commit_proposal, verify_form, read_form, add_attachment, suggest_mapping, fill_batch, send_fax, and the seven free PDF tools.

A tool call that needs a scope the connection doesn't have returns insufficient_scope; reconnect to grant it. A connection made with an API key always has both.

Tools

Tool	Needs write	Billed as
`list_forms`	No	Free
`get_form`	No	Free
`get_usage`	No	Free
`find_form`	No	Free
`create_form`	Yes	One form creation
`delete_form`	Yes	Free
`fill_form`	Yes	One fill
`fill_form_from_context`	Yes	One context fill (plus one form creation if a new PDF or a library form is given)
`prepare_form`	Yes	One context fill (plus one form creation if a new PDF or a library form is given)
`get_proposal`	No	Free
`commit_proposal`	Yes	Free within the proposal's already-billed prepare; one package if `package` is true
`verify_form`	Yes	One verify
`read_form`	Yes	One read
`send_fax`	Yes	Per transmitted page
`get_fax`	No	Free
`add_attachment`	Yes	Free
`get_job`	No	Free
`suggest_mapping`	Yes	One context fill
`fill_batch`	Yes	One fill per row, plus one context fill if `mapping` is omitted
`get_batch`	No	Free
`compose_pdf`	Yes	Free
`merge_pdf`	Yes	Free
`extract_pages`	Yes	Free
`delete_pages`	Yes	Free
`reorder_pages`	Yes	Free
`rotate_pages`	Yes	Free
`inspect_pdf`	Yes	Free

list_forms

Forms already in the user's Emboss library.

Arguments

state (optional): ready (default), processing, failed, or all.
limit (optional): up to 50.
cursor (optional): from a previous call's next_cursor, for pagination.

Returns

forms: each with id, title, state, pages, field_count, and created_at.
next_cursor: present if there are more forms to page through.

get_form

Status of one form.

Arguments

form_id (required).

Returns

id, status, title, error (when it failed), reused_layout (true when Emboss recognised the form's layout), and retention.
When the form is ready: pages, warnings and message for an XFA form, fields (each with id, label, kind, required, options for choice fields, group for fields that belong to the same exclusive group, and description when the form gives one), a download_url for the fillable PDF, its artifact_id, and, when the form was made from an upload, the upload's source_artifact_id. See Artifacts and lineage.

get_usage

No arguments. Returns this month's usage, how many free operations remain, and the billing page link.

Arguments

None.

Returns

period, used, free_remaining, billing_url.

find_form

Find a blank US federal form in the Emboss library by name, number or alias. The library is the same for everyone; only the lookups are counted against your account.

Arguments

query (required): a form name, number or alias, such as W-9, i9 or taxpayer identification.

Returns

results: each with slug, title, agency, revision and page_count. Pass a slug as library to create_form, fill_form_from_context or prepare_form to start from that form instead of uploading one. An empty list means no match.

create_form

Upload a PDF and detect its fields.

Arguments

pdf_url, pdf_base64 or library (exactly one required): a public https link, base64-encoded PDF bytes, or a slug from find_form to start from a form Emboss already keeps. A library form is billed as one form creation, like an upload.
title (optional).
retention (optional): ephemeral or account_default. See Retention below.

Returns

form_id, status. Returns when detection finishes, usually under two minutes. Billed as one form creation; the first 5 each month are free.

delete_form

Permanently removes a form and its PDFs from the user's library. Only call this when the user explicitly asks.

Arguments

form_id (required).

Returns

ok.

fill_form

Fill a ready form with values.

Arguments

form_id (required).
values (required): a dict keyed by field id or field label. Checkboxes take yes/no; choice fields take one of the field's option labels or values.
flatten (optional): reserved for a future release. Do not set it; passing true returns bad_request.

Returns

download_url, artifact_id (see Artifacts and lineage), applied values, any unmatched keys (labels that didn't match a field, or values that didn't match a checkbox word or option; ask the user about those), and warnings. Billed as one fill; the first 5 each month are free.

fill_form_from_context

Fill a form using answers pulled out of documents or notes.

Arguments

form_id, pdf_url/pdf_base64, or library (exactly one of the three): form_id for a form already in the library, a PDF to create and fill a new one, or a slug from find_form.
context_text (optional): pasted notes or text, up to 200,000 characters.
context_urls (optional): public https links to PDFs, Word docs, spreadsheets, images, or text files, each up to 10 MB.
policy (optional): safe (write high and medium confidence, the default) or strict (high only).
retention (optional): ephemeral or account_default; it applies only when this call creates the form.

At least one of context_text / context_urls is required, and the call takes at most 5 supporting documents in total, counting pasted text as one.

Returns

job_id. Poll get_job about every 20 seconds. Billed as one context fill; the first 5 each month are free. Passing pdf_url/pdf_base64 instead of form_id also creates the form, so that path is billed as one form creation plus one context fill.

prepare_form

Propose a fill without writing anything into the PDF. Same inputs as fill_form_from_context, but it stops at the proposal: read what Emboss decided, answer what is missing, then commit. See Prepare, commit and verify.

Arguments

form_id, pdf_url/pdf_base64, or library (exactly one of the three), as for fill_form_from_context.
context_text (optional): pasted notes or text, up to 200,000 characters.
context_urls (optional): public https links, each up to 10 MB. As for fill_form_from_context, at most 5 supporting documents in total, counting pasted text as one.
retention (optional): ephemeral or account_default; it applies only when this call creates the form.
policy (optional): safe (write high and medium confidence, the default) or strict (high only).

Returns

job_id and a proposal_id. Poll get_job about every 20 seconds. Billed as one context fill; the first 5 each month are free.

get_proposal

Read a proposal by its id: every field's state, its candidate values with evidence, and the questions still open.

Arguments

proposal_id (required).

Returns

fields, questions, confirmations, requirements and summary. No charge to read it.

commit_proposal

Write a proposal into the PDF, render it, check it, and return a receipt.

Arguments

proposal_id (required), from prepare_form.
confirm (optional): field ids from confirmations to accept as proposed, unchanged.
values (optional): the values the agent decided for fields still open, each with a field_id, a value, and an optional note.
policy (optional): safe or strict, overriding the proposal's own.
package (optional, default false): also build the submission package, the filled form with its attachments and the receipt embedded in one file. Billed as one package, and the first 5 each month are free. See The submission package.

Returns

job_id. Poll get_job about every 20 seconds for the download link, report, receipt and, when package was true, package_url. The commit itself is free within the proposal's already-billed prepare, up to 10 commits per proposal; a commit that builds a package is billed one package for that package.

verify_form

Check a filled PDF against a form's contract: required fields, allowed options, text that fits, empty signature boxes. No model call.

Arguments

form_id (required).
pdf_url or pdf_base64 (exactly one required): a public https link, or base64-encoded PDF bytes.

Returns

result (complete, review_required or incomplete), the issues found, and counts. Billed as one verify; the first 5 each month are free.

read_form

Read a filled PDF's values back out, labelled, without storing the file. See Read a filled form back.

Arguments

pdf_url or pdf_base64 (exactly one required): a public https link, or base64-encoded PDF bytes.
form_id (optional): the form to read the values against, if you already know it.

Returns

recognised (form_id, own_layout, shared_layout, or none), fields, unmatched, counts, and complete. Billed as one read; the first 5 each month are free.

send_fax

Send a PDF to a fax number and get a job id back at once.

Arguments

to (required): the destination fax number in E.164 form, for example +15025551212. United States, Canada, and Mexico are served.
Exactly one of:
- artifact_id: the id of a file Emboss already made or received, such as a job's filled PDF or a form's fillable PDF. See Artifacts and lineage.
- sources: a list of entries, each an artifact_id, an artifact_token for pay-per-call callers, and optional pages, sent as one packet. See Artifacts and lineage for the grammar.
- job_id: a fill_form_from_context or commit_proposal job once get_job reports ready; the filled PDF is faxed.
- form_id: a form from create_form; its fillable PDF is faxed.
- pdf_url or pdf_base64: any PDF.

Returns

job_id, status (working), pages, price_cents, destination_masked, the artifact_id of the transmitted copy, and source_artifact_ids. The fax is in flight when this returns; poll get_fax for delivery. Billed at 3¢ per page when the fax is delivered; a fax that fails is not charged. A job_id that is still processing returns not_ready; poll get_job and call again. A repeated fax of the same artifact to the same destination within ten minutes returns the same job with deduplicated: true.

get_fax

Delivery status and receipt of a send_fax job.

Arguments

job_id (required).

Returns

The receipt: status (queued, working, delivered, failed or expired; keep checking until it is delivered, failed or expired), to_masked, pages, the artifact_id of the transmitted copy and its source_artifact_ids, and on delivery the price and the artifact_sha256 of the transmitted file; on failure the failure_category, failure_reason, whether it is retryable, and refund (its mode and state), the same on an expired fax.

add_attachment

Attach a supporting document to a proposal before commit. See The submission package; commit_proposal above also takes package: true to hand back one merged submission package once attachments are in place.

Arguments

proposal_id (required), from prepare_form.
file_url or file_base64 (exactly one required): a public https link, or base64-encoded file bytes. PDF, PNG, or JPEG.
requirement (optional): the name of an entry in the form's required attachments this file satisfies.

Returns

The attachment's n, for (the requirement it satisfies), filename, bytes, sha256 and artifact_id. Free. At most 20 per proposal and 20 MB in all.

get_job

Status of a fill_form_from_context, prepare_form, or commit_proposal job.

Arguments

job_id (required).

Returns

status, the form_id the job fills (retry with it after a fill that found nothing), and retention; on failure, error. When ready: download_url, filled (field count), dropped, any warnings, and artifacts, a list of this job's files each with an artifact_id, role (filled, receipt, or package), and mime_type. See Artifacts and lineage. A prepare_form job also carries a proposal_id; a commit_proposal job carries the verification result plus links to the receipt and the PDF.

suggest_mapping

Propose which spreadsheet column fills which form field.

Arguments

form_id (required).
csv_text (up to 2 MB) or csv_url (up to 10 MB), exactly one required. Only the header row matters.

Returns

mapping of {column: field_id} and unmapped_columns. suggest_mapping is billed as one context fill (5 free each month). fill_batch runs this automatically when called without a mapping, and bills the same.

fill_batch

Fill the form once per spreadsheet row.

Arguments

form_id (required).
csv_text (up to 2 MB) or csv_url (up to 10 MB), exactly one required, up to 1,000 rows.
mapping (optional): {column: field_id}. Omit it to use the suggested mapping (this runs suggest_mapping first, billed as one context fill).

Returns

batch_id, total (row count), mapping_used (the {column: field_id} mapping actually applied, whether you passed one or it ran suggest_mapping for you). Batches up to 50 rows finish before this call returns; larger ones keep running, poll get_batch. Each row is billed as one fill.

get_batch

Progress of a fill_batch run.

Arguments

batch_id (required).

Returns

status, total, filled, failed, a download_url and artifact_id per finished row (first 100), and a zip_url once the batch is done.

Free PDF utilities

Merge, compose, extract, delete, reorder, rotate and inspect PDF artifacts. Every result carries a new artifact_id; see Artifacts and lineage for the id, the pages grammar, and how a pay-per-call caller passes an artifact_token in place of an account. Each also returns an operation_id and an artifacts list; inspect_pdf returns its facts under report, with artifact_id null.

compose_pdf

Free. Build one PDF from several artifacts.

Arguments

sources (required): a list of {artifact_id, pages, rotate}. pages is a selection like 1-3,7 (omit for every page); rotate is 90, 180 or 270.

Returns

The new artifact_id.

merge_pdf

Free. Join whole PDFs in order; no page selection.

Arguments

sources (required): a list of {artifact_id}, joined in order. For page selections use compose_pdf.

Returns

The new artifact_id.

extract_pages

Free. Keep only the named pages of one artifact.

Arguments

artifact_id (required).
pages (required): a page selection like 1-3,7 (1-based, repeats and any order allowed).

Returns

The new artifact_id.

delete_pages

Free. Remove the named pages of one artifact; every other page stays in order.

Arguments

artifact_id (required).
pages (required): a page selection like 1-3,7.

Returns

The new artifact_id.

reorder_pages

Free. Put one artifact's pages in a new order; every page is named exactly once.

Arguments

artifact_id (required).
order (required): every page number, 1-based, named exactly once, in the new order.

Returns

The new artifact_id.

rotate_pages

Free. Rotate named pages of one artifact by 90, 180 or 270 degrees, added clockwise to each page's current rotation.

Arguments

artifact_id (required).
rotations (required): a non-empty list of {pages, degrees}.

Returns

The new artifact_id.

inspect_pdf

Free. Structural facts about one artifact: no new file is produced.

Arguments

artifact_id (required).

Returns

Page count, each page's size and rotation, whether the PDF is encrypted, has form fields, annotations, outlines, embedded files or JavaScript. No text, no field values.

Polling

Long operations return an id instead of finishing inline:

fill_form_from_context, prepare_form and commit_proposal each return a job_id. Poll get_job about every 20 seconds until its status is ready or failed.
fill_batch returns a batch_id. For batches over 50 rows, poll get_batch about every 20 seconds until its status is complete or failed.
send_fax returns a fax job_id. Poll get_fax about every 20 seconds until its status is delivered, failed or expired.

Errors

Every error carries a machine-readable code and a human message.

insufficient_scope: the connection doesn't have the needed permission; reconnect Emboss to grant it.
not_found: the id doesn't exist, or isn't in this account.
not_ready: the form, job, or batch is still processing; try again shortly.
over_free_tier: this month's free operations are used up, or (fill_batch) the batch has more rows than the free fills left; relay the message and the billing_url.
over_page_cap: the form is over the free-tier 5-page limit; relay the message and the billing_url.
card_required (send_fax): the account has no payment method on file, and faxes have no free allowance; relay the message and the billing_url.
unsupported_file: not a PDF; tell the user to export to PDF first.
bad_request: malformed or conflicting arguments; check the message for which argument and fix the call.
fetch_failed: a given URL couldn't be downloaded; ask the user for a working public link, or a pasted/base64 alternative.
nothing_to_fill (fill_form): none of the given values matched a field; show get_form's fields and ask the user which ones to fill.
no_mapping (fill_batch): no spreadsheet column matched a form field; pass an explicit mapping (see suggest_mapping).
document_same_as_form (fill_form_from_context, prepare_form): a supporting document is the blank form itself, with nothing filled in; ask the user for the document that holds the answers.
too_large: the upload is over its size limit (PDF, context text, or CSV); ask the user for a smaller file or a link instead of inline content.
rate_limited: too many requests; wait a minute and retry.
server_error: Emboss had a problem processing the request; retry once, and tell the user if it persists.
unauthenticated: no valid session; reconnect Emboss.
conflicting_values (fill_form): two boxes in one Yes/No question were set to yes; ask which one the user meant.
documents_deleted: the form's files were deleted under ephemeral processing; ask the user to upload the form again.
refused (send_fax): the number is malformed, outside the United States, Canada and Mexico, or blocked; do not retry the same number.
provider_unavailable (send_fax): the fax provider did not accept the job and nothing was charged; retry once after a minute.
gone (send_fax, the free PDF tools): the file behind that artifact_id was deleted under ephemeral processing; recreate it and send again.
The free PDF tools' own codes: invalid_page_spec (a pages or order value is not a valid page selection), page_out_of_range, duplicate_page and missing_page (order must name every page exactly once), empty_output (the result would have no pages), pdf_required, too_many_pages, too_many_inputs, file_too_large, pdf_encrypted and pdf_corrupt.

A fill from documents that found nothing still finishes ready: get_job shows no_values_found in its warnings and a message to relay to the user.

402 responses (over_free_tier, over_page_cap and card_required) include a billing_url.

Billing

Free tier: The first 5 form creations, 5 context fills, 5 standard fills, 5 verifications, 5 reads, and 5 packages each month are free when the job is 5 pages or fewer (a context fill counts the form and its documents together); a longer job is charged and does not use a free one. suggest_mapping is billed as one context fill, and so is prepare_form. Committing a proposal is free within the prepare that was already billed. See Pricing for current rates.

Retention

create_form, fill_form_from_context and prepare_form take an optional retention argument: ephemeral or account_default. Leave it out and the account's own default applies. It applies only when the call creates a new form; an existing form keeps the setting it was created with. fill_form and fill_batch always fill an existing form, so on them the argument changes nothing. See Ephemeral processing for the window and what a 410 means once a form is swept.

Using it from code

Add Emboss as an MCP server on a Messages API call:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://api.getemboss.ai/mcp",
      "name": "emboss",
      "authorization_token": "your-oauth-token"
    }
  ]
}

Or from Claude Code:

claude mcp add --transport http emboss https://api.getemboss.ai/mcp

See Use Emboss in Claude for the full connect flow, including the plugin and skill.