convez.ai
MCP ServerIntegração & APIsAvançado
adamcfield

SignRequest MCP Server

adamcfield/signrequest-mcp-worker

API de assinatura digital como MCP server em Cloudflare Workers

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP remoto que expõe a API de assinatura digital SignRequest como 32 ferramentas para Claude, rodando em Cloudflare Workers. Suporta autenticação por bearer token (Claude Code/Desktop) e OAuth 2.1 (Claude.ai web), com recursos enterprise como bulk send, rollups de campanhas e extração de campos.

Instalação

$npx convez-ai adamcfield/signrequest-mcp-worker

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 dias
Versão
v1.4.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automatizar workflows de assinatura de documentos via Claude
  • Gerenciar campanhas em massa de pedidos de assinatura
  • Integrar processamento de documentos assinados em agents
  • Rastrear e cancelar solicitações de assinatura programaticamente

Veredito

Implementação sólida e production-ready de MCP server que bridgeia SignRequest em múltiplos ambientes Claude (Code, Desktop, web) com suporte robusto a OAuth e durable state. Excelente para equipes que precisam automação de assinatura digital em escala.

README

A tradução para o português deste README ainda está na fila.

signrequest-mcp-worker

The SignRequest e-signature API exposed as a remote MCP server, running as a Cloudflare Worker (Streamable HTTP + SSE). Built on the agents McpAgent.

It exposes thirty-two tools for the document-signing workflow — create & send signature requests, track, cancel/remind, delete, attach files, read documents, templates, events & teams — plus enterprise extras the raw API lacks: one-shot signer summaries, roster-wide campaign rollups, bulk send, flat field extraction, batch + auto-paginated reads, bounded polling, and a safe no-email signing-link generator. The tool definitions live in src/tools.ts and the SignRequest REST client in src/signrequest.ts; both are transport-agnostic, so every build shares an identical tool surface.

This repo ships two deployments from the same code:

WorkerAuthUse it fromEntry
signrequest-mcpstatic bearer tokenClaude Code, Claude Desktop, programmaticsrc/index.ts · wrangler.jsonc
signrequest-mcp-oauthOAuth 2.1 (single-user passphrase)Claude.ai web custom connectorsrc/oauth.ts · wrangler.oauth.jsonc

Status: both deployments typecheck, bundle, and deploy clean. Secrets are set via wrangler secret put and are never committed to this repo.


Contents


Architecture

client                         bearer worker (src/index.ts)
Claude Code / Desktop / curl ── Authorization: Bearer <MCP_AUTH_TOKEN> ──┐
                                                                          │
Claude.ai web ── OAuth 2.1 (passphrase) ── oauth worker (src/oauth.ts) ──┤
                                                                          ▼
                                              SignRequestMCP (McpAgent, Durable Object)
                                                • registerTools(server, client)  ← tools.ts
                                                • SignRequestClient               ← signrequest.ts
                                                                          │
                                                Authorization: Token <SIGNREQUEST_TOKEN>
                                                                          ▼
                                                          SignRequest REST API v1
  • McpAgent + Durable Object. MCP session state lives in a Cloudflare Durable Object (SQLite-backed, migration v1). Both workers bind it as MCP_OBJECT → class SignRequestMCP.
  • Shared tool layer. registerTools() and SignRequestClient are plain TypeScript with no Worker-specific imports, so the bearer worker, the OAuth worker, and a local stdio build all share them.
  • src/ai-stub.ts aliases the unused optional ai peer dependency of agents out of the bundle.

Endpoints

Bearer worker (signrequest-mcp):

MethodPathAuthPurpose
GET/noneHealth check → signrequest-mcp worker: ok
POST/mcpBearerMCP Streamable HTTP (modern clients)
GET/sseBearerMCP SSE (legacy clients)

OAuth worker (signrequest-mcp-oauth) — see OAuth worker.


Authentication

Bearer worker is gated by a shared bearer token (MCP_AUTH_TOKEN): fails closed (no secret → everything 401s), constant-time comparison, and the SignRequest token never leaves the Worker. Right for programmatic use, mcp-remote, Claude Code/Desktop.

