Assinafy

Assinafy MCP 客户端指南

葡萄牙语 · Read in English

将 Assinafy 连接到你的助手，以准备和发送文档、跟踪签名、发送提醒并下载已签署的副本。

将 https://mcp.assinafy.com.br/mcp 用作服务 URL。登录 Assinafy，选择一个工作区并批准请求的权限。你无需创建 OAuth 应用，也无需提供 client ID、client secret、API 密钥或工作区请求头。

你可以在登录前连接并查看目录。当工具需要访问你的工作区时，系统会请求授权。

Codex

codex mcp add assinafy --url https://mcp.assinafy.com.br/mcp
codex mcp login assinafy

在浏览器中完成登录，选择工作区并批准权限。请参阅 Codex MCP 文档。

Claude Code

claude mcp add --transport http assinafy https://mcp.assinafy.com.br/mcp
claude mcp login assinafy

你也可以在 Claude Code 中打开 /mcp，以通过 Assinafy 进行身份验证。在浏览器中完成登录并选择工作区。请参阅 Claude Code MCP 文档。

Claude 远程连接器

在 Claude 的连接器设置中，添加一个名为 Assinafy 的自定义远程连接器，URL 为 https://mcp.assinafy.com.br/mcp，然后连接并完成授权。同一设备授权（CIMD）可用时，请将可选 OAuth 凭据留空。自定义连接器是否可用取决于套餐和组织设置。命令行注册适用于 Claude Code；托管连接器需要公开的 HTTPS URL。

请参阅 Claude 连接器身份验证。

ChatGPT

使用 OAuth 和 Assinafy URL 配置远程 MCP 连接。如果有注册选项，请选择 CIMD，将可选凭据留空，然后完成 Assinafy 登录和工作区选择。请参阅 ChatGPT 身份验证。

在 ChatGPT Work 中，当受监控文档的状态发生变化或文档获得认证时，服务端还可以通过 MCP Events 通知 ChatGPT。请让 ChatGPT 监控某份文档；它会自行创建并续订订阅。

VS Code / GitHub Copilot Chat

将以下条目添加到 VS Code MCP 配置中：

{
  "servers": {
    "assinafy": {
      "type": "http",
      "url": "https://mcp.assinafy.com.br/mcp"
    }
  }
}

启动服务端并在浏览器中完成授权。如果已公布 CIMD，VS Code 会选择它；当工具需要额外范围时，也会请求这些范围。请参阅 VS Code 身份验证支持 和 MCP 配置。

工作区与权限

一个连接会授权一个工作区。账户范围的工具会自动发现该账户。account_id 参数可以重复指定该账户，但不会选择其他账户。每个额外的工作区都需要单独连接。切勿将 API 密钥、OAuth 令牌或任何其他凭据放入提示词、工具参数或 _meta；携带这些内容的请求会被拒绝。

你需要配置 MCP URL。元数据会为整个工具目录声明 account:read documents:read documents:write templates:read templates:write 这些权限。默认情况下，登录会请求完整的权限集，通过一次授权涵盖所有工具。你可以在客户端或授权页面选择较少的权限，并使用这些权限所允许的工具。API 要求生成已保存的模板文档时具有 templates:write 权限，验证字段值时具有 documents:write 权限。如果客户端使用刷新令牌进行后台访问，请请求 offline_access。

缺少权限时，会在启动流程前返回 HTTP 403 insufficient_scope，并列出需要批准的权限。请授权所请求的权限以及已授予的权限，然后重试。其他故障可能会在操作启动后中断操作；重试前，请检查是否保留了任何 document_id。

对于 Codex，请明确授权完整的文档和模板流程：

codex mcp login assinafy --scopes account:read,documents:read,documents:write,templates:read,templates:write,offline_access

对于有意设置为只读的文档连接，请选择：

codex mcp login assinafy --scopes account:read,documents:read,offline_access

