Pro edition

MCP Tools

At a glance

NextPDF Pro adds eight Model Context Protocol (MCP) tools that let an AI agent run advanced PDF operations through NextPDF Server. The tools surface automatically when both nextpdf/pro and nextpdf/server are installed — no separate registration step is required.

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.

The base MCP surface — document creation, text, tables, diagnostics — ships with the open-source NextPDF Server and needs no license. The eight tools on this page require a Pro license and register only when the nextpdf/pro package resolves at boot. The pro tool tier gates the whole set: each tool declares its tier explicitly, and there is no per-tool flag — installing nextpdf/pro alongside nextpdf/server enables the set.

Behavior contract

The eight Pro MCP tools register automatically when both nextpdf/pro and nextpdf/server resolve at boot, under the pro tier, through the standard MCP tools/list and tools/call flow. There is no per-tool flag and no code change in the consuming application.
Each tool accepts a PDF via a document_id from an earlier create_pdf call, an inline source (file path, base64, or data: URI), or — for compare_pdfs — two such sources. Tools return structured JSON.
Every tool declares a HITL risk class the server enforces: safe (auto-execute, read-only), review (output that could be misused), and approval-required. sign_pdf is approval-required and is held until a human confirms it. An operator can only tighten a tool’s risk class, never relax it.
sign_pdf produces a PAdES B-B (baseline) signature only — no trusted timestamp and no long-term validation material. Long-term (B-LT / B-LTA) profiles, hardware key custody, and audit-trail signing are Enterprise-tier and not provided by these tools; B-T (a timestamped signature) is available from the Core engine when a timestamp provider is configured.
redact_pii performs text-layer pattern detection and masking, not visual redaction; check_accessibility is a structural heuristic, not a PDF/UA or WCAG conformance verdict. The authoritative input/output schema is the server’s live tools/list response, not this page.

Conceptual overview

NextPDF Server is the deterministic MCP execution layer for NextPDF. It discovers tool providers at boot using a class-existence probe, so the Pro package does not need to be listed in the server’s dependencies. When the Pro package is present, the server registers its eight tools under the pro tier and exposes them through the standard MCP tools/list and tools/call flow over whichever transport you have configured.

Each Pro tool accepts a PDF from one of three sources: a document_id returned by an earlier create_pdf call, an inline source (file path, base64 string, or data: URI), or — for the comparison tool — two such sources. Tools return structured JSON results: extracted text, diff regions, masked text, segment trees, accessibility findings, or a signed PDF.

Every Pro tool carries a risk classification that the server uses for human-in-the-loop (HITL) enforcement. Read-only analysis tools rank as safe and auto-execute. Tools that generate output a caller could misuse rank for review. The signing tool ranks as approval-required, so the server holds it until a human confirms it. The tool itself declares this classification; an operator can only tighten it at runtime — never loosen it.

The MCP tool surface is intentionally separate from the Pro PDF engine. The tools are thin adapters: they validate inputs, resolve the PDF, delegate to a Pro engine component, and serialize the result. They are not a second API for the engine and are not part of the Pro public PHP API — the supported integration point is the MCP protocol exposed by NextPDF Server.

Tool catalog (eight Pro tools)

The eight Pro MCP tools, by MCP protocol name. Risk levels follow the server’s HITL model: safe (auto-execute, read-only), review (generates output that could be misused; warned in agent instructions), and approval-required (must be confirmed by a human).

`extract_text`

Purpose: Text extraction. Extract the text layer of a PDF, optionally limited to a 1-indexed page range.
Inputs: A PDF (document_id or source); optional page_start and page_end.
Outputs: Extracted text and total page count.
Risk: Safe. Read-only and idempotent.
Boundary: Extracts the existing text layer. It does not perform OCR on scanned or image-only pages.

`segment_document`

Purpose: Structural segmentation. Split a PDF into logical sections — title, headings, body, tables, figures.
Inputs: A PDF (document_id or source).
Outputs: A segment count and a structured list of segments.
Risk: Safe. Read-only and idempotent.
Boundary: Structural segmentation based on layout analysis; it is not a semantic outline or a tagged-PDF structure tree.

`compare_pdfs`