OAuth worker implements OAuth 2.1 (PKCE + dynamic client registration) via @cloudflare/workers-oauth-provider, gated by a single shared passphrase (APP_PASSPHRASE) on the consent screen — the only model Claude.ai web accepts.


Tools

All tools call an external service (openWorldHint: true). "Sends email" means SignRequest dispatches real signing emails.

Create & send

signrequest_quick_create

Create a document and send the signature request in one call — the most common entry point. Write · sends email.

FieldTypeNotes
document source—exactly one of file_from_url, file_from_content (+ file_from_content_name), or template
file_from_urlstring (url)public URL SignRequest downloads — preferred for anything but tiny files
file_from_contentstringbase64 file contents — small files only
file_from_content_namestringfilename with extension, e.g. contract.pdf; required if file_from_content is set
templatestring (url)template resource URL to base the document on
signersSigner[]required, min 1 — see Signer
from_emailstring (email)sender; must belong to the token's team; falls back to SIGNREQUEST_FROM_EMAIL
from_email_name, subject, messagestringmessage allows limited HTML (a,b,i,em,strong,ul,ol,li,blockquote,code,abbr,acronym)
send_remindersbooleanauto-remind signers who haven't signed
whom | o | mom=only me, o=only others, mo=both
external_id, name, events_callback_urlstringyour ref id · display name · per-document webhook URL
disable_emailsbooleansuppress SignRequest status emails (with embedded signers = fully silent)
dry_runbooleanpreview who would be emailed; creates/sends nothing

signrequest_create_document

Create a document without sending it. Returns a document with a url/uuid you can pass to signrequest_send later. Write · emails no one. Accepts the document-source fields above plus external_id, name, events_callback_url.

signrequest_send

Send a signature request for an existing document. Write · sends email. Fields: document (resource URL, required), signers (required), from_email, from_email_name, subject, message, send_reminders, who.

Track & manage

ToolPurposeInputClass
signrequest_getGet one signature request — status, signers, who signed/declined/vieweduuidread-only
signrequest_listList signature requests (most recent first)page?, external_id?read-only
signrequest_cancelCancel a request; unsigned signers lose access. Only if not already fully signed/declineduuiddestructive, idempotent
signrequest_resendResend the signing email to signers who haven't signed (dry_run? previews)uuid, dry_run?write · sends email

Documents & templates

ToolPurposeInputClass
signrequest_get_documentGet a document — conversion status, signed-PDF URL, security hash, signing log (compact? = trimmed summary)uuid, compact?read-only
signrequest_list_documentsList documents (most recent first)page?, external_id?read-only
signrequest_delete_documentPermanently delete a document + its signature requests + stored fileuuiddestructive
signrequest_list_templatesList templates; use a template's resource URL as template abovepage?read-only
signrequest_get_templateGet one template by UUID — its fields and resource URLuuidread-only
signrequest_search_documentsFast search — filter by signer_emails, q, name, status (no blind paging)filtersread-only

Events & teams

ToolPurposeInputClass
signrequest_list_eventsList the webhook delivery log (signed/declined/viewed…), for auditingpage?read-only
signrequest_get_eventGet one event by UUIDuuidread-only
signrequest_list_teamsList teams the token can accesspage?read-only
signrequest_list_team_membersList members of accessible team(s)page?read-only

Attachments

ToolPurposeInputClass
signrequest_add_document_attachmentAttach an extra file to a document (file_from_url or base64) — not a signature fielddocument + file sourcewrite
signrequest_list_document_attachmentsList document attachmentspage?read-only
signrequest_get_document_attachmentGet one attachment by UUIDuuidread-only

Attachments collected from signers aren't a separate tool — they come back inline on the signer object via signrequest_get (alongside the signer's filled inputs).

High-level helpers & safety

These compose the raw endpoints into a single call each — they encode the "find the signed document, read its filled fields" logic so callers never have to walk signrequest.signers[].inputs[] or guess which of a person's documents is the real one.