客户端会保存并续期令牌。如果授权过期或被撤销，请让客户端续期，或通过 Assinafy 重新连接。使用 offline_access 时，每次续期都会返回一个新的刷新令牌，有效期再延长 30 天；只有连续 30 天未续期时，连接才会过期，此时需要重新连接。 切勿将令牌粘贴到对话或工具参数中。

你可以提出的请求

用自然语言与助手交谈。它会选择合适的工具、帮你查找姓名，并且只会在存在歧义时向你确认。以下姓名、电子邮件和日期均为示例。

跟踪文档

你说	会发生什么
“还有哪些文档等待签名？”	列出状态为 pending_signature 的文档，按最新时间优先排列
“所有人都签署 Acme 的服务合同了吗？”	找到该文档，并告知已签署和待签署的人
“还有谁没有签署 NDA？他们是什么时候收到邀请的？”	查看每位待签署者的签署步骤和邀请记录
“本周租赁合同发生了什么？”	显示文档的事件时间线
“Carlos 的 WhatsApp 邀请送达了吗？”	查看该请求的 WhatsApp 送达记录

发送以供签署

你说	会发生什么
“将 contrato.pdf 发送给 Ana Lima（[email protected]）签署。”	发送 PDF，等待处理完成，然后通过电子邮件发送邀请
“上传 proposta.pdf，但暂时不要发送。将它命名为 Proposta v2。”	上传并重命名文件；不会通知任何人
“先让 Ana，再让 Bruno 签署 Proposta v2。”	在已上传的文档中请求签名，并设置签署顺序
“发送时附上消息‘请在星期五前签署’，并设置 6 月 30 日为有效期截止日期。”	添加邀请消息和到期日期
“将租赁合同发送给 Ana，并抄送 [email protected]，不要请求签名。”	保存联系人并发送，且仅将其设为抄送收件人

如需发送文件，请附上文件或指明文件所在位置。助手会读取文件并发送其内容；服务端不会打开你电脑上的路径。

使用模板

你说	会发生什么
“我们有哪些模板？”	列出已保存的模板及其角色和字段
“使用 NDA 模板发送给 Carla Souza（[email protected]），公司填写 Acme Ltda。”	匹配字段、验证值、填写角色并发送
“123.456.789-09 符合 CPF 字段的格式吗？”	验证该值，不会创建任何内容

管理联系人

你说	会发生什么
“联系人里已经有 Bruno Costa 了吗？”	搜索工作区的签署者
“将 Bruno Costa（[email protected]）添加为联系人。”	创建联系人；不会发送邀请
“将 Carla 的 WhatsApp 号码改为 +55 11 91234-5678。”	更新联系人，并遵守 Assinafy 的验证规则

跟进待办事项

你说	会发生什么
“提醒 Ana 签署服务合同。”	确认她仍未签署，然后发送提醒
“将租赁合同签署者的截止日期设为 7 月 15 日。”	更改到期日期；不会发送提醒

下载、验证和清理

你说	会发生什么
“下载 Acme 合同的已签署副本。”	确认认证已完成，然后下载经过认证的 PDF
“显示合同的第一页。”	下载该页面的预览
“这个签名有效吗？哈希值 3f2a…”	查询公开签名记录；无需登录即可使用
“删除草稿 Proposta v1。”	如果 Assinafy 根据当前状态仍允许删除，就会删除该文档

助手不会代替其他人签名、接受条款或提供验证码，也不会创建或编辑模板。这些操作仍需在 Assinafy 中完成。

对话行为

从用户的目标入手。解析名称并复用已返回的 ID； 不要要求对方了解 API 标识符。收件人、角色或文档存在歧义时，简短提问。明确要求发送、提醒或删除，即已授权执行该操作；不要重复确认。

请求	流程
“把这份 PDF 发给 Ana。”	解析已授权的联系人后，调用 assinafy_send_pdf_for_signature
“使用我们的 NDA 模板。”	查找模板、角色和字段；验证值；调用 assinafy_create_document_from_template
“Ana 已经签署了吗？”	调用 assinafy_list_documents，然后调用 assinafy_get_document；告知待处理事项和当前状态
“提醒 Ana。”	检查 assignment；为她调用 assinafy_resend_notification
“下载已签署的副本。”	检查认证状态和文件；调用 assinafy_download_document，并设置 artifact: "certificated"

