pdfnative-mcp

Sign PDF (RSA / ECDSA, PAdES)

sign_pdf

Sign a PDF digitally with CMS or PAdES signatures in one call. Auto-injects a signature placeholder if missing, and supports RSA/ECDSA key algorithms.

Instructions

CMS / PAdES signature in ONE call: a missing /Sig placeholder is auto-injected (prepare_signature_placeholder is optional). Inputs: pdfBase64, algorithm (rsa-sha256/384/512, ecdsa-sha256 P-256), certDerBase64 (+ certChainDerBase64 intermediates) and the DER key (rsaKeyPkcs1DerBase64 for rsa-*, ecPrivateKeyDerBase64 or ecPrivateScalarHex for ECDSA; PEM is rejected with the openssl remedy). profile:'pades' (ETSI EN 319 142-1 baseline) is the right choice when add_ltv / timestamp_pdf follow; timestamp:true = PAdES B-T through the operator TSA (TSA_NOT_CONFIGURED otherwise, no network without it). signerName/reason/location/contactInfo/signingTime are baked into the placeholder THIS call injects (a pre-built placeholder keeps its own). Several unsigned placeholders → pass fieldName (PLACEHOLDER_AMBIGUOUS); allowMultiple:true + a new fieldName adds a further signature. Verify with verify_pdf.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`reason`	No	/Sig /Reason — baked into the placeholder when this call injects it.
`profile`	No	'pkcs7' (default, adbe.pkcs7.detached) or 'pades' (ETSI EN 319 142-1 baseline; ETSI.CAdES.detached when the placeholder is injected here). Use 'pades' before timestamp / add_ltv / timestamp_pdf.	pkcs7
`location`	No	/Sig /Location — baked into the placeholder when this call injects it.
`algorithm`	Yes	Signature algorithm. 'rsa-sha384' / 'rsa-sha512' (pdfnative 1.7) upgrade the whole CMS digest chain. ECDSA only supports P-256 with SHA-256.
`fieldName`	No	Name of the signature field to sign (required when several unsigned placeholders exist) and of the placeholder injected by this call.
`pdfBase64`	Yes	Base64-encoded PDF bytes. When the PDF already contains an unsigned /Sig placeholder it is signed in place; otherwise the placeholder is auto-injected (set autoInjectPlaceholder=false to opt out).
`timestamp`	No	PAdES B-T: request an RFC 3161 signature timestamp from the operator-configured TSA (PDFNATIVE_MCP_TSA_URL). Fails with TSA_NOT_CONFIGURED when no TSA is configured — the server never contacts the network otherwise.
`outputMode`	No	'base64' (default) returns the PDF inline; 'file' writes it inside the PDFNATIVE_MCP_OUTPUT_DIR sandbox (SECURITY_VIOLATION when the sandbox is not configured).	base64
`outputPath`	No	Required when outputMode='file'. Relative path inside the sandbox; must end with .pdf (no absolute paths, no '..').
`signerName`	No	/Sig /Name — baked into the placeholder when this call injects it.
`contactInfo`	No	/Sig /ContactInfo — baked into the placeholder when this call injects it.
`signingTime`	No	ISO-8601 signing instant → /Sig /M (only when THIS call injects the placeholder) and the CMS signing-time (pkcs7 profile). Default: now. Not trusted time — use timestamp:true for that.
`allowMultiple`	No	Add a NEW signature next to existing (already signed) fields instead of signing the first placeholder. Requires fieldName. Each signature is an incremental revision; earlier signatures stay valid.
`certDerBase64`	Yes	Base64 of the signer X.509 certificate in DER form. Convert from PEM with: openssl x509 -in cert.pem -outform DER \| base64 -w0
`certChainDerBase64`	No	Optional intermediate CA certificates (DER base64) embedded in the CMS so verifiers and add_ltv can build the chain without fetching caIssuers.
`ecPrivateScalarHex`	No	Hex-encoded P-256 private scalar `d` (exactly 64 lowercase or uppercase hex chars, no 0x prefix). Mutually exclusive with ecPrivateKeyDerBase64; either is accepted for ECDSA.
`rsaKeyPkcs1DerBase64`	No	Base64 of the RSA private key in DER form — PKCS#1 RSAPrivateKey (openssl rsa -in key.pem -outform DER -traditional \| base64 -w0) or PKCS#8 PrivateKeyInfo (openssl pkey -in key.pem -outform DER \| base64 -w0). NOT PEM. Required for the rsa-* algorithms.
`autoInjectPlaceholder`	No	When true (default) and the input PDF has no /Sig widget, pdfnative.addSignaturePlaceholder is called before signing — enabling single-call signing of any PDF.
`ecPrivateKeyDerBase64`	No	Base64 of an ECDSA P-256 private key in SEC1 (RFC 5915) or PKCS#8 (RFC 5208) DER form. Convert from PEM with: openssl pkey -in key.pem -outform DER \| base64 -w0 Mutually exclusive with ecPrivateScalarHex.

