Summary
Anvil’s PDF generation API lets a server integration fill a template or generate a PDF from content and receive PDF bytes. For an interactive agent, Anvil’s remote MCP server instead returns a short-lived download link. This guide follows an approved order through invoice creation and delivery. Your application must validate the order data, verify the finished PDF, and control its delivery.
MCP server or API key integration
Choose Anvil’s remote MCP server when a person directs an interactive agent through a compatible MCP client. Choose the API-key-authenticated PDF filling or generation API when your backend needs to produce invoices from approved orders without an interactive agent. The APIs return PDF bytes, which your application can store and verify. MCP’s PDF tools return short-lived signed download links that the client must fetch.
MCP uses OAuth, so you do not put an API key in the agent client’s configuration. The authorized client can use the Anvil permissions granted to the signed-in user; MCP does not make the connection a PDF-only credential. Before an agent fills an invoice, confirm the active organization and use tool-call approval if the client supports it.
An MCP download link lasts about five minutes, and the tool result gives its exact expiry in expiresAt. Download the PDF before that time or rerun the tool after the link expires. For an unattended invoice queue, keep the API key on your server and let your backend decide which orders trigger a request.
The order-to-invoice example
The running example uses an approved order and a pre-approved invoice template. The agent selects the template and maps the order’s customer details, line items, and amounts to its fields. Your application checks the mapped data before Anvil generates the PDF. Your application then verifies the finished invoice against the order, obtains any required human approval, and delivers it to the intended recipient.
Selecting a template
Use a pre-approved standardized PDF Cast when every invoice uses the same layout. Upload the PDF, configure its fields, and assign aliases for values such as the customer name and invoice total. The agent selects that Cast, while your application supplies the order data.
Choose a dynamic template if the invoice needs conditional sections or editable document content. You build dynamic templates in Anvil’s dashboard Document Editor, not through the API. Your application then supplies values through the PDF fill endpoint; the template configuration determines which conditional content appears.
Use HTML/CSS or structured Markdown generation when your application needs to build the invoice content instead of filling a prebuilt template. Your application must construct the content from validated order data. For the structured Markdown option, follow Anvil’s documented block format rather than sending a raw Markdown string. If you have not chosen a method yet, read the published companion guide to fixed PDF filling, dynamic templates, HTML/CSS, and structured Markdown before implementing one.
Mapping and validating fields
Map the approved order to the field aliases on your invoice template before calling Anvil. For a standardized invoice PDF, your application might send invoiceNumber, customerName, and totalDue as JSON keys, but those names work only if they match the approved template’s aliases. Build the payload from the order record rather than asking the agent to invent invoice values.
When you first create a standardized template, Anvil’s createCast schema mapping can help match PDF fields to your aliasIds. Follow the template documentation for the applicable alias descriptions and field-detection options. Review the proposed matches against the PDF before approving the template. Mapping can miss a field or leave an alias unmatched, and the feature requires AI Pack or higher. It does not remap fields each time you fill an invoice.
Reject missing or null required values and keys outside the approved alias list before calling Anvil. The fill endpoint ignores unmatched keys and leaves fields with absent or null values unpopulated. Omit optional values only when the approved template permits it. Check the recipient and invoice number against the order. Recalculate line totals, tax, and the amount due from the approved order data before sending the request.
If you chose structured Markdown instead of a template, map the same validated order into the generation endpoint’s array of document blocks, such as headings, content, and tables. Do not send a raw Markdown string as the request’s root data.
Generating the PDF
For the approved invoice Cast, send the validated order fields to Anvil’s fill endpoint. The request below is pseudocode. Substitute your template ID and approved aliases, and authenticate with your server-side API key.
POST https://app.useanvil.com/api/v1/fill/{pdfTemplateID}.pdf
{"data":{"invoiceNumber":"INV-1042","customerName":"Example Customer","totalDue":"120.00"}}If the invoice needs a layout built from content rather than a Cast, Anvil’s generation endpoint accepts HTML and CSS or an array of structured Markdown blocks. The HTML request below is illustrative pseudocode, not a verified request body. Check the generation API documentation for the current endpoint, authentication, and HTML payload format before implementing it.
invoiceHtml = renderApprovedInvoice(validatedOrder)
pdfBytes = anvilGeneratePdfUsingDocumentedHtmlRequest(invoiceHtml)Both API calls return binary PDF bytes. Preserve those bytes when saving or forwarding the file rather than decoding them as text. For HTML invoices, plan the layout without CSS Flexbox or Grid, which Anvil’s generator does not support.
An interactive agent can use Anvil’s MCP tools instead. The following tool calls are pseudocode, not literal client syntax.
result = callDocumentedMcpPdfTool(approvedTemplate, validatedInvoiceFields)
invoicePdf = downloadBeforeExpiry(result.downloadUrl, result.expiresAt)The PDF-producing MCP tools return a signed download URL and an expiresAt timestamp rather than PDF bytes.
Verifying output before delivery
Verify the generated invoice against the approved order before delivery. Compare the recipient, line items, taxes, and total, and check that the PDF contains the expected invoice number. For invoices requiring human review, render the PDF so the reviewer can confirm that fields appear in the right places and no text is cut off. A successful Anvil request does not confirm that the invoice values match the order or that the layout is correct.
Keep the verified PDF in access-controlled storage and tie approval to that exact file. If you regenerate it after approval, obtain approval for the new file before sending it.
Treat MCP test runs as production PDF requests. MCP PDF fills and generations are billable and have no watermarked development mode. Use approved sample data in tests and verify every production invoice.
Controlled delivery and retries
After the reviewer approves the final PDF, intended recipient, and order totals, send that exact file. Record which approved PDF was delivered so a regenerated file requires a new review.
Key a delivery record to the invoice ID and approved PDF version, and reserve the attempt before sending. If a retry finds a completed send, stop. If the email provider times out, check its delivery status or message ID before trying again because the first attempt may have succeeded.
Keep Anvil API keys and email credentials on your server, not in browser code or agent prompts. Send only the order fields needed for the task to the agent or model provider. Your application remains responsible for approval, delivery, and retry decisions.
Authorization and account scope
An MCP-connected agent acts with the signed-in user's permissions, which may include access to account data and GraphQL mutations. Before it creates an invoice, use list_organizations to check the available Anvil organizations and select_organization if the active one must change. Enable tool-call approval where the MCP client supports it, especially for account-changing actions.
For unattended invoice jobs, keep an API key on your server and let your application decide which requests reach Anvil. The server can check that the order belongs to the right customer, require an approved invoice template, and reject requests outside the job’s purpose before it calls the PDF API. Those checks limit what the agent can initiate through your application, but they do not restrict the Anvil API key's own permissions. Never expose the key to the agent or its client.
Limitations to design around
- MCP requests are limited to roughly four per second per user. If you receive a 429 response, follow the documented retry guidance.
- Use the MCP tool result’s
expiresAtvalue to download the PDF before its signed link expires. If it has expired, rerun the PDF tool.
FAQs
Can MCP PDF tools run without a payment method on file? No. MCP PDF fills and generations require a payment method and return a Payment method required error without one. Read-only queries still work.
What happens if a signed link expires before download? Rerun the MCP fill or generation tool to obtain a new link. Check its expiresAt timestamp before downloading.
Can I create dynamic templates through the API? No. You create dynamic templates in Anvil’s dashboard Document Editor, then fill them through the API.
Does AI schema mapping work on every plan? No. Mapping for standardized templates requires AI Pack or higher. Review the proposed field matches before using the template.
What happens when PDF fill receives extra or missing JSON keys? The fill endpoint ignores keys that do not match template aliases. Missing or null values leave the corresponding fields unpopulated, so check required values and aliases before calling it.
Conclusion
For an interactive agent, start with Anvil’s MCP documentation. For a server integration, use its PDF filling or generation documentation. In either route, your application must validate the order and verify the PDF before delivering the approved file.