Claude 和 ChatGPT 中的卡片

你说	会发生什么
“显示 Acme 合同的状态。”	显示状态卡片：谁已签署、还有谁未签署、到期时间，并提供提醒和更新按钮
“我想在把 NDA 发给 Ana 和 Bruno 之前先审核。”	显示含收件人和验证信息的审核卡片；点击发送之前不会发送任何内容
“我想自己在租赁合同中放置签名字段。”	打开全屏编辑器，可在每一页放置字段，然后发送

其他客户端（包括 Claude Code）会以文本形式收到相同信息。请参阅可视卡片。

模型会选择工具。回复应以通俗语言说明结果，不要暴露不必要的 ID 或 base64。读取和准备操作不会发送邀请。请参阅所有工具及其输入。

文档流程

服务提供 27 个工具，每个操作对应一个工具。你的助手会从目录中选择工具；你只需描述想要执行的操作。 输入和示例请参阅工具参考。

flowchart TD
    A[Conectar e autorizar um workspace] --> B{Origem do documento}
    B --> C[Localizar um documento existente]
    B --> D[Enviar um PDF ou usar um template]
    D --> E[Preparar e solicitar assinaturas]
    C --> F[Ler status, assignment, signatários e atividades]
    E --> F
    F --> G{Estado atual}
    G -->|Pendente| H[Conferir entrega, lembrar ou atualizar expiração]
    H --> F
    G -->|Certificando| F
    G -->|Certificado| I[Baixar e verificar]
    G -->|Falha ou recusa| J[Inspecionar e escolher a recuperação]

1. 查找文档并检查其状态

使用 assinafy_list_documents，并传入 search、status、page 和 per_page。它 也接受 sort，值为 name 或 updated_at；可选地在前面加上 - 以反转顺序。页码 从 1 开始，每页最多返回 100 条记录；请根据返回的分页 meta 继续查询，不要假设第一页包含所有文档。

例如，调用 assinafy_list_documents，并传入：

{
  "status": "pending_signature",
  "sort": "-updated_at",
  "page": 1,
  "per_page": 25
}

找到正确的文档后，调用 assinafy_get_document：

{
  "document_id": "DOCUMENT_ID"
}

后续所有调用都使用 Assinafy 返回的 ID。不要编造 ID，也不要根据文档 ID 推断 assignment ID。文档详情会显示当前 status、is_closed、assignment、签署人记录、页面 ID、文件产物，以及 Assinafy 提供的任何拒绝原因。文档记录的生命周期如下：

状态	下一步
uploading、uploaded、metadata_processing	处理尚未完成。稍后再检查；collect assignments 需要页面元数据准备就绪。
metadata_ready	检查或重命名 PDF，并准备签署请求。
pending_signature	检查待签署人、签署顺序、送达历史和过期时间。
pending_identity_review	所有签名均已完成；在认证前，先在 Assinafy 完成身份人工审核。
certificating	可能已收齐所有签名，但最终文件产物仍在生成。
certificated	下载可用的已签署文件产物。此状态无法通过记录的 API 删除。
expired	检查 assignment，并决定是否更新过期时间。Assinafy 会验证是否允许更新。
rejected_by_signer、rejected_by_user	阅读拒绝详情，并与用户确定下一步。发送提醒无法撤销拒绝。
failed	阅读文档活动和错误后，再选择恢复方式。

状态检查是单独的读取操作，并非事件订阅。用户要求跟踪文档时，请使用有限次数的查询；到达终止状态或约定的时间后停止。

2. 检查进度和送达情况

使用 assinafy_get_document 确认实际有哪些人仍待处理。assignment 会提供 id、signers[].id、completed、step、notified、notification_history，以及可用时的签署 URL。缺少可选字段表示 API 未提供该信息。等待前一个步骤的签署人不一定是送达失败。

