Pro edition

MCP Tools — Deep Reference

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

There is no per-feature license flag. The code ships with the Pro edition, and the eight tools register under the pro tier when the Pro package resolves at boot alongside nextpdf/server.

Behavior contract

NextPDF Server discovers tiers at boot by probing for the Pro tool-provider class; if it resolves, the server registers the eight tools under the pro tier. The Pro package is not a hard dependency of the server, so the Pro tools are strictly opt-in by co-installation. Tier registration is independent: a missing or policy-excluded tier never blocks the others.
Each tool declares one of four risk levels (safe, caution, review, approval-required). An optional operator override can only raise a tool’s level, never lower it; the server audit-logs any execution at caution or above. sign_pdf is approval-required.
PDF input resolves in a fixed order: document_id from the in-memory store, then source as a data: URI, filesystem path, or raw base64. Missing input returns a validation error rather than processing an empty document.
sign_pdf produces a PAdES B-B baseline signature only — no timestamp, no long-term validation. Supported algorithms and the AES-GCM key-transport envelope are detailed below; decryption fails closed and the tool never uses ciphertext as key material.
See the sections below for the full discovery, risk, source-resolution, per-tool, and signing detail. This page describes externally observable behavior and the published tool contract only.

Scope

This page is the operator and integrator reference for the eight Pro MCP tools. It covers the discovery model, the risk/HITL semantics the server applies, source-resolution rules, the signing key-transport envelope, and per-tool failure behavior. It describes externally observable behavior and the published tool contract only. For the user-facing catalog see the public MCP page.

Discovery and registration model

NextPDF Server discovers tier providers at boot. It detects the Pro tier by probing for the Pro tool-provider class; if the class resolves, the server instantiates the provider and registers each tool it returns under the pro tier. The Pro package is intentionally not a hard dependency of the server — this keeps the open-source server installable without the proprietary package, and makes the Pro tools strictly opt-in by co-installation.

The server isolates registration per tier. If the Pro package is absent, Core tools still register; a present tier provider does not block other tiers. Tool registration is also subject to the server’s security policy allow-list: a tool excluded by policy is silently not registered and is not counted in the tier summary. The server exposes a per-tier count (core / pro / enterprise) for diagnostics and logging.

The provider returns the eight tools in a fixed order: text extraction, segmentation, comparison, PII masking, form fill, form read-back, accessibility analysis, signing. Order is stable but callers must not depend on it — resolve tools by their MCP protocol name.

Risk model and HITL semantics

Each tool declares one of four risk levels. The server uses the declared level for human-in-the-loop enforcement:

Safe — read-only, no side effects. Auto-executes.
Caution — creates or modifies in-memory state. Auto-executes with an audit-log entry.
Review — produces output that could be misused. Auto-executes, but the agent skill instructions flag it so the agent warns the user.
Approval-required — destructive, legal, or privacy-critical. The server requires explicit human confirmation before execution.

Pro tool classifications: the five extraction/analysis tools (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) are safe; redact_pii and fill_form are review; sign_pdf is approval-required.

The risk level comes from exactly two sources: the tool’s own declaration, and an optional operator override at runtime. The override can only raise a tool’s risk level (tighten enforcement); it can never lower it. The server audit-logs any execution at caution level or above. The risk model carries a version; the server advertises that version in its initialization response so clients can detect an incompatible change.

Source-resolution order

Every tool that takes a PDF accepts it through one of three input shapes, resolved in this order:

document_id — the server retrieves bytes from its in-memory document store. An unknown id fails with an explicit error directing the caller to create the document first.
source as a data: URI — the tool decodes the base64 body after the comma.
source as a filesystem path — the tool reads from disk when the path resolves to a file.
source as a raw base64 string — the tool accepts and decodes only sufficiently long, base64-shaped input.

compare_pdfs applies the same resolution independently to source_a and source_b, and additionally accepts a document_id value in either source slot. If neither a document_id nor a source is supplied, the tool returns a validation error rather than processing an empty document.

Per-tool reference

