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.
Power your agent
The publisher's own URL. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
https://mcp.assinafy.com.br/mcpThe Claude button above opens Claude with the name and URL filled in. You still confirm it there.
claude mcp add --transport http assinafy-mcp-server https://mcp.assinafy.com.br/mcpRun in a terminal.
{ "mcpServers": { "assinafy-mcp-server": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.assinafy.com.br/mcp" ] } }}claude_desktop_config.json
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
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.
Servidor MCP oficial da Assinafy: conecte assistentes de IA para enviar documentos, acompanhar assinaturas e baixar PDFs assinados. Official MCP server for Brazilian e-signature with workspace authorization.
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 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 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.
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.
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.
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.
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.
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.
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.
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]
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.
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.
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.
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.
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": "[email protected]"
}
],
"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:
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.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.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.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.
DigitalCertificate exige method: "virtual". Uma chamada collect é recusada
antes da estimativa ou do envio com
digital_certificate_requires_virtual.
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.
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.
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:
assinafy_list_templates, seguindo a
paginação, e inspecione seu status de processamento, roles e
pages[].fields.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.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_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.
Templates com campos posicionados usam collect e não aceitam
DigitalCertificate. O servidor confere templates com certificado e retorna
digital_certificate_requires_virtual antes de estimar custos, criar contatos,
gerar o documento ou enviar convites.
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": "[email protected]",
"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.
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.
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.
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_create_assignment 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.
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:
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.
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.
Servidor MCP oficial da Assinafy: conecte assistentes de IA para enviar documentos, acompanhar assinaturas e baixar PDFs assinados. Official MCP server for Brazilian e-signature with workspace authori
{ "mcpServers": { "assinafy-mcp-server": { "url": "https://mcp.assinafy.com.br/mcp", "headers": {} } }}Overview
Servidor MCP oficial da Assinafy: conecte assistentes de IA para enviar documentos, acompanhar assinaturas e baixar PDFs assinados. Official MCP server for Brazilian e-signature with workspace authorization.
Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
Assinafy is reached over HTTP.
Last checked 2026-11-05. Servidor MCP oficial da Assinafy: conecte assistentes de IA para enviar documentos, acompanhar assinaturas e baixar PDFs assinados. Official MCP server for Brazilian e-signature with workspace authorization.