Plugin da Assinafy para assistentes de IA

Envie documentos para assinatura eletrônica com validade jurídica no Brasil sem sair do seu assistente de IA. Use um PDF ou um modelo salvo, solicite assinaturas por e-mail, WhatsApp ou certificado digital ICP-Brasil (A1/A3), acompanhe o andamento, lembre os signatários, baixe o PDF certificado e verifique qualquer assinatura.

Este repositório é um plugin, com o seu marketplace, para o Claude (Claude Code, apps do Claude e Cowork), o OpenAI Codex e o ChatGPT, e o VS Code com GitHub Copilot. Ele conecta o seu assistente ao servidor MCP da Assinafy hospedado e adiciona a skill signing, que ensina ao assistente o fluxo de assinatura, as regras de cada canal e o acompanhamento seguro. Você entra com a sua conta Assinafy por OAuth 2.1. Não é preciso chave de API, segredo de cliente nem servidor local.

Instalação
Login
Fluxo completo de assinatura
O que você pode pedir
Métodos de assinatura e custos
Status do documento
Ferramentas
Sem o plugin
Solução de problemas
Segurança e privacidade

Instalação

Claude Code (terminal, app desktop, VS Code, JetBrains)

/plugin marketplace add assinafy/agent-plugin
/plugin install assinafy@assinafy

/plugin install abre os detalhes do plugin; escolha o escopo da instalação (para você, para este repositório ou só para você neste repositório). No terminal, um único comando adiciona o marketplace e instala:

claude plugin install assinafy --marketplace assinafy/agent-plugin   # Claude Code 2.1.292+

Na aba Code do app desktop use + → Plugins → Add plugin; no VS Code digite /plugins. Se o Claude Code pedir, rode /reload-plugins para ativar. O plugin adiciona:

Componente	Nome
Servidor MCP	`assinafy` → `https://mcp.assinafy.com.br/mcp` (Streamable HTTP, OAuth 2.1)
Skill	`assinafy:signing`, carregada automaticamente em tarefas de assinatura ou com `/assinafy:signing`

Atualize com claude plugin update assinafy@assinafy (ou Update now em /plugin); remova com claude plugin uninstall assinafy@assinafy. Sessões na nuvem em claude.ai/code não carregam plugins instalados na sua máquina.

Claude (chat na web, desktop e celular, e Cowork)

Como plugin (skill e conector juntos): vá em Customize → Plugins → Add → Add marketplace, informe assinafy/agent-plugin e adicione Assinafy. Depois abra a aba Connectors do plugin, adicione o conector da Assinafy e clique em Connect para entrar. O plugin fica salvo na sua conta, então também aparece no Cowork e é sincronizado com o Claude Code. Nos planos Team e Enterprise, um Owner pode precisar liberar a origem ou adicionar o conector.

Só como conector (ferramentas sem a skill):

Free, Pro e Max: vá em Customize → Connectors → Add custom connector, informe https://mcp.assinafy.com.br/mcp, deixe vazias as configurações de cliente OAuth (ou escolha Use Claude's published identity) e clique em Add. Depois clique em Connect e entre na Assinafy.
Team e Enterprise: um Owner adiciona o conector em Organization settings → Connectors → Add → Custom com a mesma URL. Cada membro abre Customize → Connectors, encontra a Assinafy e clica em Connect. Se for pedido o tipo de conector, escolha Web.

Nesses apps, status, revisão e posicionamento de campos aparecem como cartões interativos.

Codex

codex plugin marketplace add assinafy/agent-plugin
codex plugin add assinafy@assinafy
codex mcp login assinafy --scopes account:read,documents:read,documents:write,templates:read,templates:write,offline_access

O último comando abre o login da Assinafy. A extensão do Codex para IDE não carrega plugins; nela, adicione o servidor pela URL como em Sem o plugin.

ChatGPT

Adicione um conector MCP remoto com a URL https://mcp.assinafy.com.br/mcp, escolha OAuth, selecione CIMD se for perguntado o tipo de registro e deixe as credenciais de cliente vazias. Depois conecte e entre na Assinafy. Status, revisão e posicionamento de campos aparecem como cartões interativos.

