Skip to main content
Glama

SignWell MCP Server

Model Context Protocol server that orchestrates SignWell's e-signature workflows.

Prerequisites

  • Node.js v18 or newer.

  • A SignWell API key with document access (SIGNWELL_API_KEY environment variable).

  • Optional overrides:

    • SIGNWELL_API_BASE_URL for non-production endpoints.

    • SIGNWELL_API_TIMEOUT_MS to tweak HTTP client timeouts (default 90000 ms; CLI flag --timeout on setup skips env prompts and writes this override).

Related MCP server: ConnectWise API Gateway MCP Server

Setup

  1. Install dependencies if you have not already:

    npm install
  2. Bundle the CLI so MCP clients point at the build output:

    npm run build
  3. Run the wizard and follow the prompts:

    node build/index.js setup
    • Stores your SignWell secrets in ~/.config/signwell-mcp/env on Linux, ~/Library/Application Support/SignWell/MCP/env on macOS, or %APPDATA%/SignWell/MCP/env on Windows with 0700/0600 permissions.

    • Automatically updates Claude Desktop, Claude Code, Cursor, and OpenCode configuration files (backups are captured before each write) so you do not have to hunt for platform paths.

    • Client targets:

      • Claude Code: ~/.claude.json at mcpServers.signwell

      • Claude Desktop: claude_desktop_config.json at mcpServers.signwell

      • Cursor: ~/.cursor/mcp.json at mcpServers.signwell

      • OpenCode: ~/.config/opencode/opencode.json at mcp.signwell (Windows: %USERPROFILE%\.config\opencode\opencode.json)

    • Uses each client's documented JSON wrapper and STDIO/local server shape so the server is visible after the client restarts.

    • If a previous Claude Code install wrote the stale ~/.claude/mcp.json servers.signwell entry, rerunning setup backs up that legacy file and removes only the stale SignWell entry after writing the correct ~/.claude.json config.

    • Use --print (or -p) to preview outputs without writing to disk, and --yes --api-key=... for non-interactive runs (CI, devcontainers, etc.).

    • Pass --clients=claude-desktop,cursor to limit which MCP clients the wizard configures; omit for "all". Use --timeout=<ms> only if you need a non-default HTTP timeout.

    • After bundling (npm run build) and publishing the package, end users can invoke the same wizard with npx @signwell/mcp setup. Installing globally also enables invoking signwell-mcp setup directly.

Manual exports

Prefer to manage env vars yourself? Export the required values before running the server:

export SIGNWELL_API_KEY="your_api_key"
# export SIGNWELL_API_BASE_URL="https://www.signwell.com/api/v1"   # optional

Installation (npm)

Once the package is published to npm (GitHub: Bidsketch/signwell-mcp):

  • Run the setup wizard without installing anything globally:

    npx @signwell/mcp setup
  • Install globally if you prefer a persistent binary:

    npm install -g @signwell/mcp
    signwell-mcp setup

After configuration, start the MCP server via signwell-mcp (requires Node.js v18+).

The signwell-mcp.mcpb file is a separate Claude Desktop extension artifact. It uses the root manifest.json and should be rebuilt for releases after running npm run build.

Local Development Workflow

  1. Install dependencies: npm install

  2. Bundle the CLI entrypoint (required for MCP client configs): npm run build

  3. Configure credentials: node build/index.js setup (or npx @signwell/mcp setup once published)

  4. Start the MCP server locally: npm start (runs node build/index.js)

  5. Open another terminal to run tests and linters before committing:

    npm test
    npm run typecheck
    npm run lint
  6. When using MCP inspector or other clients, point them at npm start (stdio).

Running the Server

  • Development entrypoint (stdio transport):

    SIGNWELL_API_KEY="$SIGNWELL_API_KEY" npm start
    # or run directly:
    SIGNWELL_API_KEY="$SIGNWELL_API_KEY" node build/index.js
  • CLI helpers:

    • node build/index.js --help prints usage and env expectations.

    • node build/index.js --version prints the current build.

    • node build/index.js setup launches the setup wizard described above when working from source.

    • Once the package is bundled/published, npx @signwell/mcp setup runs the wizard and SIGNWELL_API_KEY=... npx @signwell/mcp starts the server via the packaged binary (global installs can call signwell-mcp ... directly).

