Assina MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Assina
Assinatura eletrônica de documentos PDF, grátis e em português: suba um PDF, diga quem assina e receba de volta o documento assinado, selado e com a trilha de auditoria. Com API REST e servidor MCP para sistemas e agentes. Um produto DabLab em assina.app.br.
Status: em implementação. Épicos 8.0 (guardrails) e 8.1 (fundação: banco, login com Google, boas-vindas) prontos; ver plans/.
Arquivo | O que é |
Especificação completa (fonte única de verdade) | |
O que está implementado de fato | |
Guia para sessões do Claude Code neste repositório | |
Modelo de dados para o dbdiagram.io | |
Prompt das telas para o Claude Design |
Rodar localmente
Pré-requisitos: Node 22, Docker, Supabase CLI e jq (os hooks do Claude Code usam).
npm install
supabase start # sobe o Postgres local nas portas 555xx e aplica as migrations
cp .env.example .env.local # e preencha (ver abaixo)
npm run dev # http://localhost:3030Em .env.local:
SUPABASE_SERVICE_ROLE_KEY: valorSERVICE_ROLE_KEYdesupabase status -o env.SESSION_SECRET,CHAVES_ENC_KEY,CRON_SECRET: cada um comopenssl rand -base64 32.GOOGLE_CLIENT_IDeGOOGLE_CLIENT_SECRET: ver "Google Cloud" abaixo.
Se o Postgres local travar ou cancelar por timeout (57014), confira se outro Supabase local está ligado (docker ps) e pare-o: dois ao mesmo tempo sufocam o Docker.
Related MCP server: Aoexl Sign
Verificação
npm run verify # typecheck, lint, guardrails, pgTAP, Vitest, build e npm auditSaída saudável: 29 de 29 casos ok (guardrails), Result: PASS (pgTAP), Tests N passed (Vitest), a tabela de rotas do next build e found 0 vulnerabilities.
Outros comandos: npm run db:types (tipos do banco a partir do local) e npm run db:schema (regenera supabase/schema.sql).
Banco
Projeto Supabase compartilhado com outros apps da DabLab (jeesdmfcrmhyufwzwzwt): todo objeto do Assina leva o prefixo as_. Migrations ficam em supabase/migrations/ e vão ao remoto pelo MCP do Supabase (apply_migration, mesmo SQL do arquivo), nunca por supabase db push, que tentaria sincronizar o projeto inteiro. Depois de cada migration: advisors de segurança e performance filtrados a as_* e npm run db:schema.
Google Cloud (login)
O Assina pede só openid email profile: escopos não sensíveis, sem verificação do Google. Fica num projeto próprio "Assina" na conta da DabLab, para a tela de consentimento mostrar o nome certo.
console.cloud.google.com → seletor de projeto → Novo projeto → nome
Assina→ Criar.APIs e serviços → Tela de consentimento OAuth (Google Auth Platform) → Começar:
Nome do app:
Assina; e-mail de suporte:alexandre@dablab.com.br.Público: Externo.
Contato do desenvolvedor:
alexandre@dablab.com.br.
Marca (Branding): página inicial
https://assina.app.br, política de privacidadehttps://assina.app.br/privacidade, termoshttps://assina.app.br/termos, domínio autorizadoassina.app.br. Essas páginas chegam no épico 8.12; até lá, deixe para depois a verificação da marca.Acesso a dados (escopos): só
openid,.../auth/userinfo.emaile.../auth/userinfo.profile. Nenhum escopo sensível.Público → Publicar app (status "Em produção"). Com escopos básicos não há revisão do Google nem limite de 100 usuários de teste.
Clientes → Criar cliente → tipo Aplicativo da Web, nome
Assina web:Origens JavaScript autorizadas:
http://localhost:3030ehttps://assina.app.br.URIs de redirecionamento autorizados:
http://localhost:3030/api/auth/google/callbackehttps://assina.app.br/api/auth/google/callback.
Copie o ID do cliente e a Chave secreta para
GOOGLE_CLIENT_IDeGOOGLE_CLIENT_SECRETno.env.local(e, no deploy, nas variáveis da Vercel).
Cloudflare R2 (arquivos, a partir do épico 8.2)
Painel da Cloudflare (conta DabLab) → R2 → Criar bucket → nome
assina-documentos, sem acesso público e sem domínior2.dev.No bucket → Configurações → Política de CORS:
[{ "AllowedOrigins": ["https://assina.app.br", "http://localhost:3030"], "AllowedMethods": ["GET", "PUT"], "AllowedHeaders": ["content-type"], "MaxAgeSeconds": 3600 }]R2 → Gerenciar tokens de API → Criar token: permissão Leitura e gravação de objetos, restrito ao bucket
assina-documentos.Copie para
R2_ACCOUNT_ID,R2_ACCESS_KEY_ID,R2_SECRET_ACCESS_KEYeR2_BUCKET.
Selo do PDF final (épico 8.6)
O PDF final leva um selo PAdES da plataforma (regra 11.10). O selo só garante a integridade do arquivo; não é a assinatura de quem assinou.
Certificado. Para dev (e para o MVP, até a decisão 25.2):
npm run selo:gerar. O comando imprimeSELO_P12_BASE64=…eSELO_P12_SENHA=…e não grava nenhum arquivo. Cole as duas linhas no.env.local, ou, em produção, nas variáveis da Vercel. Com o certificado autoassinado, o Adobe Reader mostra "identidade desconhecida", o que é esperado.Carimbo do tempo (opcional).
SELO_TSA_URLcom uma TSA RFC 3161 gratuita. Em 17/11/2026 responderam em cerca de 0,5 s:http://timestamp.digicert.com,https://freetsa.org/tsrehttp://timestamp.sectigo.com. Com resposta em até 5 s, o selo éB-T; sem resposta,B-B, e o envelope conclui do mesmo jeito.Alerta.
ADMIN_EMAILrecebe o "[Assina] Finalização falhou 3 vezes".Conferir um PDF selado. Basta abrir no Adobe Reader. Pela linha de comando:
python3 -c "import re,sys;b=open(sys.argv[1],'rb').read();a,l,c,d=map(int,list(re.finditer(rb'/ByteRange\s*\[\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)',b))[-1].groups());open('c.bin','wb').write(b[a:a+l]+b[c:c+d]);open('s.der','wb').write(bytes.fromhex(b[a+l+1:c-1].decode()))" final.pdf openssl cms -verify -binary -inform DER -in s.der -content c.bin -noverify -purpose any -out /dev/null
API REST v1 e webhooks (épico 8.9)
A documentação legível fica em /docs/api, e o contrato em /api/v1/openapi.json (OpenAPI 3.1). A chave de API de cada conta está em Integrações (Authorization: Bearer assina_…). Gerar uma nova chave revoga a anterior na hora.
Fluxo completo por curl:
# 1. Criar com o PDF numa URL https (ou sem arquivo_url, para receber a upload_url)
curl -s -X POST https://assina.app.br/api/v1/envelopes \
-H "Authorization: Bearer $ASSINA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-123" \
-d '{"titulo":"Contrato","arquivo_url":"https://exemplo.com.br/contrato.pdf",
"signatarios":[{"nome":"Ana Souza","email":"ana@exemplo.com.br"}],
"campos":[{"signatario_email":"ana@exemplo.com.br","tipo":"assinatura","pagina":1,"x":0.1,"y":0.8}]}'
# 1b. Sem arquivo_url: suba o PDF na upload_url e confirme
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @contrato.pdf
curl -s -X POST https://assina.app.br/api/v1/envelopes/$ID/arquivo -H "Authorization: Bearer $ASSINA_CHAVE"
# 2. Enviar
curl -s -X POST https://assina.app.br/api/v1/envelopes/$ID/enviar -H "Authorization: Bearer $ASSINA_CHAVE"
# 3. Consultar (e a trilha)
curl -s https://assina.app.br/api/v1/envelopes/$ID -H "Authorization: Bearer $ASSINA_CHAVE"
curl -s https://assina.app.br/api/v1/envelopes/$ID/eventos -H "Authorization: Bearer $ASSINA_CHAVE"
# 4. Depois do webhook envelope.concluido, baixar o assinado (URL de 5 minutos)
curl -s "https://assina.app.br/api/v1/envelopes/$ID/arquivo?versao=final" -H "Authorization: Bearer $ASSINA_CHAVE"Os webhooks chegam por POST na URL https configurada em Integrações, com os cabeçalhos Assina-Assinatura (t={epoch},v1={hmac_sha256(segredo, t + "." + corpo)}), Assina-Entrega e Assina-Evento. Responda 2xx; sem isso, o Assina tenta de novo, até 6 vezes (a faxina diária retenta). Exemplo de verificação em Node:
// Conferir o webhook do Assina (Node 18+, sem dependências).
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
const SEGREDO = process.env.ASSINA_WEBHOOK_SEGREDO; // whsec_… (tela Integrações)
createServer((req, res) => {
const partes = [];
req.on("data", (p) => partes.push(p));
req.on("end", () => {
const corpo = Buffer.concat(partes).toString("utf8"); // o corpo cru, antes do JSON.parse
const cab = String(req.headers["assina-assinatura"] ?? "");
const t = /t=(\d+)/.exec(cab)?.[1];
const v1 = /v1=([0-9a-f]{64})/.exec(cab)?.[1];
const esperado = createHmac("sha256", SEGREDO).update(`${t}.${corpo}`).digest("hex");
const recente = Math.abs(Date.now() / 1000 - Number(t)) < 300; // contra reenvio antigo
if (!t || !v1 || !recente || !timingSafeEqual(Buffer.from(v1), Buffer.from(esperado))) {
res.writeHead(401).end();
return;
}
const evento = JSON.parse(corpo); // { evento, envelope, signatario?, ocorrido_em }
console.log(req.headers["assina-entrega"], evento.evento, evento.envelope.id);
res.writeHead(200).end(); // 2xx = entregue; qualquer outra resposta será retentada
});
}).listen(3000);MCP: conectar ao Claude e ao ChatGPT (épico 8.10)
O endereço do servidor MCP é https://assina.app.br/mcp (Streamable HTTP). Ele aceita dois tipos de credencial: o token do OAuth, que os aplicativos pegam sozinhos, e a chave de API, para clientes configurados por arquivo. A tela Integrações mostra os dois caminhos e a lista de conexões autorizadas, com "Revogar".
Claude (claude.ai e Claude Desktop), pelo aplicativo:
Configurações → Conectores → Adicionar conector personalizado.
Nome
Assina; URLhttps://assina.app.br/mcp; Adicionar.Conectar: abre o Assina. Entre com o Google, se pedir, e clique em Permitir.
A conexão aparece em Integrações → "Conexões autorizadas", com o nome que o Claude registrou.
ChatGPT (modo desenvolvedor), pelo aplicativo:
Configurações → Aplicativos e conectores → Configurações avançadas → ligue o Modo desenvolvedor.
Criar conector: nome
Assina; URLhttps://assina.app.br/mcp; autenticação OAuth.Ao conectar, abre o Assina: Permitir.
Claude Code ou Claude Desktop por arquivo (com a chave de API de Integrações):
{ "mcpServers": { "assina": { "type": "http", "url": "https://assina.app.br/mcp", "headers": { "Authorization": "Bearer assina_…" } } } }No Claude Code, o mesmo pode ser feito pela linha de comando: claude mcp add --transport http assina https://assina.app.br/mcp --header "Authorization: Bearer assina_…".
As ferramentas são listar_envelopes, ver_envelope, criar_envelope (só rascunho; nunca envia), enviar_envelope (o assistente confirma antes), lembrar_signatarios, cancelar_envelope e link_do_documento. O MCP não exclui envelope e não mexe na chave nem no webhook.
Os prints de cada passo entram quando houver deploy (PENDENCIAS P9).
Analytics no Visão do Produto (épico 8.11)
Os eventos da seção 21 do spec (assina_*) saem do servidor para o Visão do Produto, sem segurar a resposta: timeout de 4 s, e qualquer falha só fica no log como analytics_falhou. Nenhuma propriedade leva título, nome, e-mail, CPF, mensagem, motivo, IP, valor de campo ou nome de arquivo.
No Visão do Produto, crie o projeto Assina com o prefixo
assina_e copie a chave de ingestão.Na Vercel (e no
.env.local, se quiser ver os eventos de dev), defina:VISAO_INGEST_URL: o endereço…/functions/v1/ingestdo Visão;VISAO_API_KEY: a chave copiada.
Sem as duas, nada é enviado.
Faça um envelope de teste ponta a ponta e confira em Atividade:
assina_envelope_criado,assina_envelope_enviado,assina_documento_assinadoeassina_envelope_concluido.
Vercel Firewall (limites por IP)
O app não conta requisições por IP: quem limita é o Vercel Firewall, configurado no painel da Vercel (projeto → Firewall → Configure → New Rule). Cada regra usa a condição Request Path starts with, a ação Rate Limit e a janela fixa de 60 s por IP. Acima do limite, a resposta é 429.
Caminho | Limite | Por quê |
| 30 por minuto | critério 8.8: a consulta é pública (a página do código também consulta o banco) |
| 20 por minuto | página do signatário (código por e-mail) |
| 120 por minuto | integrações (épicos 8.9 e 8.10) |
| 30 por minuto | registro de cliente e troca de código (épico 8.10) |
Para conferir depois de criar, rode for i in $(seq 1 35); do curl -s -o /dev/null -w "%{http_code} " "https://assina.app.br/api/verificar?codigo=AAAAAAAAAAAA"; done: as primeiras 30 respostas são 200 e as seguintes, 429.
Licença
MIT. Referência funcional: SignuDoc (MIT); todo código adaptado dele leva atribuição em THIRD_PARTY_NOTICES.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Get PDFs signed: prepare, send and track e-signature requests, then fetch the signed copy.
E-signature API: send documents for signature, track envelopes, get signed files.
Send documents for e-signature, track signing status, and download signed PDFs. No API key required.
E-signatures: send, track, remind, void and download envelopes; templates and reports.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for the Dropbox Sign API supporting signature requests, templates, teams, accounts, events, documents, signers, reports, bulk operations, and workflows.MIT
- FlicenseNot gradedqualityDmaintenanceEnables users to create, manage, and track electronic signing requests and templates through Claude Desktop and other MCP-compatible clients. Provides multi-tenant authentication with customer API keys for secure document workflow operations.66 npm-
- AlicenseAqualityDmaintenanceProvides DocuSign eSignature operations via JWT Grant for headless AI agents, enabling envelope management, document signing, and template access through MCP tools.9MIT
- AlicenseAqualityDmaintenanceEnables sending PDFs for e-signature via the TurboSign API, with tools for sending, reviewing, tracking status, downloading signed documents, voiding, resending, and managing credentials.12MIT