Verafirma logo Verafirma
View as Markdown ↓

MCP (Model Context Protocol)

MCP is the protocol AI clients use to call tools across a network boundary. The API exposes a streamable-HTTP MCP server; an MCP-compatible client can connect, list available tools, and call them with the same auth modes the REST surface uses.

The endpoint

POST https://api.verafirma.com/mcp

Streamable-HTTP transport. JSON-RPC over HTTP. Methods: initialize, tools/list, tools/call. Auth flows through the same modes as /v1/*: API key (Authorization: Bearer vf_live_*), x402 (PAYMENT-SIGNATURE header), or wallet JWT (Authorization: Bearer <JWT>).

The tools wrap the REST handlers, not duplicate them — so a tools/call against verafirma.create_signing_request runs through the same auth, validation, billing, and Documenso wrap as POST /v1/envelopes. There’s no second handler to keep in sync.

V1 tools

The current tool set, exposed via tools/list:

  • verafirma.create_signing_request — wraps POST /v1/envelopes. Send a PDF + recipient(s) + payment authorization; get back a signing URL.
  • verafirma.get_envelope_status — wraps GET /v1/envelopes/{id}/status. Live status from the underlying signing engine; reconciles cached state.
  • verafirma.list_envelopes — wraps GET /v1/envelopes. Paginated history.
  • verafirma.register_webhook — wraps POST /v1/webhooks. Register a callback URL for envelope state events.

Additional tools land as new endpoints stabilize. The tools/list response is authoritative; this page summarizes a snapshot.

Configuring Claude Desktop

To wire the API’s tools into Claude Desktop, edit the desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "verafirma": {
      "url": "https://api.verafirma.com/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer vf_live_<your-key>"
      }
    }
  }
}

Restart Claude Desktop after editing. The tools appear in the tool palette; calls debit the same wallet the API key is bound to.

Configuring other MCP clients

The endpoint speaks the standard streamable-HTTP MCP transport. Any client that targets the spec works against the URL above. The pattern is the same: point the client at https://api.verafirma.com/mcp, supply the auth header your account uses, and the client picks up the tools list automatically.

For agents using the lodestone path (no API key), the auth header is PAYMENT-SIGNATURE instead. The exact header is supplied per tools/call, not at session level — each call carries its own payment authorization, since the per-call billing model doesn’t have a session concept.

Discovery surfaces

Two well-known files advertise the MCP endpoint to crawlers and clients that don’t already know to look:

  • /.well-known/mcp — SEP-1960 lightweight advertisement: endpoint URL + accepted auth methods. Tiny JSON.
  • /.well-known/mcp/server-card.json — SEP-1649 rich server-card: endpoint, homepage, contact, tool summaries.

Both shapes follow in-flight MCP spec proposals. They’re stable enough to ship; if the spec moves to a different shape, this site refreshes the well-known files in a follow-up.

The /.well-known/mcp.json route on the API (distinct from these marketing-side ones) is the runtime advertisement that clients hitting the API origin would look for; the /openapi.json discovery surface tags it under the discovery operation set.

What MCP doesn’t change

  • Auth is the same. API key, x402, wallet JWT all work; the cookie path doesn’t (MCP clients don’t run in a same-origin browser context).
  • Billing is the same. Per-call price applies to billable tool calls, not to discovery (tools/list) or initialize.
  • Idempotency is the same. A tools/call for a billable operation accepts an idempotency key in arguments and treats it the same way the REST surface does.
  • Errors are the same shape. Tool errors carry the same code set as the REST API; clients can branch on them without a second translation layer.

Pointing humans at it

If you’re writing a docs page or onboarding flow that mentions MCP, point at the endpoint URL plus the V1 tool list above. The agent-discovery surfaces (/llms.txt, /.well-known/mcp*) cover the AI-client side; humans configure their client manually using one of the patterns shown above.