MCP Inspector

Use the MCP inspector to exercise tools locally:

npx @modelcontextprotocol/inspector node build/index.js

Tests

Run the quality gates in order:

npm test
npm run typecheck
npm run lint
npm run format

Demo

Sample MCP inspector session (sanitized IDs):

  1. Create Draft

    Tool: document_create
    Input: {
      "name": "Sales Agreement",
      "recipients": [{ "id": "1", "name": "Alice Example", "email": "alice@example.com" }],
      "files": [{ "name": "agreement.pdf", "file_url": "https://files.example.com/agreement.pdf" }]
    }
    Output:
    {
      "ok": true,
      "type": "document_create",
      "message": "Document draft created.",
      "data": {
        "id": "doc_123",
        "status": "draft"
      }
    }
  2. Send Draft

    Tool: document_send_draft
    Input: { "document_id": "doc_123", "confirm_send": true }
    Output:
    {
      "ok": true,
      "type": "document_send_draft",
      "message": "Send request accepted.",
      "data": { "id": "doc_123", "status": "Sent" },
      "warnings": ["Status may update asynchronously. If this response still shows Draft, call document_get after a few seconds; do not send again. Recipient send_email is an embedded-signing setting, not an email-delivery receipt."]
    }
  3. Check Status

    Tool: document_get
    Input: { "document_id": "doc_123" }
    Output:
    {
      "ok": true,
      "type": "document_get",
      "message": "Fetched document status.",
      "data": {
        "id": "doc_123",
        "status": "completed",
        "recipients": [{ "email": "alice@example.com", "status": "signed" }]
      }
    }
  4. Completed PDF

    Tool: document_completed_pdf
    Input: { "document_id": "doc_123" }
    Output:
    {
      "ok": true,
      "type": "document_completed_pdf",
      "data": {
        "pdf_url": "https://signwell-downloads.example.com/doc_123.pdf"
      }
    }

Privacy Policy

This section describes the data practices of the SignWell MCP Server.

Data Collection

  • The MCP server itself does not collect, transmit, or store any personal data or usage analytics.

  • Your SignWell API key is stored locally on your machine with restrictive file permissions (0600) in platform-specific secure locations:

    • macOS: ~/Library/Application Support/SignWell/MCP/env

    • Linux: ~/.config/signwell-mcp/env

    • Windows: %APPDATA%/SignWell/MCP/env

Usage & Storage

  • Files provided via file_store are held temporarily in memory with a 60-minute TTL and are cleared automatically.

  • All in-memory file data is also cleared on server restart.

  • No persistent data storage exists beyond the credential file created during setup.

Third-Party Sharing

  • The MCP server does not share data with any third parties.

  • All API communication goes directly between your machine and SignWell's servers (https://www.signwell.com/api/v1).

Telemetry & Analytics

  • The server does not collect, transmit, or store usage analytics or telemetry of any kind.

Data Retention

  • In-memory file storage is cleared on server restart or after the 60-minute TTL expires.

  • No persistent data is retained beyond the local credential configuration file.

Contact

For privacy inquiries, contact support@signwell.com or open an issue at github.com/Bidsketch/signwell-mcp/issues.

See also the hosted privacy policy at https://www.signwell.com/privacy/.

Resources

  • MCP resources: document://{id} and template://{id} expose read-only JSON snapshots that reuse the same normalization logic as the tools, so inspectors or other MCP clients can browse previously created assets quickly.

Attaching Files & Draft Safety

  • document_create and template_create_document always set draft: true, ensuring nothing is emailed until you intentionally call document_send_draft.

  • Supply files via the files array using either file_url (public URL or the link your MCP client provides when you @-attach a file in UIs like Claude Desktop), file_base64, or resource_uri. When a resource_uri is provided the MCP server automatically calls resources/read to pull the attachment bytes and forwards them to SignWell's /api/v1/documents/ endpoint.