VS Code com GitHub Copilot

Rode Chat: Install Plugin From Source na Command Palette e informe https://github.com/assinafy/agent-plugin, ou adicione o marketplace às configurações:

"chat.plugins.marketplaces": ["assinafy/agent-plugin"]

Os plugins de agente precisam estar ativados (chat.plugins.enabled). O servidor da Assinafy inicia com o plugin; faça o login no navegador quando o VS Code pedir.

Login

Codex, ChatGPT e VS Code fazem o login como indicado na instalação de cada um; os apps do Claude conectam pela aba Connectors do plugin. No Claude Code, faça o login uma vez depois de instalar: abra /mcp, selecione plugin:assinafy:assinafy e siga o pedido de login. O Claude Code também exibe um aviso ao iniciar enquanto o servidor precisar de autenticação. Em um terminal sem navegador, rode claude mcp login --no-browser plugin:assinafy:assinafy e cole a URL de retorno.

sequenceDiagram
    participant U as Você
    participant C as Assistente
    participant M as mcp.assinafy.com.br
    participant A as auth.assinafy.com.br
    C->>M: Chamada de ferramenta sem token
    M-->>C: 401 com metadados do recurso e escopos
    C->>A: Login no navegador (PKCE S256, metadados de cliente)
    U->>A: Entra, escolhe o workspace e aprova as permissões
    A-->>C: Código de autorização
    C->>A: Troca o código por tokens de acesso e de renovação
    C->>M: Chamada com token bearer
    M-->>C: Resultado do workspace aprovado

Uma conexão, um workspace. Para usar outro workspace, escolha Clear authentication em /mcp (ou rode claude mcp logout plugin:assinafy:assinafy) e entre de novo escolhendo-o.
Permissões solicitadas: account:read, documents:read, documents:write, templates:read, templates:write e offline_access. Você pode aprovar menos; ferramentas que precisem de uma permissão ausente retornam 403 insufficient_scope antes de fazer qualquer coisa. Gerar documento a partir de modelo exige templates:write, e validar valores de campos exige documents:write.
Tokens são armazenados com segurança pelo seu assistente e renovados automaticamente. Com offline_access, a conexão só expira após 30 dias sem uso.
Verificar o hash de uma assinatura não exige login.
O login usa o ambiente de produção da Assinafy. Para testes, use um workspace de teste.

Fluxo completo de assinatura

flowchart TD
    A[Conectar workspace] --> B{Origem}
    B -->|PDF novo| C[Enviar PDF]
    B -->|Modelo salvo| D[Escolher modelo, preencher papéis e campos]
    B -->|Documento existente| E[Encontrar documento]
    C --> F[Escolher signatários, canais e ordem]
    E --> F
    D --> G[Solicitação de assinatura enviada]
    F --> R{Revisar antes?}
    R -->|Sim| RV[Resumo ou cartão de revisão] --> G
    R -->|Não| G
    G --> H[Signatários confirmam identidade e assinam]
    H --> I{Todos assinaram?}
    I -->|Pendente| J[Ver entrega, lembrar, prorrogar prazo] --> H
    I -->|Expirado| X[Tentar prorrogar o prazo ou recomeçar]
    I -->|Recusado| K[Ver o motivo; nova solicitação ou excluir]
    I -->|Sim| L[certificating]
    L --> M[certificated]
    M --> N[Baixar PDF certificado]
    N --> O[Verificar hash da assinatura]

1. Prepare o documento

Há três pontos de partida:

