Build a multi-page document over NextPDF Connect

At a glance

Build a document with several pages over NextPDF Connect. add_page appends a page that inherits the document’s default geometry, or sets its own orientation. After each add_page, the cursor resets to the top-left margin on the new page. You use four Core tools: create_pdf, add_text, add_page, and output_pdf.

Install

composer require nextpdf/server

Bind a transport: Model Context Protocol (MCP) stdio, REST, or gRPC. You do not need a licensed tier is required.

Conceptual overview

A document uses a page tree. You reach each page through that tree (ISO 32000-2 §7.7.3). A page has its own geometry attributes, including the media box that defines the visible area (ISO 32000-2 §7.7.3.3). create_pdf creates the first page automatically, and add_page appends each additional page. Omit page_size/orientation to inherit the document default. Set orientation: "landscape" to make an A4 page 297×210 mm.

API surface

Tool	Role	Risk tier
`create_pdf`	Open the session, first page created	Safe
`add_text`	Write text at the cursor	Caution
`add_page`	Append a page (inherit or override)	Caution
`output_pdf`	Render and return the PDF	Approval Required / Review (base64)

Tool names are registry protocol names. The tool catalog is the source of record. Your available tools depend on the installed tier.

Code sample — Quick start

In prose:

create_pdf (A4 portrait, title, author) → document_id.
add_text (title, large font, centered), then add_text (intro paragraph, body font).
add_page with only the document_id → inherits A4 portrait. The new page_number is returned and the cursor resets.
add_text for the section heading and body on page 2.
add_page with orientation: "landscape" → a wide A4 page.
add_text for the wide content.
output_pdf → base64.

Code sample — Production

Validate each response. After add_page, content starts at the top of the new page. The cursor reset is intended behavior, not a bug. Track position.page from add_text responses to detect when content has flowed onto a later page. Call output_pdf exactly once, then discard the document_id.

Edge cases & gotchas

Cursor reset. After add_page, the cursor sits at the new page’s top-left margin. A common mistake is expecting it to continue from the previous page.
Required document_id. Every tool except create_pdf requires the document_id. Omitting it is an error.
Invalid orientation. Only "portrait" and "landscape" are valid.
Editing after output. Content added after output_pdf with destroy: true fails, because the session is gone.

Performance

A multi-page text document stays within the page budget, and the output is a few KB. The profile is structural: the trailer /ID and timestamps are not stable across runs.

Security notes

Base64 mode has no side effects. File output is gated; see the human-in-the-loop (HITL) section. The document_id is an opaque handle. Do not share it across concurrent requests.

Conformance

Statement	Spec	Clause	reference_id
Pages are reached through the page tree.	ISO 32000-2	§7.7.3
A page object defines its own geometry attributes.	ISO 32000-2	§7.7.3.3

Commercial context

Not applicable — all tools are Core.

Transport availability

Transport	Available	Notes
MCP (stdio)	Yes	`tools/call` per tool.
REST	Yes	One operation per tool.
gRPC	Yes	Unary per tool.

HITL risk tier

create_pdf is Safe; add_text and add_page are Caution; output_pdf is Approval Required, downgraded to Review in base64 mode. File output remains Approval Required. See output-approval and HITL risk tiers.

Confirmation gate JSON envelope

Base64 output here:

{ "allowed": true }

The challenge form is shown in output-approval.