MCP tools reference

The Transactional MCP server exposes five 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
`id`	`integer`	Internal id from `list_documents`. UUIDs are 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."

`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 signed and short-lived (download it fast).

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' }."

`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.
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.