Um PDF novo. Anexe o arquivo ou indique onde ele está. O assistente lê o arquivo e envia os bytes; o servidor nunca abre caminhos do seu computador. Limite de 25 MiB depois de decodificado.
- Quer enviar já, por e-mail? Diga isso; uma chamada envia o PDF, aguarda o processamento e dispara os convites (assinafy_send_pdf_for_signature).
- Quer preparar antes? O assistente envia o arquivo (assinafy_upload_document) e pode renomeá-lo enquanto não houver solicitação (assinafy_rename_document).
Um modelo salvo. O assistente lista os modelos com papéis e campos (assinafy_list_templates), associa os valores informados aos campos, valida-os (assinafy_validate_fields) e atribui uma pessoa a cada papel (assinafy_create_document_from_template).
Um documento já na Assinafy. O assistente encontra o documento por nome, signatário ou status (assinafy_list_documents) e confere que ele ainda não tem solicitação.

2. Escolha signatários, canais e ordem

O assistente procura cada pessoa nos contatos do workspace (assinafy_list_signers) ou a cadastra (assinafy_create_signer). Para cada signatário você define:

Como é notificado: e-mail, WhatsApp ou ambos (um canal por signatário ao usar modelo).
Como a identidade é verificada: código por e-mail, código por WhatsApp ou certificado digital ICP-Brasil (A1 ou A3). Veja Métodos de assinatura e custos.
Ordem (opcional): etapa 1, 2, 3… Quem está na mesma etapa assina em paralelo; a etapa seguinte é convidada quando a anterior termina. Quem assina com certificado precisa estar sozinho na sua etapa; com outros signatários, todos recebem etapa.
Destinatários em cópia (opcional): contatos que recebem o documento assinado sem assinar.

Também opcionais: mensagem do convite e data de expiração.

Há dois modos de assinatura:

Virtual (padrão): o signatário assina o documento inteiro; a Assinafy adiciona a página de certificado.
Coleta: campos de assinatura, rubrica, data e preenchimento são posicionados em páginas específicas para cada signatário. Nos apps do Claude e no ChatGPT, assinafy_place_fields abre um editor visual. Nos demais, o assistente monta os posicionamentos a partir do tamanho das páginas e dos IDs dos campos.

3. Revise e envie

Peça ao assistente para mostrar a solicitação antes de enviar. assinafy_review_signature_request lista destinatários, canais e prazo e não envia nada. Nos apps do Claude e no ChatGPT, o botão Enviar do cartão envia exatamente o que foi revisado; nos demais casos, confirme na conversa.

O envio (assinafy_create_assignment) cria a solicitação e notifica os signatários. Uma instrução explícita como "envie para a Ana" já é a sua confirmação; o assistente só pergunta de novo quando um destinatário, documento ou papel do modelo é ambíguo. Convites podem consumir documentos e créditos do seu plano.

4. O que os signatários fazem

Cada signatário, na sua vez:

Recebe o convite por e-mail e/ou WhatsApp, com a sua mensagem.
Abre a página de assinatura da Assinafy e aceita os termos.
Confirma a identidade:
- E-mail: digita o código enviado ao e-mail.
- WhatsApp: digita o código enviado ao WhatsApp.
- Certificado digital: assina com o próprio certificado ICP-Brasil, A1 (arquivo) ou A3 (token ou cartão). O certificado precisa corresponder ao CPF ou CNPJ cadastrado no contato do signatário na Assinafy.
Revisa o documento, preenche os campos atribuídos e assina, ou recusa informando o motivo.

O assistente não assina, não aceita termos nem digita códigos por ninguém. Links de assinatura e códigos nunca aparecem na conversa.

5. Acompanhe

"Todos já assinaram?" O assistente encontra o documento e informa quem assinou e quem falta (assinafy_get_document, ou o cartão de status de assinafy_show_document, com Lembrar e Atualizar).
"O convite chegou para o Bruno?" O assistente lê o histórico de entrega por e-mail nos dados do signatário no documento (assinafy_get_document) e os detalhes de entrega por WhatsApp (assinafy_list_whatsapp_notifications).
"O que aconteceu com este documento?" O assistente mostra a linha do tempo de eventos (assinafy_list_document_activities).

6. Lembre ou altere o prazo