Tool	Risk	Inputs	Result fields	Behavioral boundary
`extract_text`	safe	PDF; optional 1-indexed `page_start` / `page_end`	text, total page count	Text-layer only; ranges clamped to real page count; no OCR
`segment_document`	safe	PDF	segment count, segment list	Layout-derived segments; not a tagged-PDF structure tree
`compare_pdfs`	safe	two PDFs	identical flag, total changes, per-doc page counts, regions (type, text, page index, line index, optional counterpart text)	Text-content diff; not visual or binary
`redact_pii`	review	PDF; optional `types` (`email`, `phone`, `ssn`, `credit_card`)	has-PII flag, detected count, masked text, scanned types	Text-layer detection/masking; not visual redaction; pattern-based, not exhaustive
`fill_form`	review	`fields` map; optional `pdf_filename`	XFDF document, field count	Produces XFDF (ISO 19444-1); does not write values into a PDF
`extract_form_data`	safe	PDF	field count, field map, explicit note when none	Reads embedded XFDF only
`check_accessibility`	safe	PDF	structural score (0–100), issues, segment summary	Structural heuristic with WCAG references; not a conformance verdict
`sign_pdf`	approval-required	PDF; PEM cert + PKCS#8 key; optional algorithm, signer name, reason, transport envelope	signed PDF, signature count, completion flag, algorithm, OID, digest	PAdES B-B baseline only; no timestamp, no LTV

Signing: algorithms and key transport

sign_pdf produces a PAdES B-B baseline signature. Supported algorithms, accepted in both underscore and dashed spellings:

RSA with SHA-256 (default).
RSA with SHA-3 256 / 384 / 512 — requires an OpenSSL build with SHA-3 support.
Ed25519 — requires the libsodium extension; the key must be a PKCS#8 PEM wrapping the Ed25519 private key.

The tool rejects unsupported identifiers and returns the list of accepted values.

The optional transport-encryption envelope lets a caller tunnel the private key through a transport that is not end-to-end confidential. The envelope is AES-GCM only:

Symmetric key: 16, 24, or 32 bytes (AES-128/192/256), base64-encoded.
Nonce: exactly 12 bytes, base64-encoded.
Optional additional authenticated data, base64-encoded.
The private_key payload is the base64 ciphertext with a trailing 16-byte GCM authentication tag.

Decryption fails closed: an authentication-tag mismatch or a malformed payload returns a decryption error, and the tool never uses the ciphertext as key material. The tool rejects wrong key or nonce sizes before any cryptographic work.

Edge cases and FIPS-mode

extract_text: the tool clamps a page-range end that exceeds the document rather than rejecting it, and normalizes a start below the first page to the first page.
compare_pdfs: a missing source_a or source_b returns a validation error; identical documents return an explicit identical result with zero changes.
extract_form_data: PDFs without an embedded XFDF stream return a zero-field result with an explanatory note, not an error.
redact_pii: an unrecognized entry in types is ignored; an all-unrecognized list yields an empty scan rather than a failure.
sign_pdf: a missing certificate or private key fails before any signing work; the tool checks algorithm requirements (SHA-3 OpenSSL support, libsodium for Ed25519) at signing time and surfaces them as explicit errors.
FIPS-mode: algorithm availability follows the host OpenSSL/libsodium build. In a FIPS-constrained build, non-approved algorithms fail at the cryptographic boundary with an explicit error rather than silently downgrading. The MCP layer does not add or relax cryptographic policy — it surfaces the host crypto provider’s decision.

Operator runbook notes

Keep sign_pdf approval-required. Confirm there is no operator override that raises risk on the safe tools unintentionally — overrides only tighten, so an accidental override degrades availability, not safety.
Audit retention: every execution at review level or above is audit-logged by the server. Size your log retention for the volume of redact_pii, fill_form, and sign_pdf calls.
Transport choice: when running over a transport that is not end-to-end confidential, require the AES-GCM key-transport envelope for sign_pdf and treat private-key material as a secret in your agent’s tool-call logging policy.
Tier counts: use the server’s per-tier count to assert at deploy time that the Pro tier registered eight tools; a count of zero indicates the Pro package did not resolve.

Edition boundary

The Pro tier contributes exactly eight MCP tools. The Enterprise edition ships a separate MCP tier with its own tools — compliance, forensics, long-term-validation health, AI-ready certification, and document search/embedding. Enterprise tool inputs, outputs, and internals are out of scope here and documented with the Enterprise edition. The server discovers tiers independently; a missing tier never disables another.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.