Assinafy MCP Server

Create assignment (request signatures)

assinafy_create_assignment

Request signatures on a document. Use method: virtual to sign without input fields, or method: collect to place input fields on specific pages. DigitalCertificate signers require method: virtual; other methods fail with code digital_certificate_requires_virtual.

For virtual, the document may be in uploaded, metadata_processing or metadata_ready; it is promoted to pending_signature automatically once metadata processing completes. For collect, the document must be in metadata_ready (fields reference specific pages).

step controls signing order: signers sharing a step sign in parallel, and the next step is notified only after the previous step completes. If supplied, every signer must supply it and values must be contiguous starting at 1. Obtain signer IDs from assinafy_list_signers or assinafy_create_signer and page IDs from assinafy_get_document. This sends signing invitations. Check with assinafy_get_document that no assignment exists first; this can consume credits.

Input Schema

Name	Required	Description	Default
`method`	Yes		virtual
`entries`	No	Required for `collect`: field placements per page.
`message`	No	Text included in the invitation email.
`signers`	Yes
`expires_at`	No	ISO 8601; default is no expiration. Must be at least one hour in the future.
`document_id`	Yes	Document ID.
`estimate_only`	No	Preview cost and balances without creating an assignment or notifying anyone.
`copy_receivers`	No	Signer IDs that only receive a copy.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 19, 2026

changedInput schema / properties / signers / items / properties / verification_method / description

Previous value: -"How the signer's identity is verified before signing. `Email` (default) sends a one-time code to the signer's email; `Whatsapp` sends the code over WhatsApp — the verification itself is not billed, but it requires the WhatsApp notification channel, so the signer costs 0.45 credits (available only on paid subscriptions); `DigitalCertificate` has the signer sign with their own ICP-Brasil certificate (A1/A3) — it requires the Digital Certificate feature, the signer must have a CPF or CNPJ in `government_id`, must be alone in its signing step, and is charged 0.5 credits per signer. A CPF requires that person's certificate (an e-CPF, or an e-CNPJ naming them as legal representative); a CNPJ requires an e-CNPJ for that company, from any of its representatives. `IdDocumentFaceMatchBasic` verifies the signer from a photo of their government ID, a photo of them holding it and a liveness check — it requires the ID Document + Face Match feature, the signer must have a valid CPF in `government_id`, and is charged a per-signer fee. Omit to default to `Email`."New value: +"How the signer's identity is verified before signing. `Email` (default) sends a one-time code to the signer's email; `Whatsapp` sends the code over WhatsApp — the verification itself is not billed, but it requires the WhatsApp notification channel, so the signer costs 0.45 credits (available only on paid subscriptions); `DigitalCertificate` has the signer sign with their own ICP-Brasil certificate (A1/A3) — it requires `method: virtual`, the Digital Certificate feature, a CPF or CNPJ in `government_id`, must be alone in its signing step, and is charged 0.5 credits per signer. A CPF requires that person's certificate (an e-CPF, or an e-CNPJ naming them as legal representative); a CNPJ requires an e-CNPJ for that company, from any of its representatives. `IdDocumentFaceMatchBasic` verifies the signer from a photo of their government ID, a photo of them holding it and a liveness check — it requires the ID Document + Face Match feature, the signer must have a valid CPF in `government_id`, and is charged a per-signer fee. Omit to default to `Email`."

Changed11 schema fields changedOct 16, 2026

changedInput schema / allOf

Previous value: -[
-  {
-    "if": {
-      "properties": {
-        "method": {
-          "const": "collect"
-        }
-      },
-      "required": [
-        "method"
-      ]
-    },
-    "then": {
-      "properties": {
-        "entries": {
-          "minItems": 1
-        }
-      },
-      "required": [
-        "entries"
-      ]
-    }
-  }
-]New value: +[
+  {
+    "if": {
+      "properties": {
+        "method": {
+          "const": "collect"
+        }
+      },
+      "required": [
+        "method"
+      ]
+    },
+    "then": {
+      "properties": {
+        "entries": {
+          "minItems": 1
+        }
+      },
+      "required": [
+        "entries"
+      ]
+    }
+  },
+  {
+    "else": {
+      "properties": {
+        "signers": {
+          "items": {
+            "required": [
+              "id"
+            ]
+          }
+        }
+      }
+    },
+    "if": {
+      "properties": {
+        "estimate_only": {
+          "const": true
+        }
+      },
+      "required": [
+        "estimate_only"
+      ]
+    }
+  }
+]

addedInput schema / properties / estimate_only

Added value: +{
+  "description": "Preview cost and balances without creating an assignment or notifying anyone.",
+  "type": "boolean"
+}

changedInput schema / properties / expires_at / description

Previous value: -"ISO 8601; default is no expiration."New value: +"ISO 8601; default is no expiration. Must be at least one hour in the future."

changedInput schema / properties / signers / items / properties / notification_methods / description