Lembrar: o assistente confirma que a pessoa ainda está pendente e já foi convidada (a etapa dela está ativa) e envia um lembrete (assinafy_resend_notification). Cada lembrete pode consumir créditos; o assistente não repete só porque nada mudou.
Prorrogar: o assistente altera a expiração sem notificar ninguém (assinafy_set_assignment_expiration).
Corrigir um contato: o assistente atualiza e-mail ou telefone (assinafy_update_signer). A Assinafy bloqueia a troca de um canal que o signatário já verificou em um documento não concluído. Trocar um canal não verificado invalida links anteriores; o assistente só reenvia o convite se você pedir.

7. Certificação

Quando o último signatário termina, o documento passa a certificating e depois a certificated. "100% assinado" ainda pode estar em certificating; o assistente espera certificated antes de baixar.

Se a solicitação expirar (expired), o assistente pode tentar prorrogar o prazo (assinafy_set_assignment_expiration); se a Assinafy não permitir, recomece. Se um signatário recusar (rejected_by_signer), o assistente mostra o motivo e você decide se exclui o documento e envia uma nova solicitação.

8. Baixe e verifique

Baixar: o assistente baixa o PDF certificado (assinafy_download_document, artifact: "certificated") e o salva com as ferramentas de arquivo. Outros artefatos: original, certificate-page, bundle e pades. Prévias de página usam assinafy_download_document_page.
Verificar: informe ao assistente o hash de assinatura impresso no documento assinado. assinafy_verify_document consulta a verificação pública e retorna se é válido, o status, o número de signatários e a data de conclusão. Funciona sem login.

9. Recupere ou exclua

Operações compostas não são transacionais e escritas nunca são repetidas automaticamente. Se um envio falhar depois do upload, o assistente informa o documento retido e continua a partir dele, sem enviar o PDF de novo. A exclusão (assinafy_delete_document) só acontece quando você pede, e só em status que permitem.

O que você pode pedir

Nomes, e-mails e datas são exemplos.

Você diz	O que acontece
"Envie contrato.pdf para Ana Lima, ana@example.com, para assinatura."	Envia o PDF, aguarda o processamento e manda o convite por e-mail
"Suba proposta.pdf mas não envie. Chame de Proposta v2."	Envia e renomeia; ninguém é notificado
"Envie a Proposta v2 primeiro para a Ana, depois para o Bruno por WhatsApp."	Ordem de assinatura com verificação por e-mail e depois WhatsApp
"A Carla assina com certificado digital."	Confere se o contato da Carla tem CPF ou CNPJ na Assinafy e solicita assinatura com certificado
"Quero revisar antes de enviar o NDA para Ana e Bruno."	Mostra a solicitação; envia só depois da sua confirmação
"Coloque financeiro@example.com em cópia, sem assinar."	Adiciona um destinatário em cópia
"Use o modelo de NDA para a Carla, carla@example.com, empresa Acme Ltda."	Associa e valida o campo, preenche o papel e envia
"11.222.333/0001-81 é válido para o campo CNPJ?"	Valida sem criar nada
"Quais documentos estão aguardando assinatura?"	Lista documentos em `pending_signature`
"Todos já assinaram o contrato da Acme?"	Informa quem assinou e quem falta
"O convite por WhatsApp chegou para o Bruno?"	Mostra os detalhes de entrega por WhatsApp
"Lembre a Ana de assinar o contrato de serviços."	Confirma que ela está pendente e envia um lembrete
"Dê prazo até 15 de dezembro para os signatários da locação."	Altera a expiração; nenhum lembrete
"Baixe a cópia assinada do contrato da Acme."	Aguarda a certificação e baixa o PDF certificado
"Esta assinatura é válida? Hash FE32ED…"	Verificação pública, sem login
"Exclua o rascunho Proposta v1."	Exclui se o status permitir

Métodos de assinatura e custos

Verificação	Como o signatário confirma	Requisitos	Créditos por signatário
E-mail (padrão)	Código enviado por e-mail	Um e-mail	Incluído
WhatsApp	Código enviado por WhatsApp	Número de WhatsApp em E.164 (`+5511…`), notificação por WhatsApp, plano pago	0,45
Certificado digital	Certificado ICP-Brasil A1 ou A3	Recurso Certificado Digital; CPF ou CNPJ no contato do signatário na Assinafy; sozinho na sua etapa	0,5 mais a notificação

