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 generic endpoint (https://mcp.signatureapi.com/mcp) exposes 21 tools. The ChatGPT app adds upload_file, for 22. A connected client can always list the exact set itself with the MCP tools/list request; this page describes the same catalog.

Tools that touch account data take an optional mode parameter (test or live) that defaults to test. Test mode sends no email, so an agent can run a whole signing flow without reaching a real person.

Account tool

Tool	Operation	Description
`whoami`	Read	Return the connected account name and the modes it can use. Returns no email, user ID, or credential.

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. Pending recipients can no longer open their ceremonies.
`delete_envelope`	Write	Permanently delete an envelope in a final status (`completed`, `canceled`, or `failed`).

Upload tools

Tool	Operation	Description
`mint_upload_url`	Write	Return a short-lived signed PUT URL and a `reference` for agents that upload the bytes themselves. See Uploading files.
`upload_file`	Write	ChatGPT app only. Upload a file the user attached in the chat, using the host’s native file handling.
`inspect_upload`	Read	Return the analyzed structure of an uploaded PDF or DOCX: page count and sizes, detected `[[key]]` placeholders with positions, and DOCX `{{key}}` template fields.

inspect_upload reports coordinates in PDF points with the origin at the top-left of the page, the same units create_envelope uses for fixed positions. Call it before creating the envelope to check that every placeholder key was detected.

Recipient and ceremony tools

Tool	Operation	Description
`resend_request`	Write	Resend the signing-request email to a recipient who has not completed. Optional one-time subject and message overrides.
`replace_recipient`	Write	Replace a recipient with a different person, for example after a hard bounce. The new recipient inherits the original’s key, routing position, and places.
`create_ceremony`	Write	Create a new ceremony for a recipient and revoke the previous one. Use it to switch authentication, embed the ceremony, or set a `redirect_url`.

create_ceremony returns a url for custom and email_code authentication. For email_link the url is null: the emailed link is the recipient’s authentication, so it is never disclosed. In live mode, all three tools can email a real person.

Event and deliverable tools

Tool	Operation	Description
`list_events`	Read	List events newest first, for the account, one envelope, or one recipient. Optional `wait_seconds` (0–20) waits for a new event.
`get_deliverables`	Read	Return every deliverable of an envelope, each with its `status` and, once `generated`, a fresh download `url` valid for about an hour.

list_events is how an agent verifies that something happened. With wait_seconds, the server checks every two seconds for an event newer than the first page. If none arrives before the deadline, the response carries timed_out: true. That is not an error; call again to keep waiting.

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. Test-mode signing requests also carry a short-lived `html_url` and the `ceremony_url`.

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, and the email content is not returned: 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.

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`.
`update_webhook`	Write	Change an endpoint in place: its URL, description, filters, or `disabled` flag. Only the fields you pass change.
`delete_webhook`	Write	Permanently delete an endpoint. Pending deliveries to it are dropped.
`list_webhook_attempts`	Read	List recent delivery attempts to an endpoint: event type, delivery status, the endpoint’s HTTP status code, and response time.

A typical loop is create_webhook, then a test-mode envelope, then list_webhook_attempts to confirm the endpoint answered each event with a 2xx. To pause an endpoint, prefer update_webhook with disabled: true over deleting it.

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.

Documentation tool

Tool	Operation	Description
`search_documentation`	Read	Search the public documentation and return ranked excerpts with source URLs, or read one page in full with `page`.

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`
`whoami`	true	false	true	false
`get_envelope`	true	false	true	false
`list_envelopes`	true	false	true	false
`inspect_upload`	true	false	true	false
`list_events`	true	false	true	false
`get_deliverables`	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
`mint_upload_url`	false	false	false	false
`upload_file`	false	false	false	true
`create_envelope`	false	true	false	true
`cancel_envelope`	false	true	false	true
`resend_request`	false	true	false	true
`replace_recipient`	false	true	false	true
`create_ceremony`	false	true	false	true
`create_webhook`	false	true	false	true
`update_webhook`	false	true	true	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, resend_request, replace_recipient, create_ceremony, and the webhook writes carry the flag because they have effects outside SignatureAPI: in live mode they email real people, and a webhook delivers to a third-party endpoint. openWorldHint marks the tools that reach systems beyond the SignatureAPI account: recipient inboxes, customer endpoints, and the host’s file store.

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, list_events, and list_emails return 10 items per page by default, with a maximum page size of 20. list_webhook_attempts allows up to 50. 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. Pass a result’s docs slug as page to read that page’s complete Markdown. 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.