Guia do cliente MCP da Assinafy

Português · Read in English

Conecte a Assinafy ao seu assistente para preparar e enviar documentos, acompanhar assinaturas, enviar lembretes e baixar cópias assinadas.

Use https://mcp.assinafy.com.br/mcp como URL do servidor. Entre na Assinafy, escolha um workspace e aprove as permissões solicitadas. Você não precisa criar um aplicativo OAuth nem informar client ID, client secret, chave de API ou cabeçalho de workspace.

É possível conectar e consultar o catálogo antes de entrar. A autorização é solicitada quando uma ferramenta precisa acessar seu workspace.

Codex

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

Conclua a entrada no navegador, escolha o workspace e aprove as permissões. Veja a documentação MCP do Codex.

Claude Code

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

Você também pode abrir /mcp no Claude Code para autenticar na Assinafy. Conclua a entrada no navegador e escolha seu workspace. Veja a documentação MCP do Claude Code.

Conectores remotos do Claude

Nas configurações de conectores do Claude, adicione um conector remoto personalizado chamado Assinafy com a URL https://mcp.assinafy.com.br/mcp, conecte e conclua o consentimento. Deixe as credenciais OAuth opcionais em branco quando houver CIMD. A disponibilidade de conectores personalizados depende do plano e das configurações da organização. O registro por linha de comando é do Claude Code; um conector hospedado precisa da URL HTTPS pública.

Veja a autenticação de conectores do Claude.

ChatGPT

Configure uma conexão MCP remota com OAuth e a URL da Assinafy. Escolha CIMD se houver uma opção de registro, deixe as credenciais opcionais em branco e conclua a entrada na Assinafy e a seleção de workspace. Veja a autenticação do ChatGPT.

VS Code / GitHub Copilot Chat

Adicione esta entrada à configuração MCP do VS Code:

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

Inicie o servidor e conclua a autorização no navegador. O VS Code escolhe CIMD quando anunciado e sabe pedir escopos adicionais quando uma ferramenta precisa. Veja o suporte a autenticação do VS Code e a configuração MCP.

Workspaces e permissões

Uma conexão autoriza um workspace. As ferramentas com escopo de conta descobrem essa conta automaticamente. O argumento account_id pode repeti-la, mas não seleciona outra. Conecte cada workspace adicional separadamente. Nunca coloque chaves de API, tokens OAuth ou qualquer outra credencial em prompts, argumentos de ferramenta ou _meta; requisições que os carregam são recusadas.

Você configura a URL do MCP. Os metadados anunciam account:read documents:read documents:write templates:read templates:write para todo o catálogo. O login pede o conjunto completo por padrão, cobrindo todas as ferramentas com um consentimento. Você pode escolher menos escopos no cliente ou na tela de consentimento e usar as ações permitidas por eles. A API exige templates:write para gerar um documento de template salvo, e documents:write para validar valores de campos. Peça offline_access quando o cliente usar refresh tokens para acesso em segundo plano.

Uma permissão ausente retorna HTTP 403 insufficient_scope, com os escopos a aprovar, antes de iniciar o fluxo. Autorize as permissões solicitadas somadas às já concedidas e tente novamente. Outras falhas podem interromper uma operação depois de iniciada; inspecione qualquer document_id preservado antes de repetir a operação.

Para o Codex, autorize explicitamente o fluxo completo de documentos e templates:

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

Para uma conexão de documentos intencionalmente somente leitura, escolha:

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

Seu cliente guarda e renova os tokens. Se uma concessão expirar ou for revogada, deixe o cliente renová-la ou reconecte pela Assinafy. Com offline_access, cada renovação devolve um novo refresh token com mais 30 dias de validade; a conexão só expira após 30 dias sem renovação, e então é preciso reconectar. Nunca cole tokens na conversa ou nos argumentos das ferramentas.

O que você pode pedir

Converse com o assistente em linguagem natural. Ele escolhe a ferramenta certa, localiza nomes por você e só confirma o que for ambíguo. Nomes, e-mails e datas abaixo são exemplos.

Acompanhar documentos

