# MCP (Model Context Protocol)

_Point an MCP-compatible client at the API endpoint; tools wrap the same handlers as the REST surface._

_Last updated: 2026-05-07_

---

# 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`):

```json
[component]
    }
  }
}
```

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.