ToolPurposeInputClass
signrequest_whoamiToken health check — confirms the API token works; returns teams & members—read-only
signrequest_get_signer_summaryOne-shot status for a person: finds their signed document and returns status, signed-PDF URL, embed_url, and filled fields as a flat {external_id: value} mapemail, name_contains?read-only
signrequest_get_document_fieldsA document's filled values as a flat {external_id: value} map + compact signersuuid, signer_email?read-only
signrequest_get_signed_pdfFresh (time-limited) signed-PDF + signing-log URLsuuidread-only
signrequest_get_signing_linkA signer's embedded signing link (embed_url)uuid, signer_email?read-only
signrequest_get_documentsBatch-fetch up to 50 documents as compact summaries (fewer round-trips, less context)uuids[]read-only
signrequest_create_embedded_signing_linksSafe link generator — forces disable_emails + embedded signing for every signer and returns each embed_url; no one is emaileddoc source or document, signers[]write · no email

Safety flags: quick_create / send / resend accept dry_run (preview who would be emailed, send nothing); quick_create accepts disable_emails; get_document accepts compact.

Campaign-scale & operations

Built on top of the API with bounded concurrency, auto-pagination, and polling — for roster-wide workflows and large accounts.

ToolPurposeInputClass
signrequest_campaign_statusRoster rollup — runs the signer summary for many people (bounded concurrency) and returns aggregate counts + per-person status/fields. One call drives a tracking dashboard.emails[], name_contains?, concurrency?read-only
signrequest_bulk_sendBulk campaign — sends the same template/file to many recipients (one request each); per-recipient results, dry_run, and an embedded switch (no emails, returns embed_urls)template/file_from_url, recipients[], …write
signrequest_list_all_documentsAuto-paginated, compact list of all documents (no manual paging)cap?, external_id?read-only
signrequest_list_template_fieldsDiscover a template's fillable external_ids / prefill tagsuuidread-only
signrequest_wait_until_signedBounded poll until signed/declined/cancelled (≤25s); for long waits use webhooks/eventsuuid, timeout_seconds?, interval_seconds?read-only

Operational modes

  • Read-only deploys. Set MCP_READONLY=true and the worker registers only read tools — no quick_create/send/bulk_send/cancel/delete, and they never appear in tools/list. Right for a reporting/dashboard connector.
  • Audit trail. Every state-changing API call is logged ([signrequest-mcp] POST /signrequests/ — method + path only, no PII), visible via wrangler tail.
  • Resilience. Idempotent GETs retry on 429/5xx with Retry-After-aware backoff; writes never auto-retry; batch tools use bounded concurrency so they don't trip the rate limiter.

Signer object

Used by signrequest_quick_create and signrequest_send:

FieldTypeNotes
emailstring (email)required
first_name, last_namestring
orderintsigning order; lower signs first. The sender is always order 0
languagestringen, en-gb, nl, fr, de, da, fi, hu, it, no, pl, pt, es, sv. Hebrew is not supported.
force_languageboolean
messagestringper-signer message
redirect_urlstring (url)redirect after signing

SignRequest API coverage

This MCP covers twenty endpoints of the SignRequest v1 API — the document-signing workflow plus read access to templates, events, and teams. The twenty base tools below map 1:1 to a method in src/signrequest.ts; the seven high-level helpers compose these same endpoints (e.g. search → get → field-extract):

ToolSignRequest endpoint
signrequest_quick_createPOST /signrequest-quick-create/
signrequest_create_documentPOST /documents/
signrequest_sendPOST /signrequests/
signrequest_getGET /signrequests/{uuid}/
signrequest_listGET /signrequests/
signrequest_cancelPOST /signrequests/{uuid}/cancel_signrequest/
signrequest_resendPOST /signrequests/{uuid}/resend_signrequest_email/
signrequest_get_documentGET /documents/{uuid}/
signrequest_list_documentsGET /documents/
signrequest_delete_documentDELETE /documents/{uuid}/
signrequest_list_templatesGET /templates/
signrequest_get_templateGET /templates/{uuid}/
signrequest_list_eventsGET /events/
signrequest_get_eventGET /events/{uuid}/
signrequest_list_teamsGET /teams/
signrequest_list_team_membersGET /team-members/
signrequest_add_document_attachmentPOST /document-attachments/
signrequest_list_document_attachmentsGET /document-attachments/
signrequest_get_document_attachmentGET /document-attachments/{uuid}/
signrequest_search_documentsGET /documents-search/