Você diz	O que acontece
“Quais documentos ainda aguardam assinatura?”	Lista os documentos em pending_signature, mais recentes primeiro
“Todo mundo já assinou o contrato de serviços da Acme?”	Encontra o documento e informa quem assinou e quem falta
“Quem ainda não assinou o NDA e quando foi convidado?”	Lê a etapa e o histórico de convites de cada signatário pendente
“O que aconteceu com o contrato de locação esta semana?”	Mostra a linha do tempo de eventos do documento
“O convite por WhatsApp para o Carlos chegou?”	Lê o histórico de entrega por WhatsApp da solicitação

Enviar para assinatura

Você diz	O que acontece
“Envie contrato.pdf para Ana Lima, ana@example.com, assinar.”	Envia o PDF, aguarda o processamento e manda o convite por e-mail
“Suba proposta.pdf mas não envie ainda. Chame de Proposta v2.”	Envia e renomeia o arquivo; ninguém é notificado
“Envie a Proposta v2 primeiro para a Ana e depois para o Bruno.”	Solicita assinaturas no documento já enviado, com ordem de assinatura
“Envie com a mensagem ‘Por favor, assine até sexta’ e validade até 30 de junho.”	Inclui a mensagem do convite e a data de expiração
“Envie a locação para a Ana e coloque financeiro@example.com em cópia, sem pedir assinatura.”	Salva o contato e envia com um destinatário apenas em cópia

Para enviar um arquivo, anexe-o ou indique onde ele está. O assistente lê o arquivo e envia o conteúdo; o servidor nunca abre caminhos do seu computador.

Usar modelos

Você diz	O que acontece
“Quais modelos temos?”	Lista os modelos salvos com papéis e campos
“Use o modelo de NDA para Carla Souza, carla@example.com, com a empresa Acme Ltda.”	Associa o campo, valida o valor, preenche o papel e envia
“123.456.789-09 é válido para o campo CPF?”	Valida o valor sem criar nada

Gerenciar contatos

Você diz	O que acontece
“O Bruno Costa já está nos contatos?”	Pesquisa os signatários do workspace
“Adicione Bruno Costa, bruno@example.com, como contato.”	Cria o contato; nenhum convite é enviado
“Troque o WhatsApp da Carla para +55 11 91234-5678.”	Atualiza o contato, respeitando as regras de verificação da Assinafy

Acompanhar pendências

Você diz	O que acontece
“Lembre a Ana de assinar o contrato de serviços.”	Confirma que ela ainda está pendente e envia um lembrete
“Dê aos signatários da locação prazo até 15 de julho.”	Altera a expiração; nenhum lembrete é enviado

Baixar, verificar e limpar

Você diz	O que acontece
“Baixe a cópia assinada do contrato da Acme.”	Confirma que a certificação terminou e baixa o PDF certificado
“Mostre a primeira página do contrato.”	Baixa uma prévia da página
“Esta assinatura é válida? Hash 3f2a…”	Consulta o registro público de assinatura; funciona sem login
“Exclua o rascunho Proposta v1.”	Exclui o documento se a Assinafy ainda permitir no estado atual

O assistente não assina, não aceita termos nem informa códigos de verificação por outra pessoa, e não cria nem edita modelos. Isso continua na Assinafy.

Comportamento na conversa

Comece pelo objetivo do usuário. Resolva nomes e reutilize os IDs já devolvidos; não peça que a pessoa conheça identificadores da API. Faça uma pergunta curta quando houver ambiguidade de destinatário, papel ou documento. Um pedido explícito para enviar, lembrar ou excluir já autoriza aquela ação; não repita a confirmação.

Pedido	Fluxo
“Envie este PDF para Ana.”	assinafy_request_signatures com action: "from_pdf", após resolver o contato autorizado
“Use nosso template de NDA.”	Localizar template, papéis e campos; validar valores; solicitar com action: "from_template"
“Ana já assinou?”	Localizar o documento e consultar action: "get"; informar pendências e estado atual
“Lembre a Ana.”	Conferir o assignment; chamar assinafy_follow_up_assignment com action: "resend" para ela
“Baixe a cópia assinada.”	Conferir certificação e artefato; baixar com action: "artifact" e artifact: "certificated"