Purpose: Structural diff. Compare two PDFs and return a structured diff of their text content.
Inputs: Two PDFs (source_a and source_b, each a path, base64, data URI, or document_id).
Outputs: An identical flag, total change count, per-document page counts, and a list of changed regions with page and line indices.
Risk: Safe. Read-only and idempotent.
Boundary: Text-content diff. It does not diff visual rendering, embedded fonts, or binary structure.

`redact_pii`

Purpose: PII detection and masking. Detect personally identifiable information in a PDF’s text layer and return a masked view of the text.
Inputs: A PDF (document_id or source); optional types filter (email, phone, ssn, credit_card).
Outputs: A has-PII flag, detected count, masked text, and the list of types scanned.
Risk: Review. The masked output could be misused if treated as a sanitized document.
Boundary: This is text-layer pattern detection and masking, not visual redaction. It does not remove or overwrite glyphs in the rendered PDF, and pattern matching does not guarantee that every instance of sensitive data is found. Do not treat its output as a guarantee of complete PII removal. For document-level redaction that destroys the underlying content, use the dedicated redaction surface in the open-source server tools or the Enterprise edition.

`fill_form`

Purpose: AcroForm fill data. Generate XFDF (ISO 19444-1) data that fills PDF AcroForm fields from a map of field names to values.
Inputs: A fields map of field name to string value; optional pdf_filename embedded as the XFDF reference.
Outputs: The generated XFDF document and the field count.
Risk: Review. It produces form data intended to be applied to a document.
Boundary: It produces standards-compliant XFDF; it does not itself write the values back into a PDF. Apply the XFDF with any compliant reader or processing tool.

`extract_form_data`

Purpose: AcroForm read-back. Extract AcroForm field names and values from XFDF embedded in a PDF.
Inputs: A PDF (document_id or source).
Outputs: A field count and a map of field names to values; an explicit note when no embedded form data is present.
Risk: Safe. Read-only and idempotent.
Boundary: Reads embedded XFDF (ISO 19444-1) streams. A PDF that holds form values only in AcroForm objects without embedded XFDF returns an empty result.

`check_accessibility`

Purpose: Structural accessibility analysis. Analyze a PDF’s structural accessibility — headings, paragraphs, tables, and images — and report likely issues with WCAG references.
Inputs: A PDF (document_id or source).
Outputs: A structural score (0–100), a list of issues, and a segment summary.
Risk: Safe. Read-only and idempotent.
Boundary: This is a structural heuristic, not a conformance verdict. Full PDF/UA and WCAG conformance testing — tag tree, reading order, color contrast — requires a dedicated accessibility engine. A high score is not a statement of PDF/UA conformance.

`sign_pdf`

Purpose: PAdES B-B digital signature. Apply a PAdES B-B (baseline) digital signature to a PDF using a local X.509 certificate and private key.
Inputs: A PDF (document_id or source); a PEM certificate and PKCS#8 private key; an optional algorithm (RSA-SHA256 default, RSA + SHA-3 256/384/512, or Ed25519); optional signer name and reason; an optional AES-GCM transport envelope around the private-key payload.
Outputs: The signed PDF, signature count, completion flag, and the algorithm, OID, and digest used.
Risk: Approval-required. Signing is a legally significant, destructive operation; the server requires explicit human confirmation before it runs.
Boundary: This tool produces a PAdES B-B (baseline) signature — it does not embed a trusted timestamp or long-term validation material. Long-term (B-LT / B-LTA) profiles, hardware-backed key custody, and audit-trail signing are part of the Enterprise edition; B-T (a timestamped signature) is available from the Core engine when a timestamp provider is configured. See the Pro signature surface for the broader signing capabilities of the Pro package and the Enterprise edition for B-LT/B-LTA.

How the tools surface

composer require nextpdf/pro
composer require nextpdf/server

With both packages installed, start NextPDF Server with your chosen transport. The server discovers the Pro tier at boot and the eight tools appear in the MCP tools/list response under the pro tier alongside the open-source Core tools. Your application needs no code change — discovery runs automatically and a missing tier never blocks the others from loading.