Document Corrections and Signing Dates

  • Recipient names: pass name in each document_create recipient. Legacy first_name and last_name are combined when name is omitted. Set test_mode: true to create a non-binding test document without API billing.

  • Draft settings: document_send_draft accepts optional updates such as name, subject, message, expires_in, and reminders alongside confirm_send: true. Omitted settings are preserved. It cannot edit recipients, files, or fields, or save changes without sending.

  • Sent recipients: call document_get for recipient IDs, then document_update_recipients with document_id, confirm_update: true, and recipients: [{ "id": "<returned recipient ID>", "name": "Correct Name", "email": "signer@example.com" }]. Include both name and email, keeping the unchanged value. Only recipients who have not started signing on sent/viewed/pending/bounced documents can be changed. Non-embedded recipients receive a new notification email; embedded recipients follow their existing send_email setting.

  • Withdraw a document: document_delete with document_id and confirm_delete: true deletes the document and cancels signing in progress. Delete an incorrect request before creating a replacement to avoid two live requests.

  • Send status: a successful send returns “Send request accepted” and attempts one status refresh. If the refresh fails, the accepted send remains successful. Status may still lag; use document_get after a few seconds instead of resending. send_email is an embedded-signing option, not a delivery receipt.

For an automatically populated, locked signing date, use these existing SignWell text tags with text_tags: true:

{{signature:1:y}} {{autofill_date_signed:1:y}}
{{signature:2:y}} {{date:2:y::::::y}}

Both date forms lock the signing date. Plain {{date:1:y}} remains editable for dates the signer should choose. Text-tag parsing is asynchronous: inspect fields with document_get after processing. See SignWell's text-tag options, recipient updates, and update-and-send limitations.

Available Scripts

Script

Purpose

npm start

Execute the MCP server entrypoint over stdio (after npm run build).

npm test

Run the test suite.

npm run typecheck

Type-check the project with tsc --noEmit.

npm run lint

Lint source and tests using Biome.

npm run format

Apply repository formatting conventions via Biome.

npm run build

Produce an ESM bundle at build/index.js using esbuild.

Directory Layout

.
├── src/                # MCP server source (entrypoint + domain modules)
│   └── setup/          # Interactive setup wizard for MCP client configuration
├── test/               # Test suites
├── build/              # Bundled output (ignored in releases)
├── biome.json          # Biome lint/format configuration
└── tsconfig.json       # TypeScript compiler configuration

Available Tools

14 tools
document_completed_pdfC

Fetch the completed PDF. Use mode: 'base64' to get content for displaying in an artifact or chat (embed as data:application/pdf;base64,{pdf_base64}). Default 'url' mode returns a shareable link.

Inputs: document_id (required), mode, file_format, save_to_path, +1 more.

document_createA

Create a SignWell document (always created as a draft).

CRITICAL RULES:

  • Do NOT read, parse, extract, or verify file contents before uploading. The user already knows what is in the file.

  • Do NOT convert files between formats (e.g. do NOT convert .docx to .pdf). SignWell handles conversion automatically.

  • The user will place signature fields in the SignWell editor. Just upload the file and return the editor link.

SUPPORTED FILE TYPES: .pdf, .doc, .docx, .pages, .ppt, .pptx, .key, .xls, .xlsx, .numbers, .jpg, .jpeg, .png, .tiff, .tif, .webp, .html, .htm

WORKFLOW FOR USER'S EXISTING FILES:

  1. file_store (call with NO arguments to open native file picker) → returns file_token

  2. document_create (pass file_token in files array) → creates draft, returns editor_url

WORKFLOW FOR CLAUDE-GENERATED FILES:

  1. document_create with content_text directly (RECOMMENDED) → MCP server converts to DOCX automatically Pass plain text or Markdown as content_text. The server generates a DOCX file without base64 overhead.

  2. document_create with file_base64 directly (skip file_store) → creates draft, returns editor_url Do NOT write the file to disk and pass a file_path — sandbox paths are inaccessible. Use file_base64.

    Example using content_text: { "name": "Service Agreement", "recipients": [{"id": "1", "email": "client@example.com"}], "files": [{"name": "agreement.docx", "content_text": "# Service Agreement\n\nThis agreement between..."}] }

FILE ACCESS: Chat attachments and sandbox paths (/home/claude, /mnt/user-data) are inaccessible to the MCP server. Do NOT use resource_uri or sandbox file_path values. For existing files, call file_store with no arguments to open the native file picker.