调用 assinafy_list_document_activities 并传入 document_id，获取事件时间线，其中包含每个事件的日期和 payload。检查 notification_history 中是否有已发送或失败的事件及错误详情。若要查看 WhatsApp 送达情况，请调用 assinafy_list_whatsapp_notifications 并传入 document_id 和 assignment_id。请将返回的链接和访问代码视为敏感信息，仅分享给获授权的收件人。

进度达到 100% 并不能证明已认证的 PDF 已准备就绪。 下载前，请检查生命周期状态和文件产物是否可用。

3. 重新发送提醒

再次读取文档，找出待签署人和当前步骤，并确认用户的指示授权发送该提醒。OAuth 范围授权的是对某项操作的访问权限；它们不会替用户选择接收者。提醒会消耗通知额度。用户明确要求发送提醒，即已授权该操作；只有接收者或操作存在歧义时才询问。调用 assinafy_resend_notification，并提供：

{
  "document_id": "DOCUMENT_ID",
  "assignment_id": "ASSIGNMENT_ID",
  "signer_id": "SIGNER_ID"
}

is_sent: true 表示重发结果；不代表此人已签署。之后读取送达记录和进度。不要仅仅因为进度没有变化就反复重发。成功发送后也可能收到不确定的响应；再次尝试前先检查活动记录。遵守速率限制和重试间隔。

4. 更新过期时间或更正接收者数据

使用 assinafy_set_assignment_expiration，并提供文档当前详情中的 ID 和明确的 RFC 3339 时间戳：

{
  "document_id": "DOCUMENT_ID",
  "assignment_id": "ASSIGNMENT_ID",
  "expires_at": "2027-01-31T23:59:59-03:00"
}

选择用户实际要求的日期和时区；示例仅展示格式。读取更新后的 assignment，以确认最终日期。不要假设更新过期时间也会发送新邀请。

通过 assinafy_list_signers 或 assinafy_get_signer 查找联系人。assinafy_update_signer 接受 full_name、email、whatsapp_phone_number 和 government_id。仅在获准进行证书或生物识别验证时保存 CPF/CNPJ。联系人在整个 workspace 中共享，因此应用更改前请先检查拟进行的修改。Assinafy 会阻止更改进行中文档中已验证的渠道。更改未经验证的渠道会使旧链接和代码失效；成功更正后，使用获授权的重发操作发送新链接。保留并告知用户 Assinafy 的拒绝结果。

5. 准备并发送新 PDF

对于常见的电子邮件流程，请调用 assinafy_send_pdf_for_signature：

{
  "file_name": "contrato.pdf",
  "file_base64": "BYTES_DO_PDF_EM_BASE64",
  "signers": [
    {
      "full_name": "Pessoa de Exemplo",
      "email": "[email protected]"
    }
  ],
  "message": "Revise e assine o documento",
  "max_wait_secs": 30
}

该地址是虚构的。实际任务中，请仅提供获授权的收件人。该工具会发送 PDF、等待处理、创建或复用电子邮件联系人，并启动带验证和电子邮件邀请的 assignment。请保存结果中的 document.id、assignment.id 和 signer_ids。 一次调用最多接受 10 位签署者，总时限为 max_wait_secs 加两分钟。

如需在发送前进行准备，请按以下顺序操作：

1. assinafy_upload_document 接受 file_name 和 file_base64，返回文档但不会发送邀请。PDF 最多可有 25 MiB 和 2,000 页；页数限制由 Assinafy 设定。MCP 服务不会打开本地文件路径。
2. assinafy_get_document 用于确认就绪状态，并提供 ID 和页面尺寸。在允许重命名时，使用 assinafy_rename_document，并提供 document_id 和 name：必须在 assignment 创建之前，且文档状态为 uploaded 或 metadata_ready。
3. assinafy_list_signers / assinafy_create_signer 用于获取签署者 ID。单独创建联系人不会发送签署请求。单独创建联系人可能返回冲突；重试前请先查找现有联系人。
4. assinafy_create_assignment 使用签署者 ID，启动对现有文档的签署流程。此操作会消耗工作区的文档配额；使用 WhatsApp 时，还会消耗通知额度——请仅使用用户授权的收件人和操作。请保存返回的 assignment 和身份信息，以便后续跟进。

