Home  ›  Playgrounds  ›  MCP tool explorer

pdfnative-mcp tool explorer

The tools an AI assistant gets when you wire pdfnative-mcp v1.7.0 (pins pdfnative ^1.8.0, requires pdfnative ≥ 1.8.0 and Node ≥ 22; _meta.apiVersion = TOOL_API_VERSION 1.7.0) into Claude Desktop, Cursor, Continue, Zed, or any other MCP client (Cline, Windsurf, Goose, Gemini CLI…). The server exposes 28 tools — the catalogue did not grow in v1.7.0; what each tool can do did: a typography option on the nine document tools and on inspect_layout (paragraphs that split with orphan / widow control, justification with optical margins, kerning and OpenType features), CMYK colours on every colour input ([c, m, y, k] percent tuples or 'c m y k' operand strings), PDF/X-4 output (pdfx: "pdfx4", CMYK or Gray output intents, colour bars) with a structural check in validate_pdf { standard: "pdf-x-4" }, 27 scripts in add_international_text (Lao, Tai Tham, New Tai Lue, Tai Le and Cham join), and reproducible output (every date written in UTC; a per-call creationDate, or an operator-wide pin through PDFNATIVE_MCP_CREATION_DATE / SOURCE_DATE_EPOCH). Still there from earlier releases: the v1.6.0 PAdES ladder add_ltv / timestamp_pdf (with RFC 3161 timestamps on sign_pdf), update_metadata, the read-only inspect_layout pagination preview, all 13 block kinds in generate_basic_pdf, print production and charts v2, the v1.5.0 add_chart / form / encryption tools, the v1.4.0 markup annotate_pdf and network-free draft_governance_issue, the v1.3.0 page-tree trio merge_pdfs / split_pdf / extract_pages, a pdfA flag on every document tool, multi-script lang, and token-frugal read modes (verbosity / fields). Each card below shows a real example prompt, the payload it runs, and a button that produces the very PDF (or report) the AI assistant would receive — simulated with the pdfnative engine in your browser; the server returns the same shape. Older cards show the pdfnative library payload this page executes (the MCP schemas differ — see the MCP guide); the v1.7.0 cards show the exact MCP tool-call payload and map it to the engine in front of you. No API keys, no install, no LLM cost.

For the full integration story (config, security model, signed-document workflow), see the MCP guide.

1. Configure your client

Pick your client. The snippet below is what you paste into its MCP servers config. npx downloads pdfnative-mcp on first use; no global install needed.

Other clients: any tool that speaks the Model Context Protocol over stdio works — Cline, Windsurf, Goose, Aider, LibreChat, Sourcegraph Cody, Gemini CLI, and your own custom client. Use the same command: "npx" / args: ["-y", "pdfnative-mcp"] pair in whatever JSON shape your client expects.

2. Operator environment — the 12 variables

Everything the server reads from its process environment, as declared in server.json (MCP registry schema 2025-12-11). All are optional; none is ever settable from a tool argument. Set them in the env block of your client config. The two tagged v1.7.0 are new in this release.

VariablePurpose
PDFNATIVE_MCP_OUTPUT_DIRAbsolute path of a sandboxed directory where outputMode: "file" may write PDFs. Unset: every tool returns base64 only.
PDFNATIVE_MCP_CACHE_DIROpt-in content-addressed response cache (SHA-256 keyed, 1 h TTL, 256 MiB LRU, plaintext at rest). Never caches encrypt / decrypt, sign, timestamp, add_ltv, update_metadata, encrypted builds or file output. The namespace carries the creation-date pin below.
PDFNATIVE_MCP_PORTServe Streamable HTTP on this loopback port instead of stdio (stateless). Unauthenticated unless the token below is set.
PDFNATIVE_MCP_HTTP_TOKENSecret. Bearer token for the HTTP transport (≥ 16 chars, no whitespace); /mcp answers 401 without it. Never logged.
PDFNATIVE_MCP_MAX_INFLATE_BYTESPer-stream FlateDecode decompression cap in bytes (zip-bomb mitigation; default 104857600 = 100 MiB). Integer ≥ 1024; an invalid value refuses to start.
PDFNATIVE_MCP_CREATION_DATE v1.7.0ISO 8601 instant with a time zone (e.g. 2026-01-01T00:00:00Z) pinned as the creation date of every generated document — reproducible bytes on any host. An invalid value refuses to start.
SOURCE_DATE_EPOCH v1.7.0The reproducible-builds.org convention: integer seconds since the Unix epoch, used as the pin when PDFNATIVE_MCP_CREATION_DATE is unset. A shell that already exports it pins every document. An invalid value refuses to start.
PDFNATIVE_MCP_TSA_URLhttp(s) URL of the RFC 3161 timestamp authority used by sign_pdf timestamp: true and timestamp_pdf (PAdES B-T / B-LTA). Unset: those calls fail with TSA_NOT_CONFIGURED and no request is made.
PDFNATIVE_MCP_TSA_AUTHSecret. Optional Authorization header value sent to the TSA (Basic … or Bearer …). Never logged or echoed.
PDFNATIVE_MCP_REVOCATIONocsp, crl or ocsp,crl: enables online revocation collection for add_ltv mode: "online" (PAdES B-LT). Unset: that mode fails with REVOCATION_NOT_CONFIGURED; mode: "offline" stays offline.
PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTSComma-separated allow-list of OCSP / CRL responder hosts (host, host:port or *.suffix). Mandatory when the revocation variable is set; http(s) only, no credentials, no redirects, internal addresses rejected unless listed verbatim.
PDFNATIVE_MCP_NETWORK_TIMEOUT_MSPer-request timeout for TSA / OCSP / CRL calls in milliseconds, 1000–120000 (default 10000).