REQUIRED PARAMETERS:

  1. name: Document name

  2. recipients: Array with at least one object containing "id" and "email"

  3. files: Array with at least one file object containing:

    • "name": Filename (e.g., "contract.docx")

    • One content source (in order of preference):

      • "content_text": Plain text or Markdown to auto-convert to DOCX (RECOMMENDED for Claude-generated content)

      • "file_token": Token from file_store (recommended for user files)

      • "file_url": Public URL to the file

      • "file_base64": Base64-encoded file content

      • "resource_uri": MCP resource URI

EXAMPLE (docx via file_token — most common): { "name": "NDA Agreement", "recipients": [{"id": "1", "email": "signer@example.com"}], "files": [{"name": "nda.docx", "file_token": ""}] }

EXAMPLE (pdf with text tags): { "name": "Contract", "text_tags": true, "recipients": [{"id": "1", "email": "signer@example.com"}], "files": [{"name": "contract.pdf", "file_token": ""}] }

TEXT TAGS (optional): Set text_tags: true only if the document already contains signature placeholders like {{signature:1:y}}. The recipient "id" MUST match the number in text tags (id:"1" matches {{signature:1:y}}).

Inputs: name (required), files (required), recipients (required), message, +15 more.

document_getB
Read-only

Fetch the latest status for a SignWell document.

Inputs: document_id (required).

document_listB
Read-only

List SignWell documents with optional filtering (status, archived, search).

Inputs: page, search, status, archived, +3 more.

document_send_draftC

Send a previously created draft document (requires confirm_send).

Inputs: document_id (required), message, confirm_send.

document_send_reminderB

Send a reminder email for a document (optionally to a specific recipient).

Inputs: document_id (required), message, recipient_email.

file_storeA

Store a user's existing file for upcoming SignWell requests. Returns a file_token you can pass to document/template tools.

IMPORTANT: This tool is for the USER'S EXISTING FILES only. Do NOT read, parse, or convert the file — upload it as-is.

HOW TO PROVIDE THE FILE (in order of preference):

  1. No arguments — Opens a native OS file picker dialog. USE THIS BY DEFAULT. Simply call file_store with no arguments and the user will select the file themselves.

  2. file_path — Only if the user explicitly provides a local path on their computer (e.g. ~/Documents/contract.docx).

  3. file_url — A publicly accessible URL to the file.

CHAT ATTACHMENTS: When a user uploads/attaches a file in the chat, DO NOT use resource_uri — those are sandboxed and inaccessible. Instead, call file_store with NO arguments to open the native file picker.

CLAUDE-GENERATED FILES: If YOU created the file content (e.g. generated a PDF), do NOT use file_store. Pass file_base64 directly to document_create instead.

Inputs: name, file_url, file_path, resource_uri.

file_validate_text_tagsA
Read-only

Validate text tags in a PDF before creating a template or document.

RECOMMENDED WORKFLOW: file_store → file_validate_text_tags → template_create/document_create

Accepts a PDF via file_token (from file_store), file_base64, file_url, or resource_uri. Set use_picker: true to open a native file picker when no file input is provided. Extracts text from the PDF and checks for valid SignWell text tags like {{signature:1:y}}.

Returns:

  • Whether text is extractable from the PDF

  • List of valid tags found

  • List of malformed tags (if any)

  • Signer numbers referenced

  • Recommendations for fixing issues

Inputs: file_url, file_token, use_picker, file_base64, +1 more.

template_createA

Create a SignWell template for reusable signature documents.

RECOMMENDED WORKFLOW:

  1. file_store (provide file_path, file_url, or resource_uri) → returns file_token

  2. file_validate_text_tags (pass file_token) → validates tags are extractable

  3. template_create (pass file_token in files array) → creates the template

REQUIRED PARAMETERS (both are mandatory):

  • files: Array with at least one file object containing:

    • "name": Filename (e.g., "template.docx")

    • One content source (in order of preference):

      • "content_text": Plain text/Markdown to auto-convert to DOCX (RECOMMENDED for generated content)

      • "file_token": Token from file_store (recommended for uploaded files)

      • "file_base64": Base64-encoded file content

      • "file_url": Public URL to the file

      • "resource_uri": MCP resource URI

  • placeholders: Array with at least one placeholder object containing "id" and "name"