The authoritative input and output schema for every tool is the schema the server publishes in its tools/list response. Treat that response — not this page — as the contract: this catalog describes intent and boundaries; the live schema describes exact field names and types.

Code sample — Quick start

The Pro tools are consumed over the MCP protocol, not through a Pro PHP API. The host-side integration is booting NextPDF Server. With nextpdf/pro present, the eight tools register through runtime discovery — no per-tool wiring — and the host then serves them to agents.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

require __DIR__ . '/vendor/autoload.php';

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Code sample — Production

Harden the boot path. Load an explicit policy file, refuse to start on an invalid risk-level override, and confirm the Pro tier surfaced before serving. The wiring in McpServer::create() throws InvalidArgumentException when a risk_level_overrides block tries to weaken an approval-required tool such as sign_pdf, so a misconfigured policy fails closed before the serving loop.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

require __DIR__ . '/vendor/autoload.php';

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Production guidance

HITL gating. Keep sign_pdf behind human confirmation. The server enforces this from the tool’s declared risk level; do not configure your agent to bypass it. An operator can only tighten a tool’s risk level, never relax it.
Source handling. Prefer document_id for documents already in the session. For inline data, the tools accept base64 and data: URIs; very large inline payloads run slower than a referenced document.
PII expectations. Set caller expectations explicitly: redact_pii is a detection-and-masking aid, not a sanitization guarantee. For irreversible removal, route to a dedicated redaction surface.
Signing keys. Supply keys through the transport encryption envelope when the transport is not end-to-end confidential. Treat private-key material as a secret in your agent’s tool-call logging policy.
Audit logging. Tools above the safe level are audit-logged by the server. Ensure your deployment retains those logs per your compliance requirements.

Edge cases

extract_text page ranges are 1-indexed and clamped to the document’s real page count; an out-of-range end does not error.
compare_pdfs requires both sources; passing one returns a clear validation error rather than a partial diff.
extract_form_data returns a populated, explicit “no embedded form data” result rather than an error for PDFs without embedded XFDF.
sign_pdf rejects unsupported algorithm identifiers with the list of supported values; Ed25519 requires the libsodium extension and SHA-3 variants require an OpenSSL build with SHA-3 support.
check_accessibility scores image-only PDFs poorly by design — it flags the absence of a readable text layer rather than failing.

Security notes

The signing tool is the only approval-required tool; the server will not auto-execute it.
The optional AES-GCM envelope around the private key authenticates the payload; a tag mismatch fails closed with a decryption error and never falls back to using the ciphertext.
redact_pii does not alter the source PDF; it returns a masked text representation. It is not a substitute for content destruction.
The tool validates inputs before any engine work; it rejects malformed sources, data URIs, and base64 payloads with explicit errors.

Conformance

Form tools produce and consume XFDF per ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf produces a PAdES baseline (B-B) signature aligned with the ETSI EN 319 142 PAdES family; long-term profiles are an Enterprise capability, and B-T is available from the Core engine when a timestamp provider is configured.
check_accessibility reports findings with WCAG success-criterion references (for example 1.1.1, 1.3.1, 2.4.6) as heuristic guidance, not a conformance attestation.

Edition boundary

NextPDF Pro contributes exactly eight MCP tools, all at the pro tier. The Enterprise edition ships its own, separate MCP tool set at the enterprise tier — covering compliance checking, forensic analysis, long-term-validation health, AI-ready certification, and document search and embedding. Those tools, their inputs, and their internals are out of scope for this page; see the Enterprise MCP tools. The server’s own documentation covers the Core (open-source) tools that ship with it. The server discovers the three tiers independently, and a missing tier never disables the others.

Enterprise boundary note

Pro contributes exactly eight MCP tools at the pro tier. The Enterprise edition ships a separate MCP tool set at the enterprise tier (compliance checking, forensic analysis, long-term-validation health, AI-ready certification, document search and embedding) and the timestamped/long-term signature profiles; those are not provided by the Pro tier. See the Edition boundary section above for the full tier breakdown.

Core fallback / alternative

The open-source NextPDF Server gives any AI agent a deterministic Core PDF toolset (document creation, text, tables, diagnostics) with no license. The eight advanced tools on this page are Pro additions. See /connect/tools/.

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.