Cada solicitação de assinatura usa um documento da franquia do plano, ou 1 crédito quando a franquia acaba. O custo do WhatsApp vem da notificação.
Um signatário com CPF precisa do próprio e-CPF, ou de um e-CNPJ que o indique como representante legal. Um signatário com CNPJ precisa do e-CNPJ dessa empresa, de qualquer um dos representantes.
O assistente nunca pede CPF ou CNPJ. Cadastre-o no contato do signatário pelo app da Assinafy antes de solicitar assinatura com certificado.
Canais de notificação: e-mail, WhatsApp ou ambos (um por signatário com modelos). Notificação por WhatsApp é recurso pago.
Se o seu plano não inclui WhatsApp ou assinatura com certificado, a Assinafy recusa a solicitação (403) e o assistente informa qual recurso falta.
O envio de PDF em um passo (assinafy_send_pdf_for_signature) sempre usa e-mail. Para outros canais, ordem de assinatura ou cópias, o assistente usa o fluxo passo a passo.

Status do documento

Status	Significado	Pode excluir
`uploading`, `uploaded`, `metadata_processing`	Em processamento	não
`metadata_ready`	Pronto para preparar ou enviar	sim
`pending_signature`	Aguardando signatários	sim
`certificating`	Todos assinaram; certificação em andamento	não
`certificated`	Assinado e certificado	não
`expired`	Solicitação expirada	sim
`rejected_by_signer`, `rejected_by_user`	Recusado	sim
`failed`	Falha no processamento	sim

Ferramentas

27 ferramentas, uma por operação. As requisições e respostas completas de cada ferramenta estão em skills/signing/references/tools.md.

Ferramenta	Efeito
`assinafy_list_documents`	Leitura
`assinafy_get_document`	Leitura
`assinafy_list_document_activities`	Leitura
`assinafy_list_whatsapp_notifications`	Leitura
`assinafy_show_document`	Leitura; cartão de status
`assinafy_upload_document`	Escrita; sem convites
`assinafy_rename_document`	Escrita; sem convites
`assinafy_send_pdf_for_signature`	Envia convites
`assinafy_create_assignment`	Envia convites
`assinafy_create_document_from_template`	Envia convites
`assinafy_review_signature_request`	Leitura; cartão de revisão
`assinafy_place_fields`	Leitura; cartão com editor de campos
`assinafy_resend_notification`	Envia um lembrete
`assinafy_set_assignment_expiration`	Altera o prazo
`assinafy_list_signers`	Leitura
`assinafy_get_signer`	Leitura
`assinafy_create_signer`	Escrita; sem convites
`assinafy_update_signer`	Escrita; sem convites
`assinafy_list_templates`	Leitura
`assinafy_get_template`	Leitura
`assinafy_list_fields`	Leitura
`assinafy_get_field`	Leitura
`assinafy_validate_fields`	Leitura
`assinafy_download_document`	Leitura
`assinafy_download_document_page`	Leitura
`assinafy_verify_document`	Leitura; pública
`assinafy_delete_document`	Exclusão

Criação de modelos, webhooks (incluindo entregas assinadas e múltiplos endpoints), usuários, chaves de API e cobrança são gerenciados na Assinafy ou pela API REST, não por este plugin.

Sem o plugin

Qualquer cliente MCP que aceite servidores remotos com OAuth pode usar o servidor diretamente, com a mesma URL e o mesmo login; você tem as ferramentas, sem a skill.

Cliente	Configuração
Claude Code	`claude mcp add --transport http assinafy https://mcp.assinafy.com.br/mcp`, depois `/mcp`
Codex (incluindo a extensão para IDE)	`codex mcp add assinafy --url https://mcp.assinafy.com.br/mcp`, depois `codex mcp login assinafy --scopes account:read,documents:read,documents:write,templates:read,templates:write,offline_access`
VS Code / GitHub Copilot	Adicione `{"servers": {"assinafy": {"type": "http", "url": "https://mcp.assinafy.com.br/mcp"}}}` à configuração MCP e inicie o servidor

