Teste ao vivo

Execute este fluxo no ZapSign Builders — playground interativo da API REST. Abrir no Builders →

Use o ambiente sandbox para testes

Nenhum documento real será criado ou assinado. Gere seu token em sandbox.zapsign.com.br → Configurações → Integrações → API. Quando estiver pronto para produção, troque pelo token da conta em app.zapsign.com.br.

Pré-requisitos

Passo a passo

Opção mais fácil: conecte via URL Recomendado

Abra Cursor Settings → MCP (ou Cmd/Ctrl+Shift+J → MCP) e clique em Add new global MCP server. Selecione o tipo URL e cole:

URL do servidor MCP ZapSignURL
https://mcp.zapsign.com.br/mcp

O Cursor abrirá um fluxo OAuth. Na tela de autorização ZapSign, acesse Configurações → Integrações → API, copie seu api_token e cole no campo para completar a conexão.

→ Reinicie o Cursor completamente após adicionar o servidor. Não basta fechar e abrir — encerre o processo pelo Gerenciador de Tarefas (Windows) ou Quit Cursor no macOS, depois reabra. O status verde só aparece após reinício completo.

Verifique em MCP Settings

Abra Cursor Settings → MCP. O servidor zapsign deve aparecer com status verde e a lista de ferramentas (criar documento, signatários, modelos). Se estiver vermelho, clique em refresh ou reinicie o Cursor.

Teste no modo Agent

Abra o chat (Cmd/Ctrl+I) em modo Agent e peça:

prompt no Cursorchat
Usando as ferramentas da ZapSign, crie um documento de teste
chamado "Teste Cursor" a partir de
https://zapsign.s3.amazonaws.com/exemplo.pdf
com signatário Seu Nome <voce@empresa.com>
e me retorne o link de assinatura.

O Cursor pedirá aprovação para usar a ferramenta na primeira vez e devolverá o sign_url.

Alternativa: configuração manual via mcp.json (para desenvolvedores)

Escolha o escopo: global ou por projeto

O Cursor lê servidores MCP de dois lugares:

  • ~/.cursor/mcp.json — disponível em todos os projetos.
  • .cursor/mcp.json na raiz do projeto — só naquele repositório (bom para times).

Se usar o escopo de projeto, não commite seu token. Adicione .cursor/mcp.json ao .gitignore ou injete o token por variável de ambiente.

Crie o mcp.json

Requer Node.js 18+ instalado.

~/.cursor/mcp.jsonJSON
{
  "mcpServers": {
    "zapsign": {
      "command": "npx",
      "args": ["-y", "mcp-server-zapsign"],
      "env": {
        "ZAPSIGN_API_KEY": "seu_api_token",
        "ZAPSIGN_BASE_URL": "https://sandbox.zapsign.com.br/api/v1"
      }
    }
  }
}

Após criar o mcp.json, reinicie o Cursor completamente. Use o Gerenciador de Tarefas (Windows) ou Quit Cursor no macOS para encerrar o processo e reabra.

Fluxo de desenvolvimento recomendado

Com o MCP ativo, o agente do Cursor consegue desenvolver e verificar sua integração num único loop:

  • "Implemente um serviço ZapSignClient em TypeScript com criação de documento e listagem. Depois, use as ferramentas MCP para criar um documento real e validar que o formato do payload está certo."
  • "Meu webhook não dispara — liste os webhooks da minha conta via MCP e compare com o que o código registra."
  • "Gere testes de integração usando um documento criado agora via MCP como fixture."

Dica: aponte o agente para https://docs.zapsign.com.br/llms.txt no prompt (ou nas regras do projeto) para que ele consulte os endpoints reais em vez de alucinar.

Problemas comuns

SintomaCausa provável e correção
Servidor vermelho no MCP SettingsCursor não foi reiniciado completamente. Use o Gerenciador de Tarefas (Windows) ou Quit Cursor (macOS) e reabra.
Ferramentas não aparecem no AgentConfirme que o chat está em modo Agent (não Ask) e que o servidor está habilitado.
401 UnauthorizedToken inválido. Reconecte via URL ou atualize ZAPSIGN_API_KEY no mcp.json.

Próximos passos