@mindops/zapsign-mcp

Model Context Protocol server that exposes the ZapSign REST API as MCP tools. Plug it into any MCP-aware host (Claude Desktop, VS Code, Cursor, your own SDK app) and let an LLM drive document workflows: create documents, manage signers, fill DOCX templates, run background checks, manage webhooks.

What's covered

Tools are grouped by ZapSign resource. The set tracks the public REST API one-to-one; each tool wraps exactly one endpoint.

• Documents — create from PDF URL / base64 / template, list, detail, update, delete, reorder display, place signatures, oneclick, extra docs, signer activity log
• Signers — add, update, detail, delete, sign in batch, refuse, refuse by user, reset auth attempts, resend notifications, verification details, signer groups
• Templates — create from DOCX, update form fields, list, detail, update, delete
• Users — create, list, delete, plan info
• Webhooks — create, delete (event payloads are reference docs, not API endpoints)
• Auth (JWT) — get token, refresh token (alternative to static API token)
• Background checks — create person/company check, list, detail
• Timestamp — apply timestamp to a signed PDF, or to an arbitrary PDF without altering signatures
• Validation — verify a signed PDF
• Partner — partner company management, payment status updates, plan-usage CSV report

Install

After publishing to the registry:

npm install -g @mindops/zapsign-mcp
# or run on demand with npx (no global install):
npx -y @mindops/zapsign-mcp

Local install (before publish)

cd /path/to/zapsign-mcp
npm install
npm run build
npm link            # exposes `zapsign-mcp` on $PATH globally

First-time publish

The package targets the @mindops scope on npmjs.org with restricted access. To publish:

npm login                      # authenticate against registry.npmjs.org
npm publish --access restricted   # or just `npm publish` — restricted is the publishConfig default

If the @mindops org doesn't yet exist on npm, create it first at https://www.npmjs.com/org/create.

Configure

Create a .env file (or set environment variables in your MCP host config):

ZAPSIGN_API_TOKEN=your-permanent-system-user-token
ZAPSIGN_ENV=production       # or 'sandbox' for the test environment

Recommended: a System User permanent token (Configurações → API → Tokens in the ZapSign panel). User-bound tokens expire and break automation.

Use from an MCP host

Claude Desktop / Claude Code

Add to your MCP config (typically ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zapsign": {
      "command": "npx",
      "args": ["-y", "@mindops/zapsign-mcp"],
      "env": {
        "ZAPSIGN_API_TOKEN": "...",
        "ZAPSIGN_ENV": "production"
      }
    }
  }
}

VS Code / Cursor

Same shape — drop it into the MCP servers section of your settings.

Locally during development

npm install
npm run build
ZAPSIGN_API_TOKEN=... ZAPSIGN_ENV=sandbox node dist/index.js

The server speaks stdio; connect with any MCP client to introspect tools.

Tool naming conventions

• snake_case names matching ZapSign's resource terminology (create_document, add_signer, delete_template, etc.)
• Field names in tool inputs preserve ZapSign's API spelling (phone_country, phone_number, auth_mode, url_pdf...) so the underlying request body is exactly what the API expects.
• Path parameters appear as top-level fields with the same name (doc_token, signer_token, template_token).

Development

npm install
npm run typecheck
npm run build

Add new endpoints by creating a definition in src/tools/<resource>.ts and re-running npm run build. Each tool is a thin wrapper:

registerTool(server, client, {
  name: 'create_document',
  description: 'Create a new document from a public PDF URL.',
  inputSchema: z.object({ /* fields */ }),
  handler: async (input, { client }) => client.post('/docs/', input),
});

The helper handles error envelope formatting and JSON-stringification for the MCP transport.

Versioning

This package tracks the ZapSign v1 API. ZapSign versions their endpoints behind /api/v1/; if/when v2 ships, this server will gain a parallel module rather than replace v1 in place.

License

Proprietary (MindOps internal). Contact MindOps before redistributing.