O modelo escolhe a ferramenta e a ação. A resposta deve explicar o resultado em linguagem comum, sem expor IDs ou base64 desnecessários. Leituras e preparação não enviam convites. Consulte todas as ferramentas e entradas.

Fluxo do documento

O servidor oferece 11 ferramentas para 24 operações de documentos. Seu assistente escolhe as ferramentas e ações do catálogo; você descreve o que quer fazer. Consulte a referência de ferramentas para entradas e exemplos.

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. Localizar o documento e conferir seu estado

Use assinafy_find_documents (action: "list") com search, status, page e per_page. Ele também aceita sort, que recebe name ou updated_at, opcionalmente prefixado por - para inverter a ordem. As páginas começam em 1 e trazem no máximo 100 registros; siga o meta de paginação retornado em vez de supor que a primeira página contém todos os documentos.

Por exemplo, chame assinafy_find_documents (action: "list") com:

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

Identificado o documento correto, chame assinafy_find_documents (action: "get"):

{
  "action": "get",
  "document_id": "DOCUMENT_ID"
}

Use os IDs devolvidos pela Assinafy em todas as chamadas seguintes. Não invente IDs nem deduza o ID do assignment a partir do ID do documento. Os detalhes do documento expõem o status atual, is_closed, assignment, os registros de signatários, IDs de página, artefatos e qualquer motivo de recusa informado pela Assinafy. O ciclo de vida documentado é:

Estado	Próximo passo
uploading, uploaded, metadata_processing	O processamento não terminou. Verifique depois; assignments collect precisam dos metadados de página prontos.
metadata_ready	Inspecione ou renomeie o PDF e prepare a solicitação de assinatura.
pending_signature	Inspecione signatários pendentes, ordem de assinatura, histórico de entrega e expiração.
certificating	Todas as assinaturas podem estar presentes enquanto os artefatos finais ainda são gerados.
certificated	Baixe os artefatos assinados disponíveis. Este estado não é excluível pela API documentada.
expired	Inspecione o assignment e decida se atualiza a expiração. A Assinafy valida se a atualização é permitida.
rejected_by_signer, rejected_by_user	Leia os detalhes da recusa e escolha o próximo passo com o usuário. Um lembrete não reverte uma recusa.
failed	Leia as atividades do documento e o erro antes de escolher a recuperação.

As conferências de status são leituras individuais, não assinaturas de eventos. Use consultas com limite quando pedirem para acompanhar um documento; pare em um estado terminal ou no tempo combinado.

2. Inspecionar progresso e entrega

Use assinafy_find_documents (action: "get") para identificar quem realmente está pendente. O assignment traz id, signers[].id, completed, step, notified, notification_history e as URLs de assinatura quando disponíveis. Campos opcionais ausentes significam que a API não forneceu aquela informação. Um signatário aguardando uma etapa anterior não está necessariamente sofrendo falha de entrega.

Chame assinafy_find_documents (action: "activities") com document_id para a linha do tempo dos eventos, incluindo data e payload de cada um. Inspecione notification_history em busca de eventos enviados/falhos e detalhes de erro. Para entrega por WhatsApp, chame assinafy_find_documents (action: "notifications") com document_id e assignment_id. Trate links e códigos de acesso retornados como sensíveis e compartilhe apenas com os destinatários autorizados.

100% de progresso não prova que o PDF certificado está pronto. Confira o estado do ciclo de vida e a disponibilidade do artefato antes de baixá-lo.

3. Reenviar um lembrete

Leia o documento de novo, identifique o signatário pendente e a etapa ativa, e confirme que a instrução do usuário autoriza aquele lembrete. Escopos OAuth autorizam o acesso a uma operação; eles não escolhem um destinatário pelo usuário. Um lembrete consome créditos de notificação. Um pedido explícito de lembrete já autoriza aquela ação; pergunte apenas se o destinatário ou a ação estiverem ambíguos. Chame assinafy_follow_up_assignment (action: "resend") com:

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