Still not exposed (present in the SignRequest v1 API, intentionally omitted):

  • Signer-collected attachments as a standalone resource — they come back inline on the signer object via signrequest_get (document attachments themselves are supported, above)
  • Team write ops — create/modify a team, fetch a single team by subdomain, invite members
  • API-token create/delete — SignRequest's API is list-only for tokens (create/revoke are web-UI only); a read-only list_api_tokens tool can be added on request but it returns secret token values, so it's omitted by default. Also e-sign disclosures.
  • A standalone signer resource — SignRequest has none; signer data comes back inside sign-request objects (signrequest_get)

If you need any of these, add a method to SignRequestClient and a tool in registerTools(). Full API: https://signrequest.com/api/v1/docs/.

The client (Authorization: Token <token>) retries only idempotent GETs (on 429/5xx, exponential backoff honoring Retry-After); state-changing POST/DELETE calls are never auto-retried, to avoid double-creating/sending or other surprises.


Configuration

Set via npx wrangler secret put <NAME> (secrets) or a [vars] block (non-secret). Add -c wrangler.oauth.jsonc to target the OAuth worker.

NameWorkerRequiredPurpose
SIGNREQUEST_TOKENboth✅Team-scoped SignRequest API token
MCP_AUTH_TOKENbearer✅Shared bearer clients send as Authorization: Bearer <…>
APP_PASSPHRASEoauth✅Passphrase entered on the OAuth consent screen
OAUTH_KV (binding)oauth✅KV namespace storing OAuth grants/registrations
SIGNREQUEST_FROM_EMAILbothoptionalDefault sender, so callers can omit from_email
SIGNREQUEST_BASE_URLbothoptionalOverride API base (default https://signrequest.com/api/v1)
SIGNREQUEST_MAX_RETRIESbothoptionalMax retries for idempotent calls (default 3)
MCP_READONLYbothoptionaltrue ⇒ register read tools only (no create/send/bulk/cancel/delete)

Deploy

npm install

# Bearer worker secrets — paste each value at the prompt (do NOT put it on the command line):
npx wrangler secret put SIGNREQUEST_TOKEN
npx wrangler secret put MCP_AUTH_TOKEN

npx wrangler deploy

Generate a strong MCP_AUTH_TOKEN without a trailing newline (a stray newline breaks the constant-time compare):

MCP_TOKEN=$(openssl rand -hex 32); printf '%s' "$MCP_TOKEN" | npx wrangler secret put MCP_AUTH_TOKEN; echo "MCP_AUTH_TOKEN=$MCP_TOKEN"

The first deploy creates the Durable Object (migration v1) and prints your https://signrequest-mcp.<subdomain>.workers.dev URL. For the OAuth worker, see OAuth worker.


Verify

URL="https://signrequest-mcp.<subdomain>.workers.dev"

# 1) Health (no auth) → "signrequest-mcp worker: ok"
curl "$URL/"

# 2) Fail-closed — no token → 401
curl -i -X POST "$URL/mcp"

# 3) MCP initialize (with token) → JSON-RPC result, not 401
curl -X POST "$URL/mcp" \
  -H "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Connect a client

Claude Code

claude mcp add --transport http --scope user signrequest \
  https://signrequest-mcp.<subdomain>.workers.dev/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

claude mcp list   # → signrequest: … (HTTP) - ✓ Connected

Claude Desktop

Claude Desktop speaks stdio, so bridge the remote server with mcp-remote. Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/) and fully restart the app:

{
  "mcpServers": {
    "signrequest": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://signrequest-mcp.<subdomain>.workers.dev/mcp",
        "--header", "Authorization: Bearer <MCP_AUTH_TOKEN>"
      ]
    }
  }
}

If a bare npx doesn't resolve inside the Desktop app (common when Node is installed via a version manager), use the absolute path from which npx.

Claude Web