Output Schema

TableJSON Schema

Name	Required	Description
`mode`	Yes
`summary`	No	Tool-specific summary, when produced.
`filePath`	No	Sandboxed absolute path (file mode).
`sizeBytes`	Yes
`diagnostics`	No	PDF/A diagnostics (when includeDiagnostics=true).

Schema Changelog

Changes observed during successful MCP inspections.

AddedAug 24, 2026
Removedv1.6.0Jul 22, 2026

Changed2 schema fields changedv1.2.0Jun 24, 2026

addedOutput schema / description

Added value: +"Structured result of a PDF-producing tool. In base64 mode the PDF bytes are delivered out-of-band as an embedded `resource` content block (data: URI), NOT duplicated here, to keep responses token-frugal. In file mode `filePath` is the sandboxed absolute path."

removedOutput schema / properties / base64

Removed value: -{
-  "description": "Base64-encoded PDF bytes (when mode='base64').",
-  "type": "string"
-}

First observedv1.1.0Jun 20, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the annotations (readOnlyHint=false, idempotentHint=false) by disclosing real behavioral consequences: auto-injection of a /Sig placeholder occurs in the same call, the injectable signature parameters are baked only into a newly injected placeholder, allowMultiple creates incremental revisions while previous signatures remain valid, and timestamp:true contacts the operator TSA while otherwise the server never touches the network. Known error states (TSA_NOT_CONFIGURED, PLACEHOLDER_AMBIGUOUS, SECURITY_VIOLATION) are explicitly named, giving the agent accurate failure expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense, and it is front-loaded with the core one-call capability before covering edge cases, error codes, and cross-tool relationships. Every sentence contributes either a usage constraint, an error condition, or a routing decision, though there is some redundancy with the schema's parameter-level descriptions that could be trimmed. For a 19-parameter signing tool, this length is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's 19 parameters and intricate PDF-signing semantics, the description covers the full decision surface: placeholder injection, placeholder ambiguity, multi-signature behavior, time-stamping trust, key format acceptance, and sandbox/network failure modes. Since an output schema exists, not restating return values is acceptable, and the description even tells the agent where to verify the result. No critical operational detail is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the structured schema already documents every parameter's meaning, formats, mutual exclusivity, and openssl conversion remedies. The description adds orchestration-level context (how algorithm selects the corresponding key parameter, how the injected placeholder interprets signerName/reason/location/contactInfo/signingTime) rather than new per-parameter semantics. This matches the baseline of 3 for a fully covered schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb (sign), a specific resource (PDF), and the two format families (CMS / PAdES), immediately distinguishing it from sibling utilities like add_ltv, timestamp_pdf, and verify_pdf. It also clarifies the one-call advantage over prepare_signature_placeholder, making the tool's identity unmistakable. The title reinforces the same scope without adding confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when profile:'pades' should be chosen ('right choice when add_ltv / timestamp_pdf follow'), when fieldName is required ('Several unsigned placeholders → pass fieldName'), and when allowMultiple applies ('adds a further signature'). It also names the verification counterpart ('Verify with verify_pdf') and explicitly rejects PEM with a remedy. Conditional usage rules are given with concrete triggers, so no selection is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.