MCP Reference

Tool reference

Every tool the Signvoy MCP server exposes, with its parameters, return shape, and the document states it requires. Tool descriptions are also delivered to the model at connection time — this page is the human-readable version of the same contract.

8 read

8 write

signvoy_ prefixed

Conventions

Every tool accepts workspace_id — optional. Omitting it falls back to the workspace bound to your OAuth grant. Membership is verified on every call, so passing a workspace you do not belong to fails rather than leaking data.

Results are JSON in a text block — each tool returns a single content block containing pretty-printed JSON, which is what the model reads.

Errors are prose, not status codes — a failed tool call returns isError: true with a message naming the violated constraint and the recovery step, so the model can correct itself instead of stalling on a bare HTTP code.

Pagination — list tools clamp limit to 20 by default and 100 at most, and return has_more plus total. Only signvoy_list_documents supports offset.

Role-based visibility — workspace members see only their own documents. Admins and owners see all documents in the workspace.

Badges: read tools never mutate anything. idempotent tools are safe to retry. destructive maps to the MCP destructiveHint annotation, which prompts well-behaved clients to ask for confirmation.

Read tools

All 8 carry the MCP readOnlyHint annotation. Safe to call freely — they cannot change document state.

Read · 8 tools

signvoy_list_workspacesread

List every workspace the authenticated user belongs to.

Call this first unless you already know the account has a single workspace. The returned id is what you pass as workspace_id everywhere else.

No parameters.

Returns { workspaces: [{ id, name, slug, personal, role }], count }

signvoy_list_templatesread

List templates in a workspace. Defaults to active (non-archived).

Only templates with hasPublishedVersion=true can create documents. A draft-only template will fail at create time.

workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.
status: "active" | "archived" | "all"optional — Filter by template status. Default: active.
limit: intoptional — Max results (1–100, default 20).

Returns { templates: [{ id, name, workspaceId, hasPublishedVersion, hasDraftVersion, archivedAt, updatedAt }], has_more, total }

signvoy_get_templateread

Get one template in full, including its recipient role keys.

Role keys such as signer, witness, or approver are required by signvoy_create_document — each recipient must match a key defined on the template. Always call this before creating a document.

template_id: uuidrequired — Template UUID from signvoy_list_templates.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.

Returns { template }

signvoy_list_documentsread

List documents newest-first, with status filter and text search.

Workspace members see only their own documents; admins and owners see all. Drafts include a review_url pointing at the Signvoy dashboard so a human can check the document before it is sent.

workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.
status: "draft" | "sent" | "in_progress" | "completed" | "declined" | "voided" | "expired"optional — Filter by document status.
limit: intoptional — Max results (1–100, default 20).
offset: intoptional — Zero-based offset for pagination.
q: stringoptional — Search by document name or recipient email.

Returns { documents: [{ id, name, status, routingMode, recipientCount, pendingCount, recipients[], send_blockers, review_url? }], has_more, total }

signvoy_get_document_statusread

Per-recipient signing state for one document.

Use recipients[].id from this response as document_recipient_id when calling signvoy_create_signing_link. pendingCount counts only the people the document is waiting on, so a cc is never included: a viewer reaches status acknowledged and a cc copy_sent, neither of which is signed.

document_id: uuidrequired — Document UUID from signvoy_list_documents.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.

Returns { id, name, status, routingMode, sentAt, completedAt, expiresAt, voidedAt, recipients: [{ id, name, email, roleKey, type, status, signedAt, declinedAt }] }

signvoy_get_audit_trailread

Append-only event log for chain-of-custody verification.

Records send, view, sign, decline, void, expire, and remind events with actor, IP address, and timestamp. Actions taken through MCP are tagged actorSource: "mcp" in the event metadata, so agent activity is distinguishable from dashboard activity.

document_id: uuidrequired — Document UUID from signvoy_list_documents.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.

Returns { documentId, events: [{ id, type, actorName, actorEmail, ipAddress, createdAt, metadata }] }

