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.

Related MCP server: eSignatures MCP Server

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.

No ChatGPT Work, o servidor também pode avisar o ChatGPT quando o status de um documento monitorado muda ou quando ele é certificado, por meio do MCP Events. Peça ao ChatGPT para acompanhar um documento; ele cria e renova a assinatura sozinho.

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 ferramentas 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

Enviar para assinatura

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

Gerenciar contatos

Acompanhar pendências

Baixar, verificar e limpar

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.

Cartões no Claude e no ChatGPT

Os demais clientes, incluindo o Claude Code, recebem as mesmas informações em texto. Veja os cartões visuais.

O modelo escolhe a ferramenta. 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 27 ferramentas, uma por operação. Seu assistente escolhe as ferramentas 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_list_documents 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_list_documents com:

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

Identificado o documento correto, chame assinafy_get_document:

{
  "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 é:

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_get_document 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_list_document_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_list_whatsapp_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_resend_notification com:

{
  "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_set_assignment_expiration com os IDs dos detalhes atuais do documento e um timestamp RFC 3339 explícito:

{
  "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_list_signers ou assinafy_get_signer. assinafy_update_signer aceita full_name, email, whatsapp_phone_number e government_id. Salve CPF/CNPJ somente com autorização para verificação por certificado ou biometria. 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_send_pdf_for_signature:

{
  "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. Uma chamada aceita no máximo 10 signatários e tem prazo total de max_wait_secs mais dois minutos.

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

1. assinafy_upload_document 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_get_document confere a prontidão e fornece IDs e dimensões de página. Use assinafy_rename_document com document_id e name enquanto renomear é permitido: antes de existir um assignment, em uploaded ou metadata_ready.

3. assinafy_list_signers / assinafy_create_signer 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_create_assignment 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_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"
}

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, DigitalCertificate e IdDocumentFaceMatchBasic; cada signatário usa exatamente um canal de notificação Email/WhatsApp compatível. WhatsApp exige o contato e o plano adequados. Certificado e biometria exigem o recurso habilitado na conta e CPF/CNPJ salvo no contato por uma atualização autorizada de government_id. Biometria exige CPF válido. A Assinafy valida a elegibilidade e os recursos atuais no envio.

Use estimate_only: true nas ferramentas de assinatura para consultar custos e saldos antes do envio. A prévia de um PDF novo envia e preserva o documento; reutilize seu ID com assinafy_create_assignment para solicitar assinaturas. As outras prévias não criam registros nem enviam mensagens. Veja prévias de custo e os payloads completos de requisição e resposta. Reutilize a autorização do usuário para a ação pedida; pergunte apenas pelas 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_list_fields (opcionalmente include_standard: true) e assinafy_get_field 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_page.

Validar valores de campo

Use assinafy_list_fields e assinafy_get_field para inspecionar as definições e valide os valores propostos com assinafy_validate_fields:

{
  "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_list_templates e leia seus papéis, páginas e campos de editor. assinafy_get_template 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_list_templates, 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_list_fields / assinafy_get_field. 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_create_document_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. Notificação ou verificação por WhatsApp, certificado ou biometria exigem um id de signatário; prepare antes o contato autorizado. Cada entrada de template aceita no máximo um canal: Email ou Whatsapp. O servidor valida todas as entradas e a ordem completa antes de criar contatos. Se uma entrada usar step, todas usam; as etapas são contíguas desde 1 e quem assina com certificado fica sozinho na etapa. A Assinafy ainda valida os papéis, então uma falha posterior pode deixar contatos recém-criados.

A chamada aceita nome personalizado, mensagem, expiração, tags (nomes de tag, mesclados com os padrões do template) e editor_fields com {field_id,value}. A criação pode enviar convites e consome a franquia de documentos do workspace; use o documento e os destinatários autorizados pelo usuário. Guarde o ID do documento retornado e chame assinafy_get_document para o assignment e as conferências de status seguintes.

Os argumentos de criação ficam assim (substitua pelos IDs descobertos no template e no diretório de signatários):

{
  "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": "cliente@example.com",
      "step": 2
    }
  ],
  "editor_fields": [
    {
      "field_id": "ID_DO_CAMPO_NOME",
      "value": "Empresa Exemplo"
    },
    {
      "field_id": "ID_DO_CAMPO_TOTAL",
      "value": "1250.00"
    }
  ]
}

As conferências de status, lembretes, mudanças de expiração e downloads seguintes usam os IDs do documento retornado, como em um PDF enviado.

7. Inspecionar prévias de página

assinafy_download_document_page recebe document_id e um page_id retornado. Devolve os bytes da imagem em base64. Baixe apenas as páginas necessárias.

8. Baixar artefatos assinados e verificar

Concluída a certificação, chame assinafy_download_document com o ID do documento e artifact: "certificated". O resultado traz document_id, o nome do artefato e base64. Decodifique e salve os bytes pelas ferramentas de arquivo do cliente; não imprima um base64 grande na conversa.

A ferramenta também aceita original, certificated, certificate-page, pades e bundle. A disponibilidade do artefato depende do ciclo de vida e do método de assinatura; um artefato indisponível não é um download bem-sucedido. As respostas binárias são limitadas a 64 MiB antes da codificação base64. O base64 é retornado apenas no resultado estruturado, com um resumo curto em texto.

Chame assinafy_verify_document com o hash SHA-1 de assinatura do documento assinado. Use o hash de verificação real fornecido com o documento, não o ID do documento nem um valor inventado. Esta é a única ferramenta que funciona sem conectar: ela consulta um registro público de assinatura e não toca em nada pertencente a um workspace. Informe o is_valid retornado.

As pessoas concluem assinaturas, recusas e verificações exigidas dentro da Assinafy. Esses endpoints usam o código de acesso do signatário, fora da concessão OAuth2 do workspace. Estas ferramentas não aceitam termos, não digitam códigos de verificação e não assinam no lugar de ninguém.

9. Retomar uma operação parcial ou excluir

Um envio de várias etapas pode falhar depois do upload. O erro preserva o ID do documento criado. Inspecione esse documento e suas atividades antes de continuar:

• Um assignment existente indica que a solicitação de assinatura pode já ter dado certo. Continue acompanhando; não crie outro assignment nem reenvie às cegas.

• Um documento preparado sem assignment continua por assinafy_create_assignment com os IDs de signatário confirmados. Não precisa de novo upload. Confira o status de processamento antes de posicionar campos.

• Se pedirem limpeza, use assinafy_delete_document apenas quando o estado atual do documento permitir. Essa ação precisa de autorização do usuário.

Nenhuma requisição de escrita é repetida automaticamente pelo servidor MCP.

Erros e reconexão

Veja erros e recuperação e a referência de entradas.

Verificar a conexão

Atualize a lista de ferramentas no cliente após reconectar ou atualizar o cliente. Também é possível consultar o catálogo disponível sem entrar:

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"}'

Se o login informar invalid_target, invalid_client ou falta de metadados do recurso, confira se a URL é exatamente https://mcp.assinafy.com.br/mcp e se o cliente está atualizado. Se persistir, contate o suporte da Assinafy com o nome e a versão do cliente e a mensagem de erro. Não inclua tokens ou credenciais.

Prévias de custo e verificação de identidade

Use estimate_only: true nas ferramentas existentes de PDF, assignment, template e lembrete para consultar saldos e detalhamento de custos antes do envio. A prévia de PDF envia e preserva o documento; reutilize esse ID para solicitar assinaturas. As demais prévias não criam registros nem enviam mensagens. Estimativas não reservam créditos; a Assinafy verifica os recursos novamente no envio. Veja o fluxo e os payloads.

A verificação biométrica usa IdDocumentFaceMatchBasic nas configurações de signatário do assignment ou template. Salve antes um CPF autorizado em government_id no contato. O signatário conclui as fotos de identificação e a prova de vida na Assinafy. A revisão manual ocorre lá pela conta responsável; as ferramentas de documento mostram InReview e pending_identity_review. Certificados ICP-Brasil A1/A3 usam DigitalCertificate; cada signatário com certificado fica sozinho na etapa de assinatura.

Configure webhooks de conta na Assinafy, independentemente de MCP Events. Planos pagos aceitam até três endpoints. Salve o segredo retornado na criação com assinatura habilitada; aplicativos OAuth não podem recuperá-lo nem rotacioná-lo depois. O catálogo continua com exatamente 27 ferramentas, sem ferramentas separadas para custos, biometria ou administração de webhooks. Veja verificação e assinatura de webhooks.