addsign-mcp

# addsign-mcp

MCP server for [AddSign](https://addsign.io) — lets AI agents send documents
for signature, track signing status, remind signers, and download signed,
hash-verifiable PDFs.

Stateless by design: it speaks only AddSign's public v1 API with **your** API
key. No database access, no shared secrets. Revoking the key at
[addsign.io/settings/api](https://addsign.io/settings/api) kills the
integration instantly.

## Setup

1. Create an API key at **addsign.io → Settings → API Keys** (free on every
   plan; Free includes 8 documents/month).
2. Set it in the environment — never in prompts or config committed to git:

```bash
export ADDSIGN_API_KEY=sk_...
```

### Claude Code

```bash
claude mcp add addsign --env ADDSIGN_API_KEY=sk_... -- npx -y addsign-mcp
```

(Until the npm package is published, point at a checkout instead:
`claude mcp add addsign --env ADDSIGN_API_KEY=sk_... -- node /path/to/simple-sign/mcp/dist/index.js`)

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "addsign": {
      "command": "node",
      "args": ["/path/to/simple-sign/mcp/dist/index.js"],
      "env": { "ADDSIGN_API_KEY": "sk_..." }
    }
  }
}
```

### Environment

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `ADDSIGN_API_KEY` | yes | — | Your AddSign API key (`sk_...`) |
| `ADDSIGN_BASE_URL` | no | `https://addsign.io` | Point at a different deployment |

## Tools

| Tool | Kind | What it does |
|---|---|---|
| `list_templates` | read | Templates + the signer roles each expects + field summary |
| `send_for_signature` | write | Create from template + email signers; idempotent via `request_id` |
| `check_status` | read | Document + per-signer state + recent audit events |
| `download_signed` | read | 5-minute signed URL + the ledger's SHA-256 for verification |
| `remind` | write | Nudge pending signers (4h per-signer server-side cooldown) |
| `list_documents` | read | Paginated document list, filterable by status |

No destructive tools: an agent cannot cancel or delete a legal document
through this server.

## A typical agent flow

```
list_templates                      → find "Contract to Lease", roles: [tenant_1, tenant_2]
send_for_signature {template_id,
  signers: [Artem…, Valeria…],
  request_id: <uuid>}               → document_id, status: pending, usage 3/8
check_status {document_id}          → Artem signed, Valeria viewed
remind {document_id, valeria@…}     → reminded (or skipped: reminded_recently)
download_signed {document_id}       → url + sha256 → fetch, verify, file it
```

## Error semantics

Every AddSign error carries a stable `error_code`; this server appends the
right next step for the agent. The two that matter most:

- `rate_limited` (429) — back off `retry_after` seconds, retry.
- `plan_limit_reached` (402) — **never retry**; the monthly cap resets on the
  1st or the human upgrades.

## Development

```bash
cd mcp
npm install
npm run build     # → dist/index.js
ADDSIGN_API_KEY=sk_... node dist/index.js
```