assinafy_create_assignment 的参数示例：

{
  "document_id": "DOCUMENT_ID",
  "method": "virtual",
  "signers": [
    {
      "id": "SIGNER_ID",
      "verification_method": "Email",
      "notification_methods": [
        "Email"
      ],
      "step": 1
    }
  ],
  "message": "Revise e assine o documento"
}

Assignment 工具接受 virtual 和 collect、可选的 copy_receivers（签署者 ID）、message、expires_at 以及通过 step 指定的签署顺序。验证方式包括 Email、Whatsapp、DigitalCertificate 和 IdDocumentFaceMatchBasic；每位签署者必须且只能使用一个兼容的 Email/WhatsApp 通知渠道。使用 WhatsApp 需要适用的联系人和套餐。证书和生物识别需要账户启用相应功能，并且联系人中已通过授权更新保存 CPF/CNPJ 至 government_id。生物识别需要有效的 CPF。Assinafy 会在发送时验证资格和当前可用功能。

DigitalCertificate 要求 method: "virtual"。调用 collect 时，会在估算或发送前被拒绝，并返回 digital_certificate_requires_virtual。

请在签署工具中使用 estimate_only: true，以便在发送前查询费用和余额。新 PDF 的预览会发送并保留文档；请复用其 ID，通过 assinafy_create_assignment 请求签署。其他预览不会创建记录或发送消息。请参阅费用预览和完整请求与响应 payload。请沿用用户对所请求操作的授权；仅在缺少文档或收件人选择时询问。不要仅仅因为进度似乎停滞而重复调用。

对于有序签署，如果某位签署者指定了 step，则所有签署者都必须指定；数值必须从 1 开始连续递增。同一阶段的人员并行签署。使用数字证书的签署者必须独占一个阶段。

对于 collect，请等待状态变为 metadata_ready。使用 assinafy_list_fields（可选 include_standard: true）和 assinafy_get_field 获取字段定义。传入包含 page_id 和 fields[] 的 entries[]；每个定位项都包含 signer_id、field_id 和带有 left、top、width、height 与 fontSize 的 display_settings。坐标使用页面图像在 150 DPI 下的像素。若定位超出所选页面，服务会在创建 assignment 前拒绝。页面预览可通过 assinafy_download_document_page 获取。

验证字段值

使用 assinafy_list_fields 和 assinafy_get_field 检查定义， 并使用 assinafy_validate_fields 验证拟议值：

{
  "values": [
    {
      "field_id": "ID_DO_CAMPO_NOME",
      "value": "Empresa Exemplo"
    },
    {
      "field_id": "ID_DO_CAMPO_TOTAL",
      "value": "1250.00"
    }
  ]
}

MCP 会将请求正文中的 values 转换为 API 的 JSON 数组。验证不会创建文档 或发送邀请。请检查每个结果中的 success 和 error_message；HTTP 请求成功 也可能报告值无效。带有前导零的标识符请保留为文本。模板的 editor_fields[].value 始终接收字符串，即使该值表示数字或日期也是如此。

6. 根据模板生成文档

使用 assinafy_list_templates 并查看其角色、页面和编辑器字段。 在环境支持此兼容路由的情况下，assinafy_get_template 可直接查询模板。如果 无法使用单独查询路由，则列表响应是文档化的数据来源。

对于“在服务合同模板中填写 customer_name 和 contract_total”这样的请求， 请先解析字段名称，再创建任何内容：