Creation-date precedence: per-call creationDate → PDFNATIVE_MCP_CREATION_DATE → SOURCE_DATE_EPOCH → the wall clock. The pin is read once at boot and its source is logged on stderr; a call's own creationDate always wins. Not covered by any pin, by design: signingTime, modDate, RFC 3161 tokens and revocation data, encryption (fresh key, salts, IVs), ECDSA signatures.

3. Prompts and error codes

The server advertises the prompts capability with 7 prompts — read-only recipes an agent can load before it calls a tool (typography is new in v1.7.0; print_ready, reproducible_output and pdfa_valid were rewritten for CMYK, PDF/X-4, colour bars and the UTC / operator pin):

  • governance_contract
  • draft_issue_workflow
  • pades_ladder
  • print_ready
  • reproducible_output
  • typography v1.7.0
  • pdfa_valid

Strict-mode error codes. With strict: true the server escalates the first engine diagnostic to a stable error code, chosen from the diagnostic's own code (src/diagnostics.ts, escalate()): PDFA_* → PDF_A_COMPLIANCE_VIOLATION; PDFX_* (PDFX_NO_FONT_ENTRIES, PDFX_DEVICE_CMYK, PDFX_ANNOTATIONS) → PDF_X_COMPLIANCE_VIOLATION v1.7.0; anything else (today TYPOGRAPHY_FEATURE_INEFFECTIVE) → DIAGNOSTIC_ESCALATED v1.7.0, whose message starts with [CODE]. The two new codes can only be returned by a call that sets strict: true; includeDiagnostics: true echoes the codes without failing. Other codes you will meet on this page: VALIDATION_ERROR (an incoherent PDF/X request is refused before any work), PRINT_ERROR (a file that is not an ICC profile), ENCRYPTED_SOURCE, GOVERNANCE_VIOLATION, PDF_PARSE_FAILED. The PDF/X-4 card below prints the engine code and the server code it maps to whenever the build raises a PDFX_* diagnostic.

4. Try the tools

Loading pdfnative from esm.sh… this happens once per page load.

The interactive cards below cover the core document-authoring tools, the v1.3.0 page-tree trio (merge_pdfs, split_pdf, extract_pages), the v1.4.0 annotate_pdf, the v1.6.0 update_metadata, and the six v1.7.0 cards — generate_basic_pdf with typography, generate_basic_pdf as PDF/X-4 with CMYK colours and colour bars, validate_pdf { standard: "pdf-x-4" }, inspect_pdf { check: ["pdfx", "trapped"] }, add_international_text with the five new scripts, and a reproducible generate_basic_pdf that is built twice and hashed — all of which build their own source PDFs in the browser and run the real pdfnative 1.9.0 API. Three cards produce no PDF by design: inspect_layout returns a pagination report, validate_pdf and inspect_pdf (PDF/X) return structured reports (run them to see the JSON), and draft_governance_issue validates a report locally, network-free — use its Copy args button. Ten of the 28 tools have no card here: eight need a real PDF as input and run best from your own MCP client (verify_pdf, add_attachment, extract_attachments, extract_text, read_form_fields, fill_form, encrypt_pdf, decrypt_pdf), and two need the operator-configured network providers a browser page cannot supply (add_ltv, timestamp_pdf — TSA / OCSP / CRL endpoints set via the environment variables above). See the MCP guide for their full schemas.

5. Now ask your AI assistant

Once you've pasted the config snippet above and restarted your client, ask it anything PDF-shaped:

The AI assistant will pick the right tools, fill the JSON arguments, and pdfnative will render the PDF — no code from you.

Resources