Claude Code e Agent SDK com o MCP da SignDocs: Automações de Assinatura com Humano no Circuito
O servidor MCP oficial da SignDocs transforma a assinatura eletrônica em ferramentas que a Claude entende. Para quem usa Claude Code no terminal ou constrói agentes com o Agent SDK, isso abre um padrão simples e seguro: o agente prepara, a pessoa confirma, a plataforma assina e registra. Este guia mostra como conectar, quais ferramentas existem em cada modo de acesso, como montar fluxos de contrato a partir do repositório, como usar a verificação de documentos em pipelines e, principalmente, quais guardrails impedem que um agente dispare um ato com efeito jurídico sem ninguém olhar.
Não há SDK novo para aprender. O servidor MCP é uma camada fina sobre a API REST da SignDocs — as mesmas sessões, envelopes, evidências e webhooks. O que muda é quem monta a chamada: em vez do seu código, um modelo de linguagem que lê o pedido em português, escolhe a ferramenta certa e pede confirmação antes de qualquer coisa que consuma cota ou tenha validade jurídica.
Se você quer a visão geral do canal (claude.ai, Desktop, API da Claude), comece pela página de integração com a Claude. Aqui o foco é o desenvolvedor no terminal e o agente em produção.
Dois modos de conectar, dois catálogos de ferramentas
O endpoint hospedado é um só, https://mcp.signdocs.com.br/mcp, mas a forma de autenticar define o que o agente enxerga:
| Conta SignDocs (pessoa física) | Credencial de API (pessoa jurídica) | |
|---|---|---|
| Como entra | Login OAuth na própria conta do app, sem credencial e sem instalar nada | Client ID + Client Secret criados no painel (app.signdocs.com.br → API) |
| Ambiente | Produção direto: envios valem e consomem a cota do plano (Grátis = 5 documentos por mês) | Homologação primeiro (gratuita, biometria simulada, dados apagados em 7 dias); produção em plano sob medida |
| Ferramentas | 13: criar sessão e envelope, subir documento, status, download, evidências, verificações, cancelar, conta | Catálogo completo de 24: tudo acima mais listar/consultar transações e sessões e as 4 ferramentas de webhook |
| Para quem | Uso pessoal e sob demanda no Claude Code | Equipes, agentes em produção, pipelines |
A diferença de catálogo não é capricho: em modo conta, o tenant é compartilhado entre pessoas, então ferramentas de listagem mostrariam o documento de um usuário para outro. Elas simplesmente não são registradas nesse modo.
Conectar no Claude Code
Com a sua conta (pessoa física)
Sem variável de ambiente, sem segredo no disco. A senha é digitada só no site da SignDocs; o Claude Code guarda apenas o token da sessão OAuth.
Com credencial de API (equipe ou agente)
Prefere rodar o servidor localmente (ambiente isolado, build próprio)? O pacote @signdocs-brasil/mcp-server roda por stdio com as mesmas ferramentas:
Regra de ouro para agentes: comece em hml. A credencial de homologação é gratuita, não pede cartão e o que o agente criar some em 7 dias. Só troque para produção quando o fluxo estiver revisado — em produção, cada envio consome um documento e gera um ato com validade jurídica. O guia do sandbox detalha o que é simulado.
Fluxo típico numa sessão de Claude Code: do template ao link de assinatura
O caso que mais aparece: o contrato nasce de um template versionado no repositório, e a pessoa quer sair do terminal com o link de assinatura na mão. Passo a passo, com a Claude fazendo o trabalho braçal:
- Gerar o documento. "Preencha
templates/contrato-prestacao.mdcom os dados do cliente emclientes/acme.jsone gere o PDF emout/." A Claude usa as ferramentas normais do projeto (seu script de HTML→PDF,pandoc, o que houver). A SignDocs não tem templates nem preenche campos — isso fica do seu lado. - Subir o PDF. "Me dá um link para subir o PDF na SignDocs." A ferramenta
request_document_uploaddevolve uma página de upload; o arquivo vai direto para a plataforma. Anexos no chat nunca chegam às ferramentas — é assim por desenho. - Criar a sessão. "Cria a assinatura para Ana Souza, ana@acme.com.br, CPF 000.000.000-00, clique + código por e-mail." A Claude monta a chamada de
create_signing_sessione pede a sua confirmação antes de executar, porque a ferramenta é marcada como consequente. Só depois do "sim" o link existe. - Acompanhar. "Quem já assinou?" —
get_signing_session_statusouget_envelope. "Me manda o assinado e as evidências" —download_documenteget_evidence.
Para várias partes, o pedido vira um create_envelope com todos os signatários numa chamada só — um envelope custa um documento da cota, não importa quantas pessoas assinem. CPF ou CNPJ é obrigatório para cada signatário; sem ele o envio é recusado e nada é descontado.
Agent SDK: o agente prepara, a pessoa confirma
Quando o agente deixa de ser interativo e passa a rodar em processo — um agente de compras que dispara o contrato do fornecedor quando a aprovação sai, um agente de onboarding que monta o envelope de admissão — a arquitetura precisa de uma fronteira clara entre preparar e executar. O padrão que recomendamos:
| Etapa | Quem faz | Ferramentas MCP envolvidas |
|---|---|---|
| Coletar dados, escolher o perfil de autenticação, gerar o PDF, subir | Agente, sem supervisão | request_document_upload, leitura de signdocs://policy-profiles |
| Propor a ação: "vou criar um envelope sequencial com estes 3 signatários" | Agente apresenta; pessoa aprova | nenhuma ainda |
| Executar a ação consequente | Agente, só após aprovação explícita | create_envelope, create_signing_session, cancel_* |
| Acompanhar e reconciliar | Seu sistema, pela API REST | webhooks + GET /v1/transactions/{id} (fora do MCP) |
O servidor ajuda nisso de duas formas. As ferramentas consequentes carregam anotações de destructive hint e um aviso na própria descrição, então clientes compatíveis param e perguntam. E ele expõe recursos de grounding — signdocs://quickstart, signdocs://policy-profiles, signdocs://webhook-events — que o modelo lê sob demanda em vez de inventar perfis ou eventos.
Para o seu próprio agente, o endpoint aceita autenticação por cabeçalho na inicialização: Authorization: Bearer com um token da API, Basic com Client ID e Secret, ou os dois como cabeçalhos simples X-SignDocs-Client-Id e X-SignDocs-Client-Secret; o ambiente vai em X-SignDocs-Environment: hml|production. Na Messages API da Claude, o mesmo endpoint entra no parâmetro de servidores MCP. Não descrevemos aqui a API do Agent SDK linha a linha — o padrão acima é o que importa, e ele vale para qualquer orquestrador.
Verificação de documentos em pipelines
Nem todo uso é de envio. A ferramenta verify_document recebe um PDF e detecta as assinaturas presentes; verify_evidence e verify_envelope consultam o verificador público a partir de um identificador. Isso encaixa bem em automações onde um agente revisa contratos recebidos:
- Um passo de CI que recebe o PDF anexado a um pull request de "contratos assinados" e falha se o documento não tiver assinatura detectável.
- Um agente de compliance que, dado o evidenceId impresso no documento, confirma status e hashes no verificador público antes de arquivar.
- Uma triagem de e-mail que separa "PDF com assinatura digital" de "PDF com foto de assinatura" antes de alguém abrir.
Atenção ao custo: verify_document só existe em produção e consome cota, por isso também é marcada como sensível. As verificações por identificador são públicas e não consomem. Para o desenho de pipelines de teste em geral, veja testar a integração no sandbox e no CI.
Guardrails que não são opcionais
Um agente com ferramentas de assinatura é um agente que pode criar obrigações jurídicas e gastar dinheiro. Quatro regras, na ordem em que elas costumam ser quebradas:
- Nunca auto-aprove ferramentas consequentes. Revise a configuração de auto-aprovação do cliente. As anotações do servidor são dicas; quem decide se pergunta é o cliente. No Claude Code, mantenha
create_*,cancel_*everify_documentfora de qualquer lista de permissão automática. Um agente sem interface deve parar e escalar para uma pessoa nesse ponto. - O transcript não é prova. Um modelo pode narrar "enviei" sem ter enviado, ou omitir um resultado. Para saber o que aconteceu, use o que não depende da narração: o e-mail de conclusão, a lista de documentos no app e, no lado do sistema, os webhooks e o
GET /v1/transactions/{id}. - Reconcilie pela API REST, não pelo chat. O MCP é ótimo para agir; o estado de verdade do seu sistema vem dos eventos
SIGNING_SESSION.COMPLETEDeENVELOPE.ALL_SIGNEDe de um job de reconciliação. O guia de webhooks em fila descreve esse desenho. - Separe credenciais por agente e por ambiente. Uma credencial de homologação para desenvolver, outra de produção só no agente revisado; nunca a mesma credencial no laptop de todo mundo e no servidor. O guia de credenciais mostra como criar mais de uma.
O que o agente não decide: quem assina e com qual nível de autenticação. Clique, clique + OTP, biometria com prova de vida ou certificado ICP-Brasil são uma escolha de risco do negócio, definida por documento. Deixe isso explícito no prompt ou na configuração do agente, não a critério do modelo em tempo de execução.
Erros que vimos em agentes reais
- Credencial de produção no ambiente de desenvolvimento. Cenário fácil de reproduzir: o agente "testa" e cria sessões reais, com cota debitada e signatários avisados. Homologação primeiro, sempre; produção só na credencial do agente revisado.
- Payload montado de cabeça. O modelo inventou um perfil de autenticação que não existe e levou um 400; na segunda tentativa, corrigiu sozinho. Apontar o recurso
signdocs://policy-profilesno prompt do sistema evita a primeira tentativa errada. - Escopo insuficiente na credencial. Uma ferramenta de webhook respondeu 403 porque a credencial não tinha o escopo correspondente. A mensagem de erro é clara; o que falta é ler o erro em vez de tentar de novo.
- Confirmação humana desligada "para agilizar". É o único erro desta lista que não tem volta: uma sessão criada é um convite enviado. Cancelar não devolve o documento para a cota.
Quando usar MCP e quando usar a API direto
O MCP brilha no trabalho sob demanda e conversacional: gerar, enviar e acompanhar um contrato sem sair do terminal; um agente que raciocina sobre um caso por vez. Para alto volume e fluxos fixos — mil admissões por mês, integração com o ERP — a API REST com webhooks e idempotência continua sendo o caminho, e o nó do n8n cobre a automação sem código. Nada impede de combinar: o agente prepara e dispara pelo MCP; o backend acompanha pela API.
O servidor é código aberto (MIT), publicado no npm como @signdocs-brasil/mcp-server, com o plugin e a extensão de desktop no GitHub em signdocsbrasil/signdocs-mcp-plugin. A integração testada e suportada hoje é com a Claude; outros clientes conectam pelo padrão aberto MCP.
Perguntas Frequentes
Preciso de credencial de API para usar a SignDocs no Claude Code?
Não, se for uso pessoal. Com claude mcp add --transport http signdocs https://mcp.signdocs.com.br/mcp e depois /mcp, o login abre no navegador com a mesma conta do aplicativo (pessoa física), sem credencial e sem instalar nada. A credencial de API entra quando o acesso é de uma pessoa jurídica, de uma equipe ou de um agente em produção: aí o caminho é o plugin oficial ou o servidor local, com Client ID e Client Secret criados no painel — e com o ambiente de homologação disponível antes da produção.
Quais ferramentas o agente vê em cada modo?
Entrando com a conta pessoal, são 13 ferramentas: criar sessão e envelope, subir documento, consultar status, baixar documento e evidências, verificar documento, evidência e envelope, cancelar sessão e envelope, e consultar a própria conta. Com credencial de API, o catálogo completo tem 24, acrescentando listar e consultar transações e sessões e as quatro ferramentas de webhook. As de listagem ficam fora do modo conta porque o tenant é compartilhado e elas exporiam documentos de uma pessoa para outra.
Como impedir que um agente crie uma assinatura sem ninguém aprovar?
As ferramentas com efeito jurídico ou que consomem cota (criar sessão, criar envelope, adicionar signatário, cancelar, verificar documento) carregam anotações de ação consequente e um aviso na descrição, e clientes compatíveis, como o Claude Code, pedem confirmação humana antes de executar. Isso é uma dica ao cliente, não uma trava do servidor: revise a configuração de auto-aprovação e mantenha essas ferramentas fora de qualquer lista automática. Um agente sem interface deve parar nesse ponto e escalar para uma pessoa.
O agente pode anexar o PDF no chat para enviar?
Não. Arquivos anexados na conversa nunca chegam às ferramentas, por desenho. O fluxo é pedir um link de upload com request_document_upload e subir o PDF por ele; o arquivo vai direto para a plataforma sem passar pelo chat. Se o contrato foi gerado a partir de um template do repositório, a Claude gera o PDF com as ferramentas do próprio projeto e depois usa esse link. A SignDocs não tem templates nem preenchimento de campos: isso fica do seu lado.
Como sei se a assinatura realmente aconteceu?
Não pelo transcript. Um modelo pode narrar um envio que não ocorreu ou omitir um resultado. A prova está no que não depende da narração: o e-mail de conclusão, a lista de documentos no aplicativo e, no lado do seu sistema, os webhooks SIGNING_SESSION.COMPLETED e ENVELOPE.ALL_SIGNED e a consulta GET /v1/transactions/{id} pela API REST. Para agentes em produção, o desenho recomendado é o agente agir pelo MCP e o backend reconciliar pela API.
Posso testar sem gastar cota nem criar assinaturas reais?
Sim, com credencial de API no ambiente de homologação: é gratuito, não pede cartão, a biometria é simulada e os dados são apagados em 7 dias. O plugin do Claude Code aponta para a homologação por padrão, e o servidor local usa SIGNDOCS_ENVIRONMENT=hml. Entrando com a conta pessoal, você já está em produção: cada envio consome um documento do plano (o Grátis dá 5 por mês) e tem validade jurídica, então use esse modo quando a intenção for assinar de verdade.
Dê ao seu agente as ferramentas de assinatura — com uma pessoa no circuito
Crie credenciais de homologação, conecte o Claude Code ou o seu agente ao servidor MCP e teste o fluxo completo sem custo. Quando o fluxo estiver revisado, o time comercial dimensiona o plano de produção.
Criar credenciais de homologação Fale com o time comercial