Solução de problemas

Para entrar de novo ou trocar de workspace em cada cliente:

Cliente	Reconectar
Claude Code	`/mcp` → plugin:assinafy:assinafy → Clear authentication e entre de novo (ou `claude mcp logout plugin:assinafy:assinafy`)
Apps do Claude, Cowork	Customize → Plugins → Assinafy → Connectors: desconecte e conecte
Codex	`codex mcp logout assinafy`, depois `codex mcp login assinafy --scopes account:read,documents:read,documents:write,templates:read,templates:write,offline_access`
ChatGPT, VS Code	Desconecte e conecte a Assinafy nas configurações do conector ou do servidor MCP

Sintoma	Solução
Servidor pede autenticação	Faça o login como indicado na instalação do seu cliente
`403 insufficient_scope`	Reconecte e aprove as permissões citadas na mensagem; nada foi enviado
`401` depois de um tempo sem uso	A conexão expirou; reconecte
`503`	A autorização da Assinafy está temporariamente indisponível; tente em instantes
`403` citando WhatsApp ou certificado digital	O seu plano não inclui o recurso; use e-mail ou mude de plano
PDF assinado indisponível	O documento ainda está em `certificating`; peça de novo em instantes
Erro citando documento retido	Peça ao assistente para continuar com esse documento em vez de enviar o PDF de novo
Ferramentas não aparecem no Claude Code	Rode `/reload-plugins` e confira a aba Errors em `/plugin`
Workspace errado	Reconecte e escolha o workspace correto no login

Segurança e privacidade

A autenticação é OAuth 2.1 com PKCE. O assistente se identifica para a Assinafy com o seu documento de metadados de cliente; não há segredo compartilhado. O seu assistente guarda os tokens com segurança; eles nunca vão para prompts ou argumentos de ferramentas.
O servidor valida cada token com a Assinafy e só age no workspace e nas permissões que você aprovou. Argumentos de ferramentas não trocam de workspace.
Links de assinatura, códigos de verificação e bytes de documentos não aparecem na conversa.
Revogue o acesso desconectando no seu cliente (veja Solução de problemas) ou na sua conta Assinafy.
Política de privacidade · Termos de uso · Suporte

Licença

MIT

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
assets		assets
skills/signing		skills/signing
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
mcp.json		mcp.json
plugin.json		plugin.json

Navigation Menu

Repository navigation

About

Repository files navigation

Plugin da Assinafy para assistentes de IA

Instalação

Claude Code (terminal, app desktop, VS Code, JetBrains)

Claude (chat na web, desktop e celular, e Cowork)

Codex

ChatGPT

VS Code com GitHub Copilot

Login

Fluxo completo de assinatura

1. Prepare o documento

2. Escolha signatários, canais e ordem

3. Revise e envie

4. O que os signatários fazem

5. Acompanhe

6. Lembre ou altere o prazo

7. Certificação

8. Baixe e verifique

9. Recupere ou exclua

O que você pode pedir

Métodos de assinatura e custos

Status do documento

Ferramentas

Sem o plugin

Solução de problemas

Segurança e privacidade

Licença

About

Releases

Packages

Contributors

Latest commit

History

Folders and files

Repository files navigation

Plugin da Assinafy para assistentes de IA

Instalação

Claude Code (terminal, app desktop, VS Code, JetBrains)

Claude (chat na web, desktop e celular, e Cowork)

Codex

ChatGPT

VS Code com GitHub Copilot

Login

Fluxo completo de assinatura

1. Prepare o documento

2. Escolha signatários, canais e ordem

3. Revise e envie

4. O que os signatários fazem

5. Acompanhe

6. Lembre ou altere o prazo

7. Certificação

8. Baixe e verifique

9. Recupere ou exclua

O que você pode pedir

Métodos de assinatura e custos

Status do documento

Ferramentas

Sem o plugin

Solução de problemas

Segurança e privacidade

Licença

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors