pdfnative-mcp

Sign PDF (RSA / ECDSA, PAdES)

sign_pdf

Sign PDFs with CMS or PAdES in one call, auto-adding a missing /Sig placeholder and accepting RSA or ECDSA keys with optional 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

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

Name	Required	Description
`url`	No	Public URL of the file (file mode, only when PDFNATIVE_MCP_OUTPUT_BASE_URL is set): base URL + sandbox-relative path, percent-encoded.
`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.

Changed2 schema fields changedv1.8.0Nov 3, 2026

changedOutput schema / description

Previous value: -"Result of a PDF-producing tool. base64 mode: the PDF arrives as an embedded `resource` content block (not duplicated here); file mode: `filePath`."New value: +"Result of a PDF-producing tool. base64 mode: the PDF arrives as an embedded `resource` content block (not duplicated here); file mode: `filePath` (and `url` when the operator maps the sandbox to a public base URL)."

addedOutput schema / properties / url

Added value: +{
+  "description": "Public URL of the file (file mode, only when PDFNATIVE_MCP_OUTPUT_BASE_URL is set): base URL + sandbox-relative path, percent-encoded.",
+  "type": "string"
+}

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.2/5.0

Behavior3/5

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

Annotations already flag a non-read-only, non-idempotent, open-world write, and the description adds genuinely useful context beyond them: TSA_NOT_CONFIGURED when no TSA is set, 'the server never contacts the network otherwise' (narrowing the open-world scope), PEM rejection with an openssl remedy, and that earlier signatures survive as incremental revisions. It does not, however, discuss permission/auth requirements for the private key material or what happens to the input PDF on failure. Solid but not exhaustive for a signing operation.

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 single most important fact ('ONE call', auto-injection) and then packed with actionable detail justified by a 19-parameter tool. It is dense to the point of being a wall of parentheticals and semicolons, and the PEM rejection is stated twice (description and schema), which costs a little readability.

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 complex crypto tool it covers the full call path: key material formats, placeholder injection vs. reuse, profile choice for downstream LTV/timestamp steps, failure modes, and the verify_pdf handoff. An output schema exists, so return-value explanation is correctly omitted.

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 schema already documents all 19 parameters thoroughly, making 3 the baseline. The description adds a decision-level mapping (rsaKeyPkcs1DerBase64 for rsa-*, ec* variants for ECDSA) and reinforces the PEM rejection, but most of that is already in the schema text, so the added value is marginal rather than transformative.

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?

States a specific verb+resource (CMS/PAdES signature) and its key scope claim ('in ONE call'), then immediately positions prepare_signature_placeholder as optional and names verify_pdf as the follow-up. An agent can distinguish it from the sibling placeholder and verification tools without opening any schema.

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?

Gives explicit routing rules: use profile:'pades' when add_ltv / timestamp_pdf follow, pass fieldName when several unsigned placeholders exist (with the PLACEHOLDER_AMBIGUOUS condition), and use allowMultiple + a new fieldName for an additional signature. It also names the alternative workflow (prepare_signature_placeholder) and states when it can be skipped.

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