is_sent: true informa o resultado do reenvio; não significa que a pessoa assinou. Leia o histórico de entrega e o progresso depois. Não reenvie repetidamente só porque o progresso não mudou. Uma resposta incerta pode vir depois de um envio bem-sucedido; inspecione as atividades antes de tentar de novo. Respeite limites de taxa e o tempo de nova tentativa.

4. Atualizar a expiração ou corrigir dados do destinatário

Use assinafy_follow_up_assignment (action: "set_expiration") com os IDs dos detalhes atuais do documento e um timestamp RFC 3339 explícito:

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

Escolha a data e o fuso realmente pedidos pelo usuário; o exemplo ilustra apenas o formato. Leia o assignment atualizado para confirmar a data resultante. Não suponha que atualizar a expiração também enviou um novo convite.

Encontre contatos por assinafy_find_signers (action: "list") ou assinafy_find_signers (action: "get"). assinafy_save_signer (action: "update") aceita full_name, email, whatsapp_phone_number e government_id. Um contato é compartilhado dentro do workspace, então revise a alteração pretendida antes de aplicá-la. A Assinafy bloqueia mudanças em um canal já verificado em um documento em andamento. Alterar um canal não verificado invalida links e códigos antigos; depois de uma correção bem-sucedida, use um reenvio autorizado para entregar o link novo. Preserve e informe uma recusa da Assinafy.

5. Preparar e enviar um novo PDF

Para o fluxo comum por e-mail, chame assinafy_request_signatures (action: "from_pdf"):

{
  "action": "from_pdf",
  "file_name": "contrato.pdf",
  "file_base64": "BYTES_DO_PDF_EM_BASE64",
  "signers": [
    {
      "full_name": "Pessoa de Exemplo",
      "email": "signer@example.invalid"
    }
  ],
  "message": "Revise e assine o documento",
  "max_wait_secs": 30
}

O endereço é fictício. Informe apenas destinatários autorizados para a tarefa real. A ferramenta envia o PDF, aguarda o processamento, cria ou reutiliza contatos de e-mail e inicia um assignment com verificação e convite por Email. Guarde document.id, assignment.id e signer_ids do resultado.

Para preparar antes de enviar, use esta sequência:

1. assinafy_prepare_document (action: "upload") aceita file_name e file_base64, devolve um documento e não envia convites. PDFs podem ter até 25 MiB e 2.000 páginas; a Assinafy impõe o limite de páginas. O servidor MCP nunca abre um caminho de arquivo local.
2. assinafy_find_documents (action: "get") confere a prontidão e fornece IDs e dimensões de página. Use assinafy_prepare_document (action: "rename") com document_id e name enquanto renomear é permitido: antes de existir um assignment, em uploaded ou metadata_ready.
3. assinafy_find_signers (action: "list") / assinafy_save_signer (action: "create") fornecem os IDs dos signatários. Criar um contato sozinho não envia solicitação de assinatura. A criação avulsa pode retornar conflito; procure o contato existente antes de tentar de novo.
4. assinafy_request_signatures (action: "from_document") inicia a assinatura do documento existente usando os IDs de signatário. Consome a franquia de documentos da workspace e, no WhatsApp, créditos de notificação — use os destinatários e a ação autorizados pelo usuário. Guarde o assignment e as identidades retornadas para o acompanhamento.

Exemplo de argumentos de assinafy_request_signatures (action: "from_document"):

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

A ferramenta de assignment aceita virtual e collect, copy_receivers opcionais (IDs de signatário), message, expires_at e ordem de assinatura por step. Os métodos de verificação são Email, Whatsapp e DigitalCertificate; as notificações usam os canais Email/WhatsApp documentados. WhatsApp exige o contato e a assinatura de plano adequados; assinatura com certificado exige os dados de identidade do signatário e o recurso habilitado na conta. A Assinafy valida esses requisitos. Nenhuma resposta traz custo ou saldo: criar um documento e enviar uma notificação por WhatsApp consomem a franquia de documentos e os créditos de notificação da workspace pelas taxas publicadas, e o saldo restante se consulta no Assinafy, não por este servidor. Reutilize a autorização do usuário para a ação pedida; pergunte apenas por escolhas de documento ou destinatário que ainda faltam. Não repita uma chamada só porque o progresso parece parado.

