MCP tools reference

The Transactional MCP server exposes seven tools. All calls are scoped to the API token used at connection time — the assistant only ever sees that account's documents.

`list_documents`

List the templates owned by the connected account. Use this first when the assistant doesn't yet know what's available.

Arguments — none.

Returns — an array of { id, uuid, name, framework, format, updatedAt }.

Trigger prompts

"What templates do I have on Transactional?" "List my Transactional documents."

`get_document`

Fetch the full state of one document. Use this before generate_pdf so the assistant knows the exact shape of variables to send.

Arguments

Name	Type	Notes
`documentId`	`string (uuid)`	The public `uuid` from `list_documents`. The internal numeric id is not accepted here.

Returns — { uuid, name, body, framework, format, landscape, fonts, variables, updatedAt }. The variables field holds the sample shape — use it as a template when calling generate_pdf.

Trigger prompts

"Show me the variables the invoice template expects." "Get template 12."

`update_document_html`

Edit a template's Handlebars/HTML body. Two mutually exclusive modes — supply either body, or oldStr + newStr.

Arguments

Name	Type	Required	Notes
`documentId`	`string (uuid)`	yes	The `uuid` from `list_documents`.
`body`	`string`	mode A	Full replacement HTML. Mutually exclusive with `oldStr`/`newStr`.
`oldStr`	`string`	mode B	Exact substring to locate in the current body. Must match exactly once — include enough surrounding context to make it unambiguous.
`newStr`	`string`	mode B	Replacement for `oldStr`. Pass an empty string to delete the matched fragment. Required whenever `oldStr` is supplied.

Returns — { documentId, updated: true, mode }, where mode is full_replace or surgical_replace.

Errors the assistant may surface

`error`	Meaning
`invalid_document_id`	UUID is malformed.
`document_not_found`	Template doesn't exist or isn't owned by this token.
`invalid_input`	Both modes supplied at once, neither supplied, or `oldStr` given without `newStr`.
`old_str_not_found`	`oldStr` doesn't appear in the current body.
`old_str_not_unique`	`oldStr` matches more than once. Add context and retry.

Trigger prompts

"Change the footer of my invoice template to say 2026." "Rewrite the header section of template ."

`generate_pdf`

Render a document with the supplied variables. Debits one generation credit per successful call.

Arguments

Name	Type	Required	Notes
`documentId`	`string (uuid)`	yes	The `uuid` from `list_documents` / `get_document`.
`variables`	`object`	no	Handlebars context. Must match the shape from `get_document`.

Returns — { url, documentId }. url is public and permanent — it isn't signed and never expires. The file stays online until it's deleted with delete_generated_file.

Errors the assistant may surface

`error`	Meaning
`invalid_document_id`	UUID is malformed.
`NOT_FOUND`	Document doesn't exist or isn't owned by this token.
`quota_exceeded`	Out of generation credits — top up.
`storage_unavailable`	S3 hiccup. Retry once.

Trigger prompts

"Generate the invoice PDF for Acme Corp." "Render template with customer = { name: 'X' }."

`delete_generated_file`

Permanently remove a PDF that generate_pdf produced earlier. This cannot be undone — the assistant should confirm with the user before calling it.

Costs no credit. The source template is untouched, so the same PDF can be produced again with generate_pdf (which does cost a credit).

Arguments

Name	Type	Required	Notes
`url`	`string`	yes	The `url` returned by `generate_pdf`, or its absolute storage path.

Returns — { deleted: true, url }.

Errors the assistant may surface

`error`	Meaning
`file_not_found`	Not a PDF generated by this account, or already deleted. Also what you get for someone else's file — the tool never confirms that a file it can't touch exists.
`storage_unavailable`	Storage hiccup. Retry once.

Trigger prompts

"Delete the invoice PDF you just generated." "Clean up that last PDF, I've saved it."

`list_folders`

List the folders organizing the account's documents. Optional context for the assistant; not required for generation.

Arguments — none.

Returns — { id, name, createdAt, updatedAt }[], sorted alphabetically.

Trigger prompts

"What folders do I have in Transactional?" "Group my templates by folder."

`get_usage`

Read the current credit snapshot — generation and AI counters with used / included / topUp / remaining plus the period end.

Arguments — none.

Returns

{
  "generation": { "used": 482, "included": 1000, "topUp": 0, "remaining": 518 },
  "ai":         { "used":  31, "included":  100, "topUp": 0, "remaining":  69 },
  "periodEnd":  "2026-06-01T00:00:00.000Z"
}

Trigger prompts

"How many PDFs can I still generate this month?" "Show me my Transactional credits."

Patterns the assistant should follow

A few habits worth nudging into the system prompt if you're building your own assistant on top of these tools:

list_documents before get_document before generate_pdf. Don't guess UUIDs.
Read variables from get_document and reuse its shape. Inventing variable names is the #1 source of broken PDFs.
Prefer surgical update_document_html over full replacement. Sending the whole body back risks silently dropping parts of the template the assistant didn't think to reproduce.
Confirm before delete_generated_file. It's the one destructive tool here, and there's no undo. Echo back which file is about to go.
Surface error codes verbatim. They're stable and let users branch programmatically — don't paraphrase.
Don't loop on quota_exceeded. It won't fix itself within a turn; tell the user to top up.