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).
Setup
Interactive Wizard (recommended)
-
Install dependencies if you have not already:
npm install -
Bundle the CLI so MCP clients point at the build output:
npm run build -
Run the wizard and follow the prompts:
node build/index.js setup- Stores 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.signwell - Claude Desktop:
claude_desktop_config.jsonatmcpServers.signwell - Cursor:
~/.cursor/mcp.jsonatmcpServers.signwell - OpenCode:
~/.config/opencode/opencode.jsonatmcp.signwell(Windows:%USERPROFILE%\.config\opencode\opencode.json)
- Claude Code:
- 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.
- Stores your SignWell secrets in
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
-
Install dependencies:
npm install -
Bundle the CLI entrypoint (required for MCP client configs):
npm run build -
Configure 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 lint -
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 --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.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):
-
Create Draft
Tool: document_create Input: { "name": "Sales Agreement", "recipients": [{ "id": "1", "name": "Alice Example", "email": "[email protected]" }], "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": "[email protected]", "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/env - Linux:
~/.config/signwell-mcp/env - Windows:
%APPDATA%/SignWell/MCP/env
- macOS:
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 [email protected] 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": "[email protected]" }]. 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
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