STEP-BY-STEP EXAMPLE (using file_token):

  1. Call file_store with {"file_path": "/path/to/doc.pdf"} → get file_token

  2. Call file_validate_text_tags with {"file_token": "..."} → confirm tags are valid

  3. Call this tool with: { "name": "My Template", "files": [{"name": "doc.pdf", "file_token": ""}], "placeholders": [{"id": "1", "name": "Signer"}], "text_tags": true }

ALTERNATIVE (inline base64): { "name": "My Template", "files": [{"name": "doc.pdf", "file_base64": "JVBERi0xLjQK..."}], "placeholders": [{"id": "1", "name": "Signer"}], "text_tags": true }

TEXT TAGS (when text_tags: true): Your PDF must contain these literal text strings as SELECTABLE TEXT (not images):

  • {{signature:1:y}} - Signature field for placeholder id "1"

  • {{date:1:y}} - Date field for placeholder id "1"

  • {{text:1:y:Label}} - Text field with label

  • {{initial:1:y}} - Initials field

The number in the tag (1, 2, etc.) MUST match a placeholder "id" in your request.

CRITICAL: Text tags must be SELECTABLE/SEARCHABLE text in the PDF, not rendered as images or graphics. When generating PDFs programmatically, use text drawing methods (e.g., drawString) with standard fonts. To verify: open the PDF and try to select/copy the tag text with your mouse. If you can't select it, SignWell can't parse it.

MULTI-SIGNER EXAMPLE: { "name": "Contract", "files": [{"name": "contract.pdf", "file_base64": "JVBERi0xLjQK...actual base64 here..."}], "placeholders": [ {"id": "1", "name": "Client"}, {"id": "2", "name": "Vendor"} ], "text_tags": true }

For this example, the PDF should contain: {{signature:1:y}} for Client and {{signature:2:y}} for Vendor.

COMMON ERRORS:

  • Empty arguments {} = You forgot to include files and placeholders arrays

  • "fields": [] in response = PDF doesn't contain valid text tags, or text_tags wasn't set to true

Inputs: name, draft, files, fields, +18 more.

template_create_documentA

Create and send a document from a template. Templates are pre-configured and ready to send, so this tool sends the document for signing by default.

IMPORTANT: When a user asks to "send a template" or "send a document from a template", the document will be sent immediately for signing. Set draft: true ONLY if the user explicitly asks to create a draft or review before sending.

REQUIRED:

  • template_id: The template ID to create the document from

  • recipients: Array of recipient objects, each with:

    • id: Unique identifier for this recipient (e.g., "recipient_1")

    • placeholder_name: Name of the template placeholder to assign (must match exactly)

    • email: Recipient's email address

    • name: (optional) Recipient's display name

Example: { "template_id": "abc123", "recipients": [{ "id": "recipient_1", "placeholder_name": "Client", "email": "client@example.com", "name": "John Doe" }] }

Inputs: recipients (required), template_id (required), name, draft, +14 more.

template_deleteC
Destructive

Delete a SignWell template.

Inputs: template_id (required).

template_getA
Read-only

Fetch an individual SignWell template by ID.

Inputs: template_id (required).

template_listB
Read-only

List SignWell templates with pagination.

Inputs: page, per_page.

template_updateA

Update an existing SignWell template. Only provide fields you want to change.

Inputs: template_id (required), name, draft, files, +19 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct action: document creation vs. template creation, file validation vs. file storage, etc. There is no ambiguity; even similar tools like document_send_draft and document_send_reminder have clearly different purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., document_create, template_list, file_store) using snake_case. No deviations or mixed conventions.

    Tool Count5/5

    With 14 tools, the count is well within the 3-15 ideal range. Each tool addresses a specific step in the document signing workflow without being excessive or lacking.

    Completeness4/5

    The tool set covers core CRUD operations for documents and templates, file handling, validation, sending, reminders, and PDF retrieval. A minor gap is the absence of a document_delete tool, but deletion may be intentionally omitted as it's not a common part of the workflow.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables interaction with the Tradovate API for managing trading contracts, positions, orders, and accounts.
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      A Model Context Protocol server that provides a comprehensive interface for interacting with the ConnectWise Manage API, simplifying API discovery, execution, and management for both developers and AI assistants.
      13 npm
      19
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      This is an auto-generated Model Context Protocol server that enables interaction with Gmail API, allowing applications to access and manipulate Gmail data through structured operations defined in the OpenAPI specification.
      -