The bearer worker can't be added to Claude.ai web (its connector UI requires OAuth, with no field for a static token). Use the signrequest-mcp-oauth deployment instead:

  1. Deploy it and set its secrets — see OAuth worker.
  2. In Claude.ai → Settings → Connectors → Add custom connector, enter the MCP URL: https://signrequest-mcp-oauth.<subdomain>.workers.dev/mcp
  3. Claude.ai discovers OAuth automatically (dynamic client registration) and sends you to the consent screen. Enter your passphrase to authorize.

Programmatic

Any HTTP MCP client works — send Authorization: Bearer <MCP_AUTH_TOKEN> and Accept: application/json, text/event-stream to POST /mcp.


OAuth worker (Claude.ai web)

signrequest-mcp-oauth is the same MCP server fronted by an OAuth 2.1 provider, gated by a single shared passphrase. Routes:

RoutePurpose
GET /health check (no auth)
GET/POST /authorizepassphrase consent screen
/token, /register, /.well-known/oauth-*OAuth endpoints (handled by the provider)
POST /mcp, GET /sseMCP transports, OAuth-protected

Deploy alongside the bearer worker:

# One-time: create the KV namespace the provider needs, then put its id in wrangler.oauth.jsonc
npx wrangler kv namespace create signrequest-mcp-oauth   # → { "binding": ..., "id": "<paste into kv_namespaces>" }

# Secrets (paste at the prompt; -c selects the OAuth worker):
npx wrangler secret put SIGNREQUEST_TOKEN -c wrangler.oauth.jsonc
npx wrangler secret put APP_PASSPHRASE   -c wrangler.oauth.jsonc

npx wrangler deploy -c wrangler.oauth.jsonc

APP_PASSPHRASE fails closed — if unset, the consent screen rejects every attempt. Then add the connector in Claude.ai per Claude Web.


Testing

npm run typecheck   # tsc --noEmit (strict)
npm test            # vitest — client (retry/backoff/pagination, no-retry-on-POST), helpers, signer summary
npm run smoke       # live smoke vs a deployed worker (set MCP_URL + MCP_TOKEN)

CI (.github/workflows/ci.yml) runs typecheck + tests on every push and PR. The client is fully unit-testable with a mocked fetch (injectable backoffBaseMs keeps retry tests fast); the pure helpers and the signer-summary composition are tested against fixtures.

Caveats

  • Existing-token-only. SignRequest is owned by Box and is in maintenance mode; this assumes you already have a working team API token.
  • No Hebrew in signer email/UI language (see Signer object).
  • Single-user OAuth. The OAuth worker gates on one shared passphrase — fine for a personal connector, not multi-tenant. Swap the consent handler for a real IdP (GitHub/Google/etc.) if you need per-user identity.
  • Dependency versions. agents@^0.14.5 + @modelcontextprotocol/sdk@^1.29.0 + zod@^4 (the SDK accepts zod 3 or 4); npm audit is clean. ai/react are required peers of agents but are never imported into the Worker bundle.

Project layout

src/
  index.ts        Bearer worker entry — routing, bearer gate, McpAgent/Durable Object
  oauth.ts        OAuth worker entry — OAuthProvider + passphrase consent + McpAgent
  tools.ts        registerTools() — the 32 tool definitions + Zod schemas + helpers (shared)
  signrequest.ts  SignRequestClient — dependency-free REST client, fetch-only, mapLimit/pagination (shared)
  ai-stub.ts      stubs the unused `ai` peer dep out of the bundle
tests/            vitest unit tests (client retry/backoff/pagination, helpers, signer summary)
vitest.config.ts  test config (resolves NodeNext .js specifiers to .ts)
scripts/smoke.mjs smoke test against a deployed worker (npm run smoke)
.github/workflows/ci.yml  CI — typecheck + tests on push/PR
wrangler.jsonc        bearer worker config (signrequest-mcp)
wrangler.oauth.jsonc  OAuth worker config (signrequest-mcp-oauth) — adds OAUTH_KV
package.json          deps (SDK ^1.29.0, agents ^0.14.5, zod ^4, workers-oauth-provider, wrangler, vitest)
Ver o original no GitHub

Bom para

Relacionados