1. 在 assinafy_list_templates 中选择请求的模板，按页获取数据，并检查其 处理状态、roles 和 pages[].fields。
2. 将请求中的名称与定位项的 label 或 assinafy_list_fields / assinafy_get_field 返回的定义对应起来。将定义的 id 与定位项的 field_id 关联，并确认定位项的 role_id 对应模板的编辑角色。仅填写该 模板中已配置的字段。
3. 在 editor_fields 中使用定位项的 field_id，而不是定位项的 id 或标签。字段名称可配置；它们不是工具参数名称。客户端会根据元数据完成 这一映射；服务端接受 ID。
4. 如果名称缺失或含糊，请用户指出所需字段。不要猜测。具有相同 field_id 的 重复定位项只接收一个值；API 不支持在此请求中按定位项分别设置值。
5. 在获准创建之前，验证拟填入的值，并为模板中的每个角色解析一位签署人。

模板创建以及布局和角色编辑仅在内部 API 中有文档说明，此服务端不提供这些 功能。使用公开的模板文档工作流之前，请先在 Assinafy 中配置已保存的模板。

assinafy_create_document_from_template 会填写所有角色。每个条目都包含现有 签署人的 id，或 full_name 和 email，服务端会据此创建或复用签署人； 每个条目只能选其中一种，不能同时提供，因此一次调用可以同时使用目录中的签署人 和新联系人。条目还可按文档说明接受 verification_method、 notification_methods 和 step。通过 email 解析的条目使用 Email 验证和 通知。通过 WhatsApp、证书或生物识别进行通知或验证时，必须提供签署人的 id；请提前准备好已获授权的联系人。每个模板条目最多接受一个渠道：Email 或 Whatsapp。服务端会在创建联系人之前验证所有条目和完整顺序。如果某个条目 使用 step，则所有条目都必须使用；步骤从 1 开始连续排列，使用证书签署的人 必须单独占一个步骤。Assinafy 仍会验证角色，因此后续失败可能会留下新创建的 联系人。

包含已定位字段的模板使用 collect，不接受 DigitalCertificate。服务端会检查 使用证书的模板，并在估算费用、创建联系人、生成文档或发送邀请之前返回 digital_certificate_requires_virtual。

调用接受自定义名称、消息、过期时间、tags（标签名称，与模板默认标签 合并）以及包含 {field_id,value} 的 editor_fields。创建操作可能会发送邀请， 并消耗工作区的文档配额；请使用用户授权的文档和收件人。保存返回的文档 ID， 并调用 assinafy_get_document 进行后续分配和状态检查。

创建参数如下（请替换为从模板和签署人目录中查到的 ID）：

{
  "template_id": "TEMPLATE_ID",
  "name": "Contrato de serviço.pdf",
  "signers": [
    {
      "role_id": "ID_DO_PAPEL_EDITOR",
      "id": "ID_DO_SIGNATARIO_PREPARADOR",
      "step": 1
    },
    {
      "role_id": "ID_DO_PAPEL_CLIENTE",
      "full_name": "Cliente Exemplo",
      "email": "[email protected]",
      "step": 2
    }
  ],
  "editor_fields": [
    {
      "field_id": "ID_DO_CAMPO_NOME",
      "value": "Empresa Exemplo"
    },
    {
      "field_id": "ID_DO_CAMPO_TOTAL",
      "value": "1250.00"
    }
  ]
}

后续的状态检查、提醒、过期时间变更和下载都使用返回的文档 ID，与已发送 PDF 的处理方式相同。

7. 检查页面预览

assinafy_download_document_page 接受 document_id 和返回的 page_id。 它会以 base64 格式返回图像字节。仅下载必要的页面。

8. 下载已签名的文件并验证

签署完成后，使用文档 ID 和 artifact: "certificated" 调用 assinafy_download_document。结果包含 document_id、文件名称和 base64。使用客户端的文件工具解码并保存字节；不要在对话中打印大段 base64。

该工具还接受 original、certificated、certificate-page、pades 和 bundle。文件是否可用取决于生命周期和签名方式；文件不可用不代表下载成功。二进制响应在进行 base64 编码前限制为 64 MiB。 base64 仅在结构化结果中返回，文本摘要则较短。

