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 (SIGNWELLAPIKEY environment variable).
• Optional overrides:
• SIGNWELLAPIBASE_URL for non-production endpoints.
• SIGNWELLAPITIMEOUT_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)

1. Install dependencies if you have not already:

npm install

1. Bundle the CLI so MCP clients point at the build output:

npm run build

1. 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: claudedesktopconfig.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= 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

1. When using MCP inspector or other clients, point them at npm start (stdio).

Running the Server

• Development entrypoint (stdio transport):

Shortened. The full README is on GitHub.