The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Assinafy listing page.
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.
Conclua a entrada no navegador, escolha o workspace e aprove as permissões. Veja a documentação MCP do Codex.
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.
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.
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.
Adicione esta entrada à configuração MCP do VS Code:
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.
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:
Para uma conexão de documentos intencionalmente somente leitura, escolha:
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.
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.
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.
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.
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:
Identificado o documento correto, chame assinafy_find_documents (action: "get"):
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.
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.
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:
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.
Use assinafy_follow_up_assignment (action: "set_expiration") com os IDs dos detalhes atuais do
documento e um timestamp RFC 3339 explícito:
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.
Para o fluxo comum por e-mail, chame assinafy_request_signatures (action: "from_pdf"):
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:
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.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.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.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"):
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").
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"):
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.
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:
assinafy_find_templates (action: "list"), seguindo a
paginação, e inspecione seu status de processamento, roles e
pages[].fields.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.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.field_id recebem um único valor; a API não oferece valor por posicionamento
nesta requisição.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.
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_find_documents (action: "get") 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):
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.
assinafy_download_document (action: "page") recebe document_id e um page_id retornado.
Devolve os bytes da imagem em base64. Baixe apenas as páginas necessárias.
Concluída a certificação, chame assinafy_download_document (action: "artifact") 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.
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.
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:
assinafy_request_signatures (action: "from_document") com os IDs de signatário confirmados. Não precisa
de novo upload. Confira o status de processamento antes de posicionar campos.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.
| Resultado | Ação do cliente |
|---|---|
| HTTP 401 | Deixe o cliente renovar a concessão ou reconectar pelo consentimento da Assinafy. |
HTTP 403 com insufficient_scope | Autorize os escopos pedidos somados aos já concedidos e tente de novo após o consentimento. |
| Erro de ferramenta nomeando um escopo ausente | A Assinafy recusou a chamada. Reconecte somando o escopo indicado; tentar de novo sem novo consentimento falha outra vez. Uma ferramenta de várias etapas pode ter concluído etapas anteriores; leia o erro em busca de um document_id preservado e continue dali. |
Resultado de ferramenta com isError: true | Leia o erro da Assinafy e inspecione o documento atual antes de repetir uma escrita. |
| Contato inválido, assignment expirado ou artefato indisponível | Corrija a requisição ou aguarde o estado necessário do ciclo de vida. |
| Limite de taxa ou resposta de rede incerta | Respeite o tempo de nova tentativa; inspecione o estado e o histórico de entrega antes de repetir uma escrita. |
| HTTP 429 | A Assinafy está limitando as verificações de autorização; respeite o Retry-After. |
| HTTP 503 na autenticação | Serviço temporariamente indisponível. Tente mais tarde; contate o suporte da Assinafy se persistir. |
Veja erros e recuperação e a referência de entradas.
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:
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.