使用已签名文档的签名 SHA-1 哈希调用 assinafy_verify_document。请使用文档提供的实际验证哈希，不要使用文档 ID 或编造的值。这是唯一无需连接即可使用的工具：它会查询公开签名记录，不会访问任何工作区内容。请报告返回的 is_valid。

用户在 Assinafy 中完成签名、拒绝和所需验证。这些端点使用签署人的访问代码，不属于工作区 OAuth2 授权范围。这些工具不会接受条款、输入验证码，也不会代替任何人签名。

9. 恢复部分操作或删除

多阶段提交可能在上传后失败。错误会保留已创建文档的 ID。继续操作前，请检查该文档及其活动：

• 已存在的 assignment 表明签名请求可能已成功。请继续跟进；不要创建另一个 assignment，也不要盲目重新提交。
• 已准备好但没有 assignment 的文档，可使用已确认的签署人 ID 调用 assinafy_create_assignment 继续操作。无需重新上传。设置字段前，请检查处理状态。
• 如果用户要求清理，只有在文档当前状态允许时，才能使用 assinafy_delete_document。此操作需要用户授权。

MCP 服务不会自动重试任何写入请求。

错误和重新连接

结果	客户端操作
HTTP 401	让客户端续订授权，或通过 Assinafy 同意流程重新连接。
HTTP 403，且包含 insufficient_scope	授权所请求的范围，并保留已授予的范围；同意后重试。
工具错误指出缺少某个范围	Assinafy 拒绝了调用。请重新连接并添加所指出的范围；未获得新同意就重试会再次失败。多阶段工具可能已完成前面的步骤；请检查错误中是否保留了 document_id，并从该步骤继续。
工具结果包含 isError: true	阅读 Assinafy 错误，并在重试写入操作前检查当前文档。
联系人无效、assignment 已过期或文件不可用	修正请求，或等待生命周期达到所需状态。
速率限制或网络响应不确定	遵守重试等待时间；重试写入操作前，检查状态和交付历史。
HTTP 429	Assinafy 正在限制授权检查；请遵守 Retry-After。
身份验证时出现 HTTP 503	服务暂时不可用。请稍后重试；如果问题持续存在，请联系 Assinafy 支持。
卡片显示“无法完成”	此次点击没有更改任何内容；请通过聊天继续操作，聊天会先查询当前状态。

请参阅错误和恢复以及输入参考。

验证连接

重新连接或更新客户端后，请刷新客户端中的工具列表。 也可以在不登录的情况下查询可用目录：

curl -sS -X POST https://mcp.assinafy.com.br/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

如果登录时提示 invalid_target、invalid_client 或缺少资源元数据，请 确认 URL 是否精确为 https://mcp.assinafy.com.br/mcp，以及客户端是否 已更新。如果问题仍然存在，请联系 Assinafy 支持，并提供客户端名称、 版本和错误消息。请勿提供令牌或凭据。

成本预估与身份验证

对现有的 PDF、assignment、template 和提醒工具使用 estimate_only: true， 以便在发送前查询余额和成本明细。PDF 预估会上传并保留文档；请重复使用 该 ID 来请求签名。其他预估不会创建记录或发送消息。 预估不会预留额度；Assinafy 会在发送时重新检查资源。请参阅签署流程和负载。

生物识别验证使用 assignment 或 template 的签署人设置中的 IdDocumentFaceMatchBasic。请先在联系人 government_id 中保存经授权的 CPF。签署人需在 Assinafy 完成人脸证件照和活体检测。人工审核由负责账户 在 Assinafy 中进行；文档工具会显示 InReview 和 pending_identity_review。 ICP-Brasil A1/A3 证书使用 DigitalCertificate；每位使用证书的签署人 都会单独进入签署步骤。

在 Assinafy 中配置账户 Webhook，此配置独立于 MCP Events。 付费计划最多可接受三个端点。创建时请保存返回的密钥并启用签名； OAuth 应用之后无法找回或轮换该密钥。目录仍恰好包含 27 个工具，不会 单独提供成本、生物识别或 Webhook 管理工具。请参阅验证和 Webhook 签名。