Previous value: -"Channels used to notify the signer of the request. Any combination of `Email` and `Whatsapp` (WhatsApp incurs an additional cost and is available only on paid subscriptions). Omit to default to `{\"Email\"}`."New value: +"How the signer is told a signature is being requested. **Exactly one method per signer** — the array shape is historical, and sending two returns `400`. The method must also be compatible with `verification_method`: `Email` verification takes `Email`, `Whatsapp` verification takes `Whatsapp`, and `DigitalCertificate` and `IdDocumentFaceMatchBasic` take either. WhatsApp incurs an additional cost and is available only on paid subscriptions. Omit it to have it inferred from `verification_method`, or `{\"Email\"}` when neither is sent. See **Verification & Notification Methods** for the full pairing table."

addedInput schema / properties / signers / items / properties / notification_methods / example
```
Added value: +[
+  "Email"
+]
```
addedInput schema / properties / signers / items / properties / notification_methods / maxItems
```
Added value: +1
```
addedInput schema / properties / signers / items / properties / step / minimum
```
Added value: +1
```

changedInput schema / properties / signers / items / properties / verification_method / description

Previous value: -"How the signer's identity is verified before signing. `Email` (default) sends a one-time code to the signer's email; `Whatsapp` sends the code over WhatsApp — the verification itself is not billed, but it requires the WhatsApp notification channel, so the signer costs 0.45 credits (available only on paid subscriptions); `DigitalCertificate` has the signer sign with their own ICP-Brasil certificate (A1/A3) — it requires the Digital Certificate feature, the signer's CPF or CNPJ must already be registered on their Assinafy contact (added in Assinafy, never through this tool), must be alone in its signing step, and is charged 2 credits per signer. A CPF requires that person's certificate (an e-CPF, or an e-CNPJ naming them as legal representative); a CNPJ requires an e-CNPJ for that company, from any of its representatives. Omit to default to `Email`."New value: +"How the signer's identity is verified before signing. `Email` (default) sends a one-time code to the signer's email; `Whatsapp` sends the code over WhatsApp — the verification itself is not billed, but it requires the WhatsApp notification channel, so the signer costs 0.45 credits (available only on paid subscriptions); `DigitalCertificate` has the signer sign with their own ICP-Brasil certificate (A1/A3) — it requires the Digital Certificate feature, the signer must have a CPF or CNPJ in `government_id`, must be alone in its signing step, and is charged 0.5 credits per signer. A CPF requires that person's certificate (an e-CPF, or an e-CNPJ naming them as legal representative); a CNPJ requires an e-CNPJ for that company, from any of its representatives. `IdDocumentFaceMatchBasic` verifies the signer from a photo of their government ID, a photo of them holding it and a liveness check — it requires the ID Document + Face Match feature, the signer must have a valid CPF in `government_id`, and is charged a per-signer fee. Omit to default to `Email`."

changedInput schema / properties / signers / items / properties / verification_method / enum

Previous value: -[
-  "Email",
-  "Whatsapp",
-  "DigitalCertificate"
-]New value: +[
+  "Email",
+  "Whatsapp",
+  "DigitalCertificate",
+  "IdDocumentFaceMatchBasic"
+]

addedInput schema / properties / signers / items / properties / verification_method / example
```
Added value: +"Email"
```
removedInput schema / properties / signers / items / required
```
Removed value: -[
-  "id"
-]
```

AddedOct 13, 2026
RemovedSep 18, 2026
AddedSep 17, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare non-readOnly, non-idempotent, openWorld, non-destructive, but the description adds real behavioral context beyond them: this action sends invitations, consumes credits, promotes document state automatically for virtual, imposes the collect-only 'metadata_ready' prerequisite, and surfaces the specific failure code digital_certificate_requires_virtual. That is above-bar disclosure for a mutation tool.

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?

Four tight paragraphs, front-loaded with the mode decision and prerequisites, and every sentence carries operational information (states, error codes, step rules, credit cost). It is dense but not padded; a slightly terser step explanation could still earn the same content, keeping it from a perfect score.

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

Completeness4/5

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

For an 8-param, no-output-schema, side-effecting tool, the description covers mode selection, prerequisites, ordering rules, credit impact and identity/certificate constraints. The main residual gap is that it says nothing about what the created assignment returns (IDs, status), which the absence of an output schema leaves unaddressed.

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 75% and the schema already documents method, entries, verification_method and notification_methods in depth. The description still adds meaning the schema does not: the step contiguity rule ('contiguous starting at 1', all signers must supply it), parallel-vs-sequential signing order semantics, and the virtual/collect compatibility constraint. It stops short of explaining estimate_only and expires_at beyond the schema text, hence not a 5.

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 description opens with a specific verb and resource ('Request signatures on a document') and immediately distinguishes its two modes (virtual vs collect) with the exact conditions that select each. It is clearly separable from siblings like assinafy_send_pdf_for_signature and assinafy_place_fields 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?

It gives explicit when-to-use rules: virtual for field-less signing, collect for placing fields on specific pages, with the required document states for each. It also routes the agent to sibling tools for inputs (assinafy_list_signers, assinafy_create_signer, assinafy_get_document) and warns to pre-check for existing assignments before spending credits.

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

All Assinafy MCP Server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?