Na assinatura ordenada, se um signatário informar step, todos precisam informar; os valores devem ser contíguos a partir de 1. Pessoas na mesma etapa assinam em paralelo. Um signatário com certificado digital fica sozinho na etapa dele.

Para collect, aguarde metadata_ready. Use assinafy_check_fields (action: "list") (opcionalmente include_standard: true) e assinafy_check_fields (action: "get") para as definições de campo. Passe entries[] com page_id e fields[]; cada posicionamento contém signer_id, field_id e display_settings com left, top, width, height e fontSize. As coordenadas usam os pixels da imagem da página em 150 DPI. O servidor recusa posicionamentos fora da página escolhida antes de criar o assignment. As prévias de página estão em assinafy_download_document (action: "page").

Validar valores de campo

Use assinafy_check_fields (action: "list") e assinafy_check_fields (action: "get") para inspecionar as definições e valide os valores propostos com assinafy_check_fields (action: "validate"):

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

O MCP converte values no corpo em array JSON da API. A validação não cria documento nem envia convites. Verifique success e error_message de cada resultado; uma requisição HTTP bem-sucedida pode reportar um valor inválido. Mantenha como texto os identificadores com zeros à esquerda. O editor_fields[].value de template sempre recebe uma string, mesmo quando o valor representa número ou data.

6. Gerar um documento a partir de um template

Use assinafy_find_templates (action: "list") e leia seus papéis, páginas e campos de editor. assinafy_find_templates (action: "get") oferece a consulta direta onde o ambiente suporta essa rota de compatibilidade. A resposta da listagem é a fonte documentada quando a rota individual não está disponível.

Para um pedido como “preencha customer_name e contract_total no template de contrato de serviço”, resolva os nomes antes de criar qualquer coisa:

1. Selecione o template pedido em assinafy_find_templates (action: "list"), seguindo a paginação, e inspecione seu status de processamento, roles e pages[].fields.
2. Relacione os nomes pedidos aos label dos posicionamentos ou às definições devolvidas por assinafy_check_fields (action: "list") / assinafy_check_fields (action: "get"). Ligue o id da definição ao field_id do posicionamento e confira o role_id do posicionamento contra o papel de editor do template. Preencha apenas campos já configurados naquele template.
3. Use o field_id do posicionamento em editor_fields — não o id do posicionamento nem seu rótulo. Nomes de campo são configuráveis; eles não são nomes de argumento de ferramenta. O cliente faz esse mapeamento pelos metadados; o servidor aceita IDs.
4. Se os nomes faltarem ou forem ambíguos, peça ao usuário que identifique o campo pretendido. Não adivinhe. Posicionamentos repetidos com o mesmo field_id recebem um único valor; a API não oferece valor por posicionamento nesta requisição.
5. Valide os valores propostos e resolva um signatário por papel do template antes da criação autorizada.

Criação de template e edição de layout e papéis são documentadas apenas na API interna e não são expostas por este servidor. Configure o template salvo na Assinafy antes de usar o fluxo público de documento por template.

assinafy_request_signatures (action: "from_template") preenche todos os papéis. Cada entrada traz o id de um signatário existente ou full_name e email, que o servidor cria ou reutiliza — um ou outro, nunca os dois na mesma entrada, de modo que uma única chamada combina signatários do diretório e contatos novos. As entradas também aceitam verification_method, notification_methods e step conforme documentado. Uma entrada resolvida por email usa verificação e notificação por Email; informar só o método de notificação deixa a Assinafy inferir a verificação correspondente. Cada entrada de template aceita no máximo um canal: Email ou Whatsapp. O servidor valida todas as entradas antes de criar contatos. A Assinafy ainda valida os papéis e a ordem de assinatura, então uma falha posterior pode deixar contatos recém-criados.