Servidor MCP da ZapSign: guia completo

O que é

O ZapSign api-mcp é um servidor do Model Context Protocol (MCP) — o padrão aberto que conecta LLMs a sistemas externos. Ele traduz a API REST da ZapSign em ferramentas tipadas que qualquer cliente MCP (Claude, Cursor, Codex, Gemini CLI, ChatGPT com conectores, agentes próprios) consegue descobrir e chamar com segurança.

Na prática: em vez de você escrever código de integração, seu agente recebe ferramentas como create_document_from_template e decide quando usá-las a partir de instruções em linguagem natural.

Instalação

Via npm (para uso com npx nos clientes MCP):

terminalbash

npm install -g mcp-server-zapsign
# ou sem instalar, direto na config do cliente:
npx -y mcp-server-zapsign

A partir do código-fonte (para SSE, produção ou desenvolvimento):

terminalbash

git clone https://github.com/ZapSign/api-mcp.git
cd api-mcp
npm install
cp .env.example .env   # configure ZAPSIGN_API_KEY

Configuração (.env)

.envenv

# Obrigatório
ZAPSIGN_API_KEY=seu_api_token

# Padrões sensatos
ZAPSIGN_BASE_URL=https://api.zapsign.com.br
ZAPSIGN_API_VERSION=v1
PORT=3001
HOST=localhost
LOG_LEVEL=info
ENABLE_RATE_LIMITING=true
MAX_REQUESTS_PER_MINUTE=100

Gere ou copie seu api_token em Configurações → Integrações → API. O servidor aceita tanto o token principal da conta quanto tokens de workspace — use tokens de workspace para limitar o alcance do agente.

Modos de execução

Modo	Comando	Quando usar
stdio	`npm start` / `npx mcp-server-zapsign`	Clientes locais: Claude Desktop, Claude Code, Cursor, Codex, Gemini CLI.
SSE (HTTP)	`npm run start:sse`	Clientes remotos: conector do ChatGPT, agentes hospedados, múltiplos usuários.
desenvolvimento	`npm run dev`	Contribuindo com o projeto ou depurando.

No modo SSE há um endpoint de saúde para monitoração:

terminalbash

curl http://localhost:3001/health
# → status do servidor, autenticação, saúde da API e contagem de ferramentas

Ferramentas disponíveis

Categoria	Ferramentas
Documentos	`create_document_from_upload`, `create_document_from_template`, `get_document_details`, `list_documents`, `update_document`, `delete_document`, `add_extra_document`, `place_signatures`
Modelos	`list_templates`, `get_template_details`, `create_template`, `update_template`, `delete_template`
Signatários	`add_signer`, `update_signer`, `get_signer_details`, `delete_signer`, `sign_in_batch`
Consultas	`create_person_background_check`, `create_company_background_check`, `get_background_check_status`
Webhooks	`create_webhook`, `delete_webhook`, `manage_webhook_headers`
Carimbo do tempo	`add_timestamp`

Deploy em produção (Docker + Traefik)

O repositório inclui um setup pronto com Docker Compose e Traefik (TLS automático via Let's Encrypt):

terminalbash

git clone https://github.com/ZapSign/api-mcp.git
cd api-mcp
cp .env.example .env      # configure o token e o domínio
chmod +x setup-traefik.sh
./setup-traefik.sh
docker-compose up -d

Checklist de produção: rate limiting ativo, logs estruturados, monitoração do /health, HTTPS obrigatório e restrição de acesso à URL do SSE (rede privada, allowlist de IP ou autenticação no proxy).

Boas práticas de segurança

Menor privilégio: use tokens de workspace em vez do token principal quando o agente só precisa de um subconjunto de documentos.
Rotação: revogue e regenere o token no painel se houver qualquer suspeita de exposição.
Aprovação humana: mantenha a confirmação de ferramenta ativada no cliente para operações destrutivas (delete_document, delete_signer).
Auditoria: todos os documentos criados via MCP aparecem no painel da ZapSign com trilha de auditoria normal — revise periodicamente.
Nunca exponha o token ao LLM: ele vive no .env/config do servidor; o modelo só vê as ferramentas.

Próximos passos

Conecte seu cliente: Claude, ChatGPT, Cursor, Codex ou Gemini.
Quickstart da API — entenda o que as ferramentas chamam por baixo.
Repositório no GitHub — issues e contribuições são bem-vindas.