How do I install Signwell?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Signwell need an API key?

The publisher lists these environment variables: SIGNWELL_API_KEY.

What transport does Signwell use?

Signwell runs locally over stdio.

When was Signwell last checked?

Last checked 2026-11-08. Send documents for e-signature, track signing, and manage templates in SignWell from any MCP client.

Signwell MCP server

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).

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.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

Install dependencies: npm install
Bundle the CLI entrypoint (required for MCP client configs): npm run build
Configure credentials: node build/index.js setup (or npx @signwell/mcp setup once published)
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).

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

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 [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} 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:

{{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

Signwell

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions