turbosign-mcp
The turbosign-mcp server provides tools to send, manage, and track PDF signature requests via the TurboSign e-signature API. Key capabilities include:
Send documents for signature (
turbosign_send): Upload PDFs (or DOCX/PPTX) and email recipients to collect signatures, with options for sequential or parallel signing and automatic field placement via anchors, geometry, or coordinates.Preview before sending (
turbosign_review): Run the same document preparation and signature field placement without emailing anyone, returning a preview URL to verify field placement before live sending.Check signing status (
turbosign_status): View whether a request is pending, completed, or voided, with per‑recipient status and IDs.Download completed documents (
turbosign_download): Fetch the fully signed PDF once all signatures are collected.Cancel a request (
turbosign_void): Irrevocably void a pending request, recording a reason in the audit trail.Resend reminders (
turbosign_resend): Re‑send signature request emails to recipients who haven’t signed yet.Audit trail (
turbosign_audit_trail): Retrieve a hash‑chained, tamper‑evident history of document events (prepared, sent, viewed, signed, etc.).Setup and configuration: Guided credential setup (
turbosign_setup), secure storage and verification of API key, org ID, and sender email (turbosign_configure), and account identity check (turbosign_whoami).Client instructions:
get_instructionsreturns usage guidance, andrefresh_toolsrefreshes the tool list.
⚠️ Every turbosign_send call hits the production API; use turbosign_review as a safe rehearsal step before sending.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@turbosign-mcp send ~/contracts/nda.pdf to Bob Smith <bob@example.com> for signature"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
turbosign-mcp
Send PDFs out for signature by asking for it.
> send ~/contracts/nda.pdf to Bob Smith <bob@example.com> for signatureA thin MCP server over the TurboSign e-signature API. It speaks stdio, so any MCP client can launch it — Claude Code, Hermes Agent, anything else — with no container, no port, and no daemon.
What it does
Tool | |
| Send a document for signature. Emails the recipients. |
| Same, but emails nobody and returns a preview URL. |
| Has anyone signed yet? |
| Fetch the completed signed PDF. |
| Cancel a request that has not completed. |
| Chase a recipient. |
| Hash-chained history — prepared, sent, viewed, signed. |
| Getting a machine credentialled. |
Related MCP server: eSignatures MCP Server
Install
git clone https://github.com/disciplin-run-org/turbosign-mcp
cd turbosign-mcp
python3 -m venv .venv
.venv/bin/pip install -e .Then point your MCP client at it. For Claude Code, the bundled .mcp.json
already does this:
{
"mcpServers": {
"turbosign": { "command": ".venv/bin/turbosign-mcp" }
}
}Use an absolute path to .venv/bin/turbosign-mcp if your client does not
resolve relative commands from the project directory.
The signing chain must be stated, never inferred
The initiator names every party. Nothing is filled in for you, because a name that arrives by default is a party to a contract that nobody chose.
> send ~/contracts/nda.pdf to Bob Smith <bob@example.com> for signatureThree rules, each closing a different hole:
Names are explicit | A bare address is refused, not given a name derived from its local part. |
The sender is per-send |
|
The document declares the chain | Anchors are cross-checked against the recipients; every recipient must have a field, and every field a recipient. |
The anchors are the only declaration in a request that the caller did not write at the moment of sending — they are in the document a human drafted, which is what makes them worth checking against.
There was a fourth rule and it is gone: a signer allowlist. It refused any
recipient not pre-approved in an environment variable. The argument for it was
bounding who a manipulated agent could send to; the argument that won is that
sending someone a document to sign is what permission means, and requiring
every counterparty to be pre-approved on the box made signing with anyone new
an operator task. A permanent everyday cost against an occasional threat that
is already covered where it matters — on an agent deployment turbosign_send
sits behind human approval, and the person approving it is the person who
decided to send. See AR-7.
The document says where people sign — nothing else can
There is no placement argument, no coordinates and no fields array. The PDF
carries inline text anchors where each party signs, or it is refused.
That is deliberately narrower than the TurboSign API allows, and it was bought with experience: roughly ten signatures landed in the wrong place on a real agreement before it was corrected by hand. Every one was a position computed by something that could not see the page. An anchor cannot be off by a page, because the author put it where the signature goes.
The cost is accepted rather than hidden: a PDF you cannot edit cannot be sent through this server. Anchors have to be real extractable text, so they go in the source document and you re-export.
How to anchor a document
{Signature1}<tab><tab>{Date1}
______________________________________________
[Ann Jones Signature & Date]Above the line. On its own line directly above the signature rule. TurboSign draws the field downward from the anchor, so an anchor above the rule puts the signature on it. An anchor on the rule pushes it below.
Invisible. Colour the anchor text to match the page background — white on white. Still real text, so TurboSign finds it; nobody sees
{Signature1}on the executed agreement.Signature left, date right, same line, tab-separated.
The number is the signer's position in your recipients list, not their position in the document. A company that counter-signs at the top of the page but is second in your list gets
{Signature2}/{Date2}. Getting this backwards swaps who signs where — and the document still sends.
The same guidance comes back in the error when a document has no anchors, and it is served from one place in the code so the two cannot disagree.
turbosign_review is held to every rule above — a rehearsal that skipped the
checks would return a clean preview for a request that could never be sent.
Open the preview and look, every time: a wrong anchor number produces a
perfectly valid-looking agreement signed by the wrong party in the wrong place.
Getting credentialled
Ask the agent where to start:
> turbosign_setup()It reports what is missing and gives you the URL to create a TurboDocx account and the navigation to the API key. Then save the key one of two ways.
From a terminal — the key never enters the conversation:
.venv/bin/turbosign-mcp configurePrompts for the key with the echo off, verifies it against the live API, and
writes it owner-only to ~/.turbosign-mcp/credentials.json. Nothing is printed
but a masked fingerprint. Use this for any key you would mind seeing in a log.
There is deliberately no --api-key flag: a secret on a command line is
recorded in your shell history and is visible to every other user on the
machine via ps. Passing one is refused with an explanation rather than
silently ignored. For automated provisioning use --api-key-file, and
--org-id / --sender-email to skip the prompts.
Or through the agent, if convenience wins:
> turbosign_configure(api_key="...", org_id="...", sender_email="you@example.com")Same verification, same store. The trade-off is that the key travels through the agent's context and lands in that conversation's transcript on disk — fine for a scoped key on a test account, not fine for a long-lived one or for a session token that can do everything your user can.
Either way the credentials are checked against the live API before they are saved, so a mistyped key fails at setup rather than on your first real send. The server re-reads the store on every call, so there is nothing to restart.
turbosign_whoami() shows which account a machine is sending as — worth having
when the server is installed on several machines with different accounts.
Credentials never live in this repo
The store is at ~/.turbosign-mcp/credentials.json — outside the working
tree, so a credential cannot be committed by accident even if .gitignore
were wrong. .gitignore covers credentials.json, .env, *.pem and *.key
anyway, for the case where someone puts one in the tree deliberately. The test
suite needs no credentials, and its fixtures are obviously fake.
As a backstop that does not depend on anyone being careful, this repo has GitHub secret scanning and push protection enabled — a push carrying a recognised key pattern is rejected rather than published.
Credentials resolve in this order
TURBODOCX_*environment variables~/.turbosign-mcp/credentials.jsonNeither — the server still runs and still offers the setup tools
The environment always wins. On an unattended box where the harness injects
the key, it never passes through the agent's context and no tool call can
overwrite it. turbosign_configure is the interactive path for a machine
someone is sitting at.
The trade-off, stated plainly: anything you pass to turbosign_configure
travels through the agent's context and, on a supervised agent, across its
approval surface. That is fine for interactive setup. For unattended
instances, prefer the environment.
Testing: there is no sandbox
TurboSign has exactly one environment, and it is production. There is no test
host, no sandbox key and no dry-run flag — the "free sandbox" on the vendor's
marketing page means the free tier (5 signatures a month) on the live API. Every
turbosign_send reaches a real inbox, lands in a real audit trail, and cannot
be recalled, only voided.
So the server provides the rehearsal the API does not. Work up this ladder on any new machine, new document layout, or new account:
Emails anyone? | ||
1 |
| No |
2 |
| No |
3 |
| Yes |
Rung 2 is the important one: it uploads the document, parses the recipients, places the fields and passes the API's own validation — everything a send does except the send. Open the preview URL and look at where the boxes landed.
These instructions ship inside the server, so any MCP client that reads
get_instructions() gets them too, not just readers of this file.
If you are embedding this server in an agent host, gate turbosign_send
behind human approval, and consider gating turbosign_void as well —
cancelling someone's pending signature request is equally irreversible. Leave
turbosign_review ungated: it is the safe rehearsal, and gating it removes the
reason to prefer it.
Where the signature boxes go
By default (placement="auto") the server reads the PDF and decides:
Anchors, if the document has them. Text like
{Signature1},{Date1}or{Initial2}is replaced in place by TurboSign. The trailing digit picks the recipient. Exact placement, no geometry involved.Geometry, if it does not. A signature and date box per recipient at the foot of the last page.
So a document authored with anchors gets exact placement for free, and an arbitrary PDF still works. The response always reports which strategy was used.
Override with placement="anchor" (fail rather than fall back),
placement="coordinates", or pass a fields array for full control.
Anchors leave their token in the executed PDF
TurboSign paints over an anchor and draws the field on top, so nobody sees
{Signature1} on screen or on paper. But the token is still in the text
layer of the finished contract:
Signature: {Signature1}
Date: {Date1}It reaches copy-paste, search indexes, a document-management system's full-text extract, and screen readers.
There is no way to avoid this while using anchors. Making the token white or 1pt does not help — text extraction ignores colour and size, so pypdf, a search index and a screen reader all still find it. It only ever changed how the source looked, and TurboSign already covers the token in the output anyway. And the token cannot simply be omitted, because the API locates the field by extracting that text.
So it is a genuine trade-off, not a technique problem:
Placement follows reflowed content | Clean text layer | |
Anchors ( | Yes | No — token survives |
Coordinates / explicit | No — fixed geometry | Yes — no markers at all |
For a contract where the text layer matters — anything indexed, archived, or
read aloud — use placement="coordinates" or supply fields directly. Nothing
is written into the document, so nothing can leak out of it.
Verified on a real executed document, 2026-08-02.
Date format is an account setting, not an API parameter
Out of the box a date field renders 08/01/2026 for 1 August 2026 —
ambiguous to anyone who reads dates day-first. There is no per-field
date-format parameter: the field options are type, required,
defaultValue, isReadonly, backgroundColor and geometry, in the REST API
and in every official SDK.
Change it in the TurboDocx console, under your account settings. Richer
formats are available than the API docs suggest — including fully unambiguous
ones like Saturday, August 1st, 2026. Set it once and every subsequent
signature uses it.
Two consequences worth knowing:
It is a property of the sending account, not the request. Every document that account sends gets that format, and this server cannot override it per send. If you run several machines with different TurboDocx accounts, set the format on each one, or they will not match.
It is not retroactive. Verified: re-downloading an already-executed document after changing the setting returns a byte-identical file. The format is baked in at signing time.
If you cannot change the setting — someone else's account, say — spell the date in the body of the agreement ("this 1st day of August, 2026") and let the field date stand as the machine timestamp.
turbosign_review() takes the same arguments as turbosign_send() but emails
nobody and hands back a preview URL. Worth doing the first time you send a new
kind of document.
Configuration
Every setting is optional; the three credentials are needed before a send.
Variable | Default | |
| — | Bearer token |
| — |
|
| — | Reply-to; the API rejects sends without it |
| API key's name | Shown in the request emails |
|
| |
|
| Console, for |
|
| |
|
| Credential store location |
|
| Roots documents may be sent from |
|
| Upload cap |
|
| Per-request timeout, seconds |
Health
Stdio servers have no health endpoint, so:
.venv/bin/turbosign-mcp --selftestIt lists the registered tools and reports how the machine is configured. A machine with no credentials exits 0 — that is the normal state before setup, not a fault.
Notes for the curious
Why stdio and not HTTP. TurboSign is a stateless request/response API. There is no long-lived session to keep warm, so a container, a port and a health check would be pure overhead. The client launches the process; when it exits, nothing is left behind.
Why httpx directly and not turbodocx-sdk. This server is the thin
wrapper. Stacking it on a second wrapper buys drift protection at the price of
a pre-1.0 dependency and someone else's error messages — and error messages are
most of the value here, because an agent recovers from a sentence and cannot
recover from a stack trace.
Why the tools are synchronous. The usual MCP advice for a call to an external service is a background task the client polls. Stdio clients like Hermes do not poll the MCP task protocol, so that would make the primary consumer worse. Instead the calls are synchronous with a bounded timeout (90s, inside Hermes' 300s per-tool budget) and a 10 MB upload cap that keeps a typical send well inside the tighter ~60s budget of other clients.
Coordinates are top-left origin — y counts down from the top edge. That
is both documented ("Vertical position from top edge") and verified against the
live API, and it is isolated to one constant in placement.py so a future
change stays a one-line fix. See docs/VERIFICATION.md.
Architecture decisions
The four decisions most likely to look like mistakes to a new reader are
recorded as MADR records in architrix/adr/, in force as of
2026-08-09:
Stdio transport, not HTTP in a container | |
Call the API with httpx directly, not the official SDK | |
Synchronous tools with a bounded timeout, not | |
Environment beats stored credentials, and onboarding lives in the server | |
The signing chain is stated, never inferred (superseded by AR-7) | |
Inline text anchors are the only placement mechanism | |
The signer allowlist is removed |
Each records what was given up as well as what was gained. AR-3 in particular is a deliberate, documented deviation from the house MCP-server standard — read it before "fixing" the synchronous tools.
The architrix/ directory is Architrix's namespace in this repository, per the
ecosystem's directory-ownership convention. Edit the records through Architrix
(adr_create / adr_status with org="disciplin-run-org", then
github_save), not by hand — a hand-edit will be overwritten by the next save.
Development
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytestThe suite runs without network access or credentials — HTTP is mocked with
respx, and PDF fixtures are generated in code rather than committed, so
nothing in this public repo can carry a real name or address.
Licence
MIT.
Available Tools
12 toolsget_instructionsA
Return this server's usage instructions and recommended workflow.
Call this after a context compaction, or whenever it is unclear which tool to reach for.
Inputs: no named parameters. Returns: result
refresh_toolsA
Refresh the client's cached tool list after a server restart or upgrade. Call this instead of falling back to raw HTTP requests.
Inputs: no named parameters. Returns: result
turbosign_audit_trailA
Get the tamper-evident history of a document.
Returns hash-chained entries — prepared, sent, viewed, signed, voided — newest last. Use this to answer "has Bob opened it yet?".
Inputs: document_id (required), limit. Returns: object
turbosign_configureA
Save this machine's TurboDocx credentials after checking they work.
The credentials are verified against the live API before anything is written, so a mistyped key fails here rather than on your first real send. They are stored owner-only in ~/.turbosign-mcp/credentials.json.
Get the values from turbosign_setup(). sender_email is the reply-to address recipients see. sender_name is optional and defaults to the name on the API key. base_url is only for a non-production endpoint.
The key is never echoed back — only a masked fingerprint.
PRIVACY: whatever you pass here travels through this conversation and is written to its transcript on disk. For a scoped key on a test account that is usually fine. For a long-lived key, or a session token that can do everything the user can, tell the human to run this in their own terminal instead — same verification, same store, and the key never enters the conversation:
turbosign-mcp configureInputs: org_id (required), api_key (required), sender_email (required), base_url, +1 more. Returns: object
turbosign_downloadA
Download a completed signed document to a local file.
Only completed documents can be downloaded. output_path must be an absolute path in an existing directory.
Inputs: document_id (required), output_path (required). Returns: object
turbosign_resendA
Resend the signature request email to recipients who have not signed.
recipient_ids is a comma-separated list of recipient UUIDs — get them from turbosign_status(). Only recipients whose turn it is in the signing order will actually be emailed.
Inputs: document_id (required), recipient_ids (required). Returns: object
turbosign_reviewA
Prepare a document and get a preview URL WITHOUT emailing anyone.
Same arguments as turbosign_send. Use this to check where the signature boxes landed before committing to a real send — open the returned preview_url in a browser and look.
Worth doing the first time you send a particular kind of document.
Inputs: file_path (required), recipients (required), anchor, fields, +7 more. Returns: object
turbosign_sendA
Send a document out for signature. This emails the recipients.
THERE IS NO SANDBOX — TurboSign has one environment and it is production. This reaches a real inbox and cannot be recalled, only voided. On a new machine, new document layout or new account, run turbosign_whoami(verify=True) then turbosign_review() first, and make your first real send to your own address.
turbosign_review() takes these exact arguments and emails nobody.
file_path: absolute path to a PDF (DOCX and PPTX also work, but only with an explicit anchor or fields, since they cannot be measured). recipients: "Bob Smith bob@example.com, ann@example.com", or a JSON array of {name, email} objects. placement: "auto" reads the document, uses {Signature1}-style anchors if they are there, and otherwise places a signature and date box per recipient at the foot of the last page. "anchor" requires anchors. "coordinates" forces automatic positioning. "explicit" requires a fields array. sequential: false (default) lets everyone sign at once; true makes them sign in the order listed.
Returns the document_id — keep it, every other tool needs it.
Inputs: file_path (required), recipients (required), anchor, fields, +7 more. Returns: object
turbosign_setupA
Start here on a machine that has never sent a signature request.
Reports which credentials are missing and where the present ones came from, then gives the URLs for creating a TurboDocx account and finding the API key and organization id. Follow the URLs, then call turbosign_configure() with the three values.
Set open_browser=True to also try opening the console locally — it is best-effort and reports whether it worked, since a server without a desktop has no browser to open.
Inputs: open_browser. Returns: result
turbosign_statusA
Check where a signature request has got to.
Reports the document's state (pending, completed, voided) and, where the API returns them, each recipient's state and id. The recipient ids are what turbosign_resend() needs.
Inputs: document_id (required). Returns: object
turbosign_voidA
Cancel a signature request that has not completed.
The reason is recorded in the audit trail and is required. This cannot be undone — send the document again if you need to restart.
Inputs: reason (required), document_id (required). Returns: object
turbosign_whoamiA
Show which TurboDocx account this machine sends as.
Reports the masked API key, organization id, sender address, and where each value was resolved from — useful when the same server is installed on several machines with different accounts. With verify=True it also checks the credentials against the live API.
Inputs: verify. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a unique, focused purpose: setup guides credential configuration, configure saves credentials, whoami displays current identity, send/review/status/download/void/resend/audit_trail handle distinct stages of the signing workflow, and get_instructions/refresh_tools are server utilities. The only near-overlap is send vs review, but the explicit 'emails nobody' distinction makes them unambiguous.
Ten of twelve tools use the turbosign_ prefix, which is a strong pattern, but get_instructions and refresh_tools break it. Within the prefixed tools, some names are verbs (send, review, download) and some are nouns (status, audit_trail, whoami), so the convention is not perfectly uniform.
With 12 tools, the server covers the full signing lifecycle plus setup and utility functions without redundancy. This is a well-scoped size for an e-signature MCP server.
The toolset covers the entire document signing workflow: credential setup, configure, send, review, status, download, void, resend, and audit trail. Minor gaps, like a list-documents tool, but the core workflows are fully supported.
Maintenance
Related MCP Connectors
Send documents for e-signature, track signing status, and download signed PDFs. No API key required.
Get PDFs signed: prepare, send and track e-signature requests, then fetch the signed copy.
Send documents for e-signature from templates, track status, remind signers, get signed PDFs.
Send, track, and manage documents for eSignature: templates, drafts, signing status, signed PDFs.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables interaction with the BoldSign e-signature platform through its API. Supports managing documents, templates, contacts, users, and teams for electronic signature workflows.14MIT
- AlicenseAqualityDmaintenanceEnables managing electronic signatures and contracts through the eSignatures API, including creating, sending, and withdrawing contracts, as well as managing templates and collaborators.13MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents and developers to create, send, and follow up on contracts for e-signature, manage signers and templates, retrieve signed PDFs and audit trails, and verify PDF signatures. It keeps signing and declining in the hands of each signer through personal links.1MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to send documents for e-signature from templates or local files, track signers and history, send reminders, create signing links, and download or verify sealed PDFs.1351 npmMIT