Tools and Resources – SignatureAPI Docs

The MCP server exposes a curated set of tools that map to the most common SignatureAPI operations. Every tool is scoped to the account the user authorized. The tools fall into four groups: envelopes, emails, webhooks, and documentation.

Envelope tools

Tool	Operation	Description
`create_envelope`	Write	Create a new envelope with documents and recipients. Maps to Create envelope.
`get_envelope`	Read	Fetch an envelope by id. Maps to Get envelope.
`list_envelopes`	Read	List envelopes for the account, most-recent first, with cursor pagination. Filters: `status`, `topic`.
`cancel_envelope`	Write	Cancel an in-progress envelope. Recipients receive a cancellation email.
`delete_envelope`	Write	Permanently delete an envelope in a final status (`completed`, `canceled`, or `failed`).
`upload_file`	Write	Upload a file into SignatureAPI using the host’s native file handling (for example, ChatGPT Apps).
`mint_upload_url`	Write	Return a short-lived signed PUT URL and reference for agents that upload the bytes themselves.

Email tools

SignatureAPI records every email it generates for the account: signing requests, deliverable emails, one-time codes, and owner notifications. In test mode no email is actually sent, so this log is how an agent sees what recipients would have received, and how it reaches a test-mode signing ceremony.

Tool	Operation	Description
`list_emails`	Read	List emails for the account, most-recent first, with cursor pagination. Filters: `envelope_id`, `recipient_id`, `mode`, and free-text `search`.
`get_email`	Read	Fetch one email by id (`eml_…`), with delivery details, a short-lived `html_url` to the rendered content, and the signing `ceremony_url` when the email carries one.

Each email reports its status and delivered_at and bounced_at timestamps, which makes the log the first place to look when a recipient says they never received a signing email.

For an email_link ceremony in test mode, the agent calls list_emails filtered by envelope_id, picks the email with type: "request", and reads ceremony_url from get_email. For live-mode emails ceremony_url is always null: possession of the emailed link is the recipient’s authentication, so live links are never disclosed to the agent.

Webhook tools

Webhooks are configured separately per mode. An endpoint created in test mode only receives events from test-mode envelopes. Every webhook tool takes a mode parameter that defaults to test.

Tool	Operation	Description
`list_webhooks`	Read	List the endpoints subscribed in one mode, with their URL, event types, topic filter, and disabled flag.
`create_webhook`	Write	Subscribe an HTTPS endpoint. Optional `event_types` and `topics` filters. Returns the endpoint and `signing_secret_dashboard_url`.
`delete_webhook`	Write	Permanently delete an endpoint. Pending deliveries to it are dropped.
`test_webhook`	Write	Deliver the documented example payload of one event type to a single endpoint, signed like a real delivery.
`list_webhook_attempts`	Read	List recent delivery attempts to an endpoint: event type, delivery status, the endpoint’s HTTP status and response body, and response time.

A typical loop is create_webhook, then test_webhook, then list_webhook_attempts to confirm the endpoint answered with a 2xx, and only then a real test-mode envelope.

No tool returns a credential. A tool result lands in the agent’s context, in the client’s transcript, and in the model provider’s logs, and the agent, not a person, decides to read it. The signing secret of an endpoint is shown only on the dashboard webhooks page, which create_webhook links as signing_secret_dashboard_url. An agent should ask you to copy it into your application’s environment, never into the chat. The same applies to API keys, which live on the dashboard API keys page.

Test deliveries use the same example payload shown in the webhooks reference for that event. Its id and timestamp are fixed sample values and it references no real envelope. The request carries a webhook-test: true header that real deliveries never have, so handlers can tell them apart. A few event types have no example registered yet and return a validation error from test_webhook; real deliveries of those events are unaffected.

Documentation tool

Tool	Operation	Description
`search_documentation`	Read	Search the public SignatureAPI documentation and return ranked excerpts with source URLs.

Tool annotations

Each tool is annotated with MCP’s standard hints so resource-aware clients can render the right confirmation UI:

Tool	`readOnlyHint`	`destructiveHint`	`idempotentHint`	`openWorldHint`
`get_envelope`	true	false	true	false
`list_envelopes`	true	false	true	false
`list_emails`	true	false	true	false
`get_email`	true	false	true	false
`list_webhooks`	true	false	true	false
`list_webhook_attempts`	true	false	true	false
`search_documentation`	true	false	true	false
`upload_file`	false	false	false	false
`mint_upload_url`	false	false	false	false
`test_webhook`	false	false	false	true
`create_envelope`	false	true	false	true
`create_webhook`	false	true	false	true
`cancel_envelope`	false	true	false	true
`delete_envelope`	false	true	true	false
`delete_webhook`	false	true	true	false

Tools marked destructive should trigger user confirmation in any well-behaved client. create_envelope and create_webhook carry the flag because they have effects outside SignatureAPI: creating a live envelope emails real recipients, and a webhook starts delivering to a third-party endpoint. openWorldHint marks the tools that reach systems beyond the SignatureAPI account: recipient inboxes and customer endpoints.

Resources

The server also exposes envelopes as an MCP resource so clients that support resources (such as Claude) can render them as chips, list them in side panels, and re-fetch them on their own.

URI template	Description
`signatureapi://envelope/{envelope_id}`	JSON representation of an envelope. Same payload as `get_envelope`.

Listing returns up to 10 envelopes by default, sized for client pickers (for example the @ picker in Claude Code).

Pagination

list_envelopes returns 10 envelopes per page by default, with a maximum page size of 20. The response includes links.next and links.previous cursor URLs; pass the cursor query value back as the cursor parameter to paginate. API-level pagination defaults on the REST surface are unchanged.

Uploading files

There are two ways to get a local file into an envelope, depending on what the client can do:

upload_file uses the host’s native file handling. In hosts like ChatGPT Apps, the client transfers the bytes for you; you do not run a PUT yourself.
mint_upload_url returns a single-use signed URL the agent uses to PUT the file directly to the SignatureAPI upload subdomain. Use this when the client can execute code and upload bytes itself.

The signed-URL flow below applies to mint_upload_url.

Compute size and SHA-256

Get the file's exact byte count and its SHA-256 hash. These values are bound into the signed URL, so they must match the bytes you actually send.

wc -c < contract.pdf
shasum -a 256 contract.pdf | awk '{print $1}'

Call mint_upload_url

Provide media_type, size, and sha256. You receive:

upload_url — single-use, expires in roughly five minutes.
reference — the canonical https://api.signatureapi.com/v1/uploads/upl_… URL to use later.

PUT the bytes

Send the raw file body to upload_url. All three headers below are required and must match the values declared in step 2.

curl -X PUT "<upload_url>" \
-H "Content-Type: <media_type>" \
-H "Content-Length: <size>" \
-H "x-amz-content-sha256: <sha256>" \
--data-binary @contract.pdf

A 2xx response means the bytes landed and reference is now resolvable. A 4xx means the upload failed; the URL is single-use, so re-mint by calling mint_upload_url again.

Pass the reference to create_envelope

Use the returned reference (not upload_url) as the document URL when calling create_envelope.

Supported media types

Type	MIME	Used for
PDF	`application/pdf`	Envelope documents
DOCX	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	Envelope documents (with optional template merge)
PNG	`image/png`	Symbol assets such as logos

Phase one of the upload service caps individual files at roughly 5 MB. Larger files will be supported as the upload service scales.

Pure connector clients

Clients without local code execution cannot run the PUT, so they should not call mint_upload_url. Hosts with native file handling (such as ChatGPT Apps) can use upload_file instead. Otherwise, supply a URL on a host SignatureAPI already accepts (S3, Google Drive, Dropbox, and similar) and pass that URL directly to create_envelope.

Documentation search

search_documentation lets the agent look up SignatureAPI concepts, field names, enum values, and webhook events before guessing. Each result includes a title, url, and a short snippet. The tool is read-only and safe to call as often as needed; in practice, calling it once before a non-trivial create_envelope produces noticeably better results than relying on the model’s training data.