mcp-signwell
OfficialManage end-to-end e-signature workflows in SignWell — upload files, create and send documents, track signing status, retrieve completed PDFs, and manage reusable templates.
Store & validate files:
file_store(native picker, path, URL, or resource) andfile_validate_text_tagsto check PDF text tags like{{signature:1:y}}before use.Create documents:
document_createbuilds always-draft documents fromcontent_text, base64, tokens, or URLs, with recipients, CCs, metadata, reminders, expiration, signing order, and embedded-signing options.Send & follow up:
document_send_draft(requiresconfirm_send) sends a draft;document_send_remindernudges all or one recipient.Monitor:
document_list(filter by status, archive, search, dates) anddocument_getfor live status and recipient details.Retrieve output:
document_completed_pdfreturns a URL, base64, or saved file, as PDF or ZIP, with optional audit page.Templates:
template_create,template_update,template_get,template_list, andtemplate_deletefor reusable signed documents with placeholders, fields, checkbox groups, labels, and languages.Send from templates:
template_create_documentgenerates and sends (or drafts) a document from a template, assigning recipients to placeholders with per-recipient subject, message, passcode, and email timing.Safety defaults: drafts are never emailed until explicitly sent, and files are held in memory with a 60-minute TTL.
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_KEYenvironment variable).Optional overrides:
SIGNWELL_API_BASE_URLfor non-production endpoints.SIGNWELL_API_TIMEOUT_MSto tweak HTTP client timeouts (default 90000 ms; CLI flag--timeoutonsetupskips env prompts and writes this override).
Related MCP server: ConnectWise API Gateway MCP Server
Setup
Interactive Wizard (recommended)
Install dependencies if you have not already:
npm installBundle the CLI so MCP clients point at the build output:
npm run buildRun the wizard and follow the prompts:
node build/index.js setupStores your SignWell secrets in
~/.config/signwell-mcp/envon Linux,~/Library/Application Support/SignWell/MCP/envon macOS, or%APPDATA%/SignWell/MCP/envon Windows with0700/0600permissions.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.jsonatmcpServers.signwellClaude Desktop:
claude_desktop_config.jsonatmcpServers.signwellCursor:
~/.cursor/mcp.jsonatmcpServers.signwellOpenCode:
~/.config/opencode/opencode.jsonatmcp.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.jsonservers.signwellentry, rerunning setup backs up that legacy file and removes only the stale SignWell entry after writing the correct~/.claude.jsonconfig.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,cursorto 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 withnpx @signwell/mcp setup. Installing globally also enables invokingsignwell-mcp setupdirectly.
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" # optionalInstallation (npm)
Once the package is published to npm (GitHub: Bidsketch/signwell-mcp):
Run the setup wizard without installing anything globally:
npx @signwell/mcp setupInstall 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
Install dependencies:
npm installBundle the CLI entrypoint (required for MCP client configs):
npm run buildConfigure credentials:
node build/index.js setup(ornpx @signwell/mcp setuponce published)Start the MCP server locally:
npm start(runsnode build/index.js)Open another terminal to run tests and linters before committing:
npm test npm run typecheck npm run lintWhen 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.jsCLI helpers:
node build/index.js --helpprints usage and env expectations.node build/index.js --versionprints the current build.node build/index.js setuplaunches the setup wizard described above when working from source.Once the package is bundled/published,
npx @signwell/mcp setupruns the wizard andSIGNWELL_API_KEY=... npx @signwell/mcpstarts the server via the packaged binary (global installs can callsignwell-mcp ...directly).
MCP Inspector
Use the MCP inspector to exercise tools locally:
npx @modelcontextprotocol/inspector node build/index.jsTests
Run the quality gates in order:
npm test
npm run typecheck
npm run lint
npm run formatDemo
Sample MCP inspector session (sanitized IDs):
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" } }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."] }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" }] } }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/envLinux:
~/.config/signwell-mcp/envWindows:
%APPDATA%/SignWell/MCP/env
Usage & Storage
Files provided via
file_storeare 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}andtemplate://{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_createandtemplate_create_documentalways setdraft: true, ensuring nothing is emailed until you intentionally calldocument_send_draft.Supply files via the
filesarray using eitherfile_url(public URL or the link your MCP client provides when you@-attach a file in UIs like Claude Desktop),file_base64, orresource_uri. When aresource_uriis provided the MCP server automatically callsresources/readto pull the attachment bytes and forwards them to SignWell's/api/v1/documents/endpoint.
Document Corrections and Signing Dates
Recipient names: pass
namein eachdocument_createrecipient. Legacyfirst_nameandlast_nameare combined whennameis omitted. Settest_mode: trueto create a non-binding test document without API billing.Draft settings:
document_send_draftaccepts optional updates such asname,subject,message,expires_in, andremindersalongsideconfirm_send: true. Omitted settings are preserved. It cannot edit recipients, files, or fields, or save changes without sending.Sent recipients: call
document_getfor recipient IDs, thendocument_update_recipientswithdocument_id,confirm_update: true, andrecipients: [{ "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 existingsend_emailsetting.Withdraw a document:
document_deletewithdocument_idandconfirm_delete: truedeletes 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_getafter a few seconds instead of resending.send_emailis 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 |
| Execute the MCP server entrypoint over stdio (after |
| Run the test suite. |
| Type-check the project with |
| Lint source and tests using Biome. |
| Apply repository formatting conventions via Biome. |
| Produce an ESM bundle at |
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 configurationAvailable Tools
14 toolsdocument_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:
file_store (call with NO arguments to open native file picker) → returns file_token
document_create (pass file_token in files array) → creates draft, returns editor_url
WORKFLOW FOR CLAUDE-GENERATED FILES:
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.
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:
name: Document name
recipients: Array with at least one object containing "id" and "email"
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_getBRead-only
Fetch the latest status for a SignWell document.
Inputs: document_id (required).
document_listBRead-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):
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.
file_path — Only if the user explicitly provides a local path on their computer (e.g. ~/Documents/contract.docx).
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_tagsARead-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:
file_store (provide file_path, file_url, or resource_uri) → returns file_token
file_validate_text_tags (pass file_token) → validates tags are extractable
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):
Call file_store with {"file_path": "/path/to/doc.pdf"} → get file_token
Call file_validate_text_tags with {"file_token": "..."} → confirm tags are valid
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_deleteCDestructive
Delete a SignWell template.
Inputs: template_id (required).
template_getARead-only
Fetch an individual SignWell template by ID.
Inputs: template_id (required).
template_listBRead-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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
PandaDoc MCP server for creating, sending, signing, and tracking PandaDoc documents.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Hosted MCP server for Dropbox Sign — signature requests, templates, and account for AI agents.
Create documents and reusable templates, request signatures, and track approvals — for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables interaction with the Tradovate API for managing trading contracts, positions, orders, and accounts.1MIT
- FlicenseNot gradedqualityCmaintenanceA 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 npm19-
- AlicenseAqualityDmaintenanceModel Context Protocol (MCP) server for BoldSign API14154 npm7MIT
- FlicenseNot gradedqualityDmaintenanceThis 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.-