signvoy_get_signed_pdf_urlread

Presigned download URL for the certified signed PDF.

The URL expires after 10 minutes. Request a fresh one each time rather than caching or persisting it.

Requires: Document status must be completed.

document_id: uuidrequired — Document UUID. Must be in completed status.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.

Returns { documentId, url, note }

signvoy_list_contactsread

Search the workspace address book to turn a name into an email.

The address book is shared by everyone in the workspace and fills up automatically from the recipients of every document sent. Reach for this before signvoy_create_document whenever the user names a recipient rather than spelling out their address, instead of guessing an email. Archived contacts are never returned. Passing q ranks by relevance and returns no offset-based paging; omitting it browses the whole book, named contacts first.

workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.
q: stringoptional — Case-insensitive substring matched against name and email. Omit to list everything.
limit: numberoptional — Max results (1–100, default 20).
offset: numberoptional — Zero-based offset for pagination. Ignored when q is set.

Returns { contacts: [{ id, email, name, company, jobTitle }], total, has_more }

Write tools

These mutate state, and two of them are visible to third parties: signvoy_send_document and signvoy_remind_document both send real email to real counterparties. Every write tool checks that you are the document owner or a workspace admin before proceeding.

Write · 8 tools

signvoy_create_documentwrite

Create a draft document from a published template.

Creating and sending are deliberately separate tools so a human can review the draft before real emails reach counterparties. The response includes next_step telling the agent what to do, and review_url for the human to open.

Requires: Call signvoy_get_template first to obtain valid role keys.

template_id: uuidrequired — Published template UUID (hasPublishedVersion must be true).
recipients: Array<{ roleKey, name, email?, type?, order? }>required — Everyone the document goes to. type defaults to signer, and only a signer needs a roleKey from the template. cc receives a copy at their position in the order with nothing to do; viewer must open it and confirm they read it. At least one signer or viewer.
name: stringoptional — Document title. Defaults to the template name.
message: stringoptional — Personal note included in the signing invitation email.
email_subject: stringoptional — Replaces the generated subject on the signing request and reminders. Completion and cancellation notices keep their standard wording.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.

Returns { document, next_step }

signvoy_update_documentwriteidempotent

Fix a draft before sending — recipients, name, message, or routing mode.

This is the tool to reach for when signvoy_create_document reports a send_blocker such as a recipient with no email address. Passing recipients replaces the entire list, so include every recipient rather than only the changed ones.

Requires: Document status must be draft.

document_id: uuidrequired — Draft document UUID to update.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.
name: stringoptional — Updated document title.
message: stringoptional — Updated signing invitation message.
email_subject: stringoptional — Updated subject for the signing request and reminders. Pass an empty string to go back to the generated one.
routing_mode: "parallel" | "sequential"optional — parallel: everyone signs at once. sequential: group-by-group in order.
recipients: Array<{ roleKey, name, email?, type?, order? }>optional — Replacement recipient list. Replaces all existing recipients, including any cc and viewer entries.

Returns { document, message: "Draft updated successfully." }

signvoy_send_documentwriteidempotent

Email signing requests to every recipient.

Real emails go to real counterparties. Confirm with the user before calling. Idempotent — calling it on an already-sent document is a no-op rather than a duplicate send.

Requires: Document status must be draft, with no outstanding send_blockers.

document_id: uuidrequired — Document UUID to send. Must be in draft status.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.

Returns { document, message: "Document sent to N recipient(s)." }

signvoy_remind_documentwrite

Send one reminder email to all pending recipients.

Use sparingly. Remind once rather than repeatedly. cc recipients are never reminded — they were sent a copy and have nothing outstanding.

Requires: Document status must be sent or in_progress.

document_id: uuidrequired — Document UUID. Must be in sent or in_progress status.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.

Returns { document, message: "Reminder sent to pending recipients." }

signvoy_remind_recipientwrite

Send one reminder email to a single pending recipient.

The targeted alternative to signvoy_remind_document. Rate limited to one reminder per recipient per 24 hours — read recipients[].lastRemindedAt from signvoy_get_document_status first, and only remind recipients whose hasActiveSigningLink is true, since sequential signing means the others have nothing to act on yet.

Requires: Document status must be sent or in_progress, and the recipient must be pending.

document_id: uuidrequired — Document UUID. Must be in sent or in_progress status.
document_recipient_id: uuidrequired — Recipient UUID from signvoy_get_document_status recipients[].id. Must be pending.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.

Returns { document, message: "Reminder sent to <name>." }

signvoy_create_signing_linkwriteidempotent

Embedded signing URL for one pending recipient, no login required.

Returns the recipient's active signing token as an embeddable URL. Because it reuses the existing token, expires_in_seconds is currently accepted but not applied — the returned expiresAt is the signing token's own expiry. Treat the URL as a secret: anyone holding it can sign as that recipient.

Requires: Document status must be exactly sent, and the recipient must still be pending.

document_id: uuidrequired — Document UUID. Must be in sent status.
document_recipient_id: uuidrequired — Recipient UUID from signvoy_get_document_status recipients[].id. Must still be pending.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.
expires_in_seconds: intoptional — Accepted (60–86400) but not currently applied — see detail.

Returns { url, expiresAt, note }

signvoy_void_documentdestructive

Irreversibly void a document and revoke all signing links.

The document cannot be re-sent afterwards. Marked destructive so well-behaved clients prompt for confirmation before calling it.

document_id: uuidrequired — Document UUID to void. Irreversible.
workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.

Returns { document, message: "Document voided. All signing links have been revoked." }

signvoy_create_contactwrite

Save someone to the workspace address book ahead of time.

Rarely needed on its own, because sending a document files its recipients automatically. Reach for it when the user asks to save a contact before there is anything to send, or wants to record company, job title or phone, none of which a send captures. Fails with a conflict if the address is already in the book.

Requires: The email must not already be in the workspace address book — call signvoy_list_contacts first if unsure.

workspace_id: uuidoptional — Target workspace. Safe to omit only if you belong to exactly one; required otherwise, and the call fails with the candidates listed.
email: stringrequired — Email address. The only required field.
name: stringoptional — Full name, as it should appear on a document.
company: stringoptional — Company or organisation.
job_title: stringoptional — Role or job title.
phone: stringoptional — Contact phone number.
notes: stringoptional — Free-form note.

Returns { contact: { id, email, name, company, jobTitle }, message: "Contact saved to the workspace address book." }

Document lifecycle

Most tool errors are status errors: the document was not in the state the tool needs. This is the state machine the tools operate on.

draft ──signvoy_send_document──▶ sent ──first signature──▶ in_progress
                                  │                        │
                                  │                        ├─all signed──▶ completed
                                  │                        ├─declined────▶ declined
                                  │                        └─expiry──────▶ expired
                                  │
                                  └──signvoy_void_document──▶ voided  (irreversible)

Tool availability by status
  draft        create · update · send
  sent         remind · create_signing_link · void
  in_progress  remind · void
  completed    get_signed_pdf_url
  any status   list_documents · get_document_status · get_audit_trail

Two sharp edges. signvoy_create_signing_link requires status exactly sent — once a first recipient signs and the document moves to in_progress, it returns an error even though other recipients are still pending. And signvoy_update_document only works on draft; after sending, the only ways to change a document are to void it and start over.

Next steps

Prompt library

Prompts that chain these tools reliably

Troubleshooting

Error codes and what to do about them

REST API reference

The same operations over plain HTTP

MCP overview

Setup, auth flow, and the safety model

Something here out of date? Tell us — this page is generated from the same catalog the docs use, so corrections propagate everywhere.

Stop chasing signatures

Join thousands of teams using Signvoy to close deals, onboard clients, and sign contracts — faster.

Create your free account

No credit card · Free forever plan · Cancel anytime