# 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](/docs/claude) for the Claude-specific connect steps, or [Use Emboss in
ChatGPT](/docs/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](/docs/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.

```bash
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](/docs/artifacts).

### 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](/docs/artifacts)), `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](/docs/prepare-commit-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](/docs/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](/docs/read-filled-form).

**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](/docs/artifacts).
  - `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](/docs/artifacts) 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](/docs/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](/docs/artifacts). 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](/docs/artifacts) 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](/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](/docs/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:

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

Or from Claude Code:

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

See [Use Emboss in Claude](/docs/claude) for the full connect flow, including
the plugin and skill.

## See also

- [Fill PDF forms in Claude](https://getemboss.ai/use-cases/fill-pdf-forms-in-claude)
- [MCP server](https://getemboss.ai/glossary/mcp-server)
- [Use Emboss in ChatGPT](https://getemboss.ai/docs/chatgpt)
- [Use Emboss in Claude](https://getemboss.ai/docs/claude)
- [Use Emboss in ChatGPT](https://getemboss.ai/docs/chatgpt)
- [Use Emboss in Antigravity](https://getemboss.ai/docs/antigravity)
- [Use Emboss from agent frameworks (A2A)](https://getemboss.ai/docs/a2a)
- [Pay per call with MPP](https://getemboss.ai/docs/pay-per-call/mpp)
- [Prepare, commit and verify](https://getemboss.ai/docs/prepare-commit-verify)
- [What agents may do, and when to ask](https://getemboss.ai/docs/agentic-access)
- [Fill with context](https://getemboss.ai/docs/reference/fill-with-context)