A SignWell API key with document access ( environment variable).
Send documents for e-signature, track signing, and manage templates in SignWell from any MCP client.
SIGNWELL_API_KEY
Last checked
2026-11-08
Stars
—
Tools
—
Uptime
—
SIGNWELL_API_KEY
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).
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/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.jsonservers.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:
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
Start the MCP server locally: npm start (runs node 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 --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).
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."]
}
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": "[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 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:
