pdfnative-mcp

Sign PDF (RSA / ECDSA, PAdES)

sign_pdf

Sign PDFs with CMS or PAdES in a single call, auto-injecting a missing /Sig placeholder. Accepts DER certificate and key inputs and supports timestamps.

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 \| openssl base64 -A
`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 \| openssl base64 -A) or PKCS#8 PrivateKeyInfo (openssl pkey -in key.pem -outform DER \| openssl base64 -A). 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 \| openssl base64 -A 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	Engine diagnostics (when includeDiagnostics=true).

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.6.2Sep 27, 2026

changedInput schema / properties / certDerBase64 / description

Previous value: -"Base64 of the signer X.509 certificate in DER form. Convert from PEM with: openssl x509 -in cert.pem -outform DER | base64 -w0"New value: +"Base64 of the signer X.509 certificate in DER form. Convert from PEM with: openssl x509 -in cert.pem -outform DER | openssl base64 -A"

changedInput schema / properties / ecPrivateKeyDerBase64 / description

Previous value: -"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."New value: +"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 | openssl base64 -A  Mutually exclusive with ecPrivateScalarHex."

changedInput schema / properties / rsaKeyPkcs1DerBase64 / description

Previous value: -"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."New value: +"Base64 of the RSA private key in DER form — PKCS#1 RSAPrivateKey (openssl rsa -in key.pem -outform DER -traditional | openssl base64 -A) or PKCS#8 PrivateKeyInfo (openssl pkey -in key.pem -outform DER | openssl base64 -A). NOT PEM. Required for the rsa-* algorithms."

changedOutput schema / properties / diagnostics / description

Previous value: -"PDF/A diagnostics (when includeDiagnostics=true)."New value: +"Engine diagnostics (when includeDiagnostics=true)."

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

Behavior4/5

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

Annotations cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), and the description goes well beyond them: auto-injection of the /Sig placeholder, error codes (TSA_NOT_CONFIGURED, PLACEHOLDER_AMBIGUOUS), the no-network guarantee, PEM rejection, and the fact that each allowMultiple signature is an incremental revision keeping earlier signatures valid. It stops short of stating revertibility or output/return shape, so a 4 rather than 5.

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?

Front-loaded with the one-call capability, then organized by input, profile choice, TSA behavior, placeholder metadata, and ambiguity handling. Extremely dense but no sentence is filler; the density slightly taxes readability, keeping it from a 5.

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?

For a 19-parameter cryptographic signing tool with an output schema and rich annotations, the description covers what to call, which profile, when the TSA is needed, how placeholder metadata is applied, and how to handle ambiguity and multiple signatures. Nothing an agent needs to invoke it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description supplies cross-parameter semantics the schema cannot: PEM is rejected with the openssl remedy, the placeholder-baking rule for signerName/reason/location/contactInfo/signingTime applies only when THIS call injects the placeholder, fieldName is required on ambiguity, and allowMultiple needs a new fieldName. That is real added meaning.

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?

Opens with a specific verb+resource+scope: 'CMS / PAdES signature in ONE call', and immediately clarifies the relationship to the sibling prepare_signature_placeholder (optional) and the verify step (verify_pdf). An agent can distinguish this from every other sibling in the list.

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?

Explicit routing rules: profile:'pades' 'is the right choice when add_ltv / timestamp_pdf follow', timestamp:true for PAdES B-T, allowMultiple:true to add a further signature, and verify with verify_pdf. Names conditions and alternatives rather than leaving them to inference.

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