MCP or REST API: Which Should Your Agent Sign With?

Signvoy exposes two programmable surfaces: an MCP server that Claude or Cursor can connect to, and a REST API with SDKs and webhooks. People building on Signvoy usually assume one is the modern replacement for the other and ask which to standardise on.

Neither replaces the other, and the choice is not really about protocols. It comes down to one question: is a human present at the moment the document goes out?

The one question

An e-signature call has a side effect you cannot take back. Sending a contract puts an email in a counterparty's inbox. There is no delete, and a void afterwards is a visible event rather than an undo — they already saw it.

So the useful axis is not "conversational vs programmatic". It is who is accountable for that irreversible moment.

• A human is there. They are in a chat window, mid-task, deciding what the document should say. You want the model to gather intent, assemble a draft, and put it in front of them. That is MCP.
• No human is there. A queue drains at 2am, or a webhook fires, or a CRM stage changes. You want determinism, retries and idempotency. That is REST.

Side by side

Why MCP is the wrong hammer for batches

Three properties make it a poor fit for unattended volume, and all three are consequences of the design rather than gaps to be filled later.

The token is interactive. OAuth access tokens expire. A compliant MCP client refreshes them silently, but the grant itself is bound to a human who consented. There is no user to consent at 2am on a Sunday, and a cron job that depends on a token someone established in a browser six weeks ago is a pager waiting to go off.

Tool selection is probabilistic. This is the point of MCP, not a defect — you describe capabilities and the model chooses. But "usually picks the right tool" is a different reliability class from "calls the endpoint I wrote", and for 500 documents the difference compounds.

Rate limits assume a conversation. Signvoy allows 100 requests per 60 seconds per OAuth token, sized for a person working through a task. A batch will hit that immediately, and the correct response is not a higher limit — it is a different surface.

Why REST is the wrong hammer for ad-hoc work

The symmetric failure is subtler because REST works; it just costs more than the task is worth.

Every one-off request — "send the mutual NDA to this person, but change the term to two years" — needs someone to write code, or needs a UI built in advance for that exact variation. Most of these requests happen once. Building an interface for each is how internal tools accumulate twenty half-finished forms.

REST also has nowhere to put judgement. There is no consent screen and no draft for a person to read; whatever the code decides is what happens. When the decision is genuinely a judgement call, that is the wrong shape.

The architecture that actually ships

Most real systems use both, split along the same seam.

Human in a chat window
  └─ MCP: find template → fill fields → create draft → return review_url
        └─ Human opens the draft and approves
              └─ REST: send, then handle webhooks
                    └─ document.completed → your system of record

MCP is the front half, where intent is ambiguous and a person is available. REST is the back half, where the work is defined and needs to survive a retry.

This is also why Signvoy separates signvoy_create_document from signvoy_send_document. Create only produces a draft and returns a review_url for a human to open; nothing is emailed until an explicit send call. That split is what makes the handoff above possible instead of hypothetical — and it bounds the damage when a model misreads an instruction, which is the subject of why create and send should be two different tools.

Picking, concretely

Use MCP when:

• A person is in the loop at send time
• The request is one-off or varies every time
• You want zero setup for a non-developer — Claude, Cursor
• You are prototyping and do not want to write a client yet

Use the REST API when:

• Nobody is watching when it runs
• Volume is above a handful per session
• You need webhooks, idempotency, or a typed SDK — see the quickstart
• The same call has to produce the same result every time

Use both when you have a real product: MCP for the conversational surface, REST for the machinery behind it.

What does not change between them

Worth stating, because it is the reason mixing them is safe rather than merely possible.

Both surfaces act on the same documents, the same templates and the same tamper-evident audit trail. Both are available on every plan including Free. And both are attributable after the fact: MCP calls write audit events tagged actorSource: "mcp" with the user ID, IP and user agent, so six months later you can still tell which actions an agent took and which a person did.

That last property is what makes agent access auditable rather than merely convenient — and it is the part most worth checking before you let anything automated near a contract.

Start with the one that matches your caller

If you are in a chat window right now, paste https://api.signvoy.com/mcp into Claude or Cursor and ask it to draft something. If you are writing a service, start with the quickstart and send your first document in five minutes.

If the auth model is what you are weighing rather than the surface, MCP OAuth vs API keys covers why the MCP side has no key to paste in the first place.