mcp

# @sequesign/mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server for
[Sequesign](https://sequesign.com) — let an MCP-capable agent produce a
cryptographically verifiable receipt of its own delegated work, then verify it
offline.

It is a thin local-stdio wrapper over [`@sequesign/sdk`](../sequesign-sdk). The
agent's signing key never leaves the machine: in direct mode the SDK signs each
action locally and the hosted witness only co-signs a hash.

## Tools

| Tool | What it does |
| --- | --- |
| `sequesign_start_session` | Open a recording session (one signed action chain). Returns a `sessionId` (the receipt id) used by every other tool. Pass a `policyContext` object to bind the receipt to a policy (reaches `L3_POLICY_BOUND`). Optional `mode` (`direct`/`managed`) overrides the server default per session. |
| `sequesign_record_action` | Append a signed action to the chain. `evidence` is hashed and signed. Returns the `actionId`. |
| `sequesign_record_approval` | Attach a locally signed approval for a recorded action (e.g. a human or agent reviewer signing off). |
| `sequesign_record_counterparty_attestation` | Attach a counterparty's signed confirmation of a recorded action (e.g. a vendor confirming an amount). The SDK derives the content binding from the attested action. |
| `sequesign_approve_receipt` | Attach an independently-witnessed **approval** to an *already-sealed* receipt (a deferred satellite). For a reviewer — human or another agent — signing off after the fact. The approver must be distinct from the recording agent. |
| `sequesign_countersign_receipt` | Attach an independently-witnessed **counterparty confirmation** to an *already-sealed* receipt (a deferred satellite), bound to a specific action. |
| `sequesign_finalize` | Seal + witness the receipt and run the SDK's own verification. Closes the session. |
| `sequesign_verify` | Verify a sealed receipt offline. Three modes: integrity self-check of the local package (default); third-party `external` check when you pass the witness's published keys; or pass `receiptUrl` to verify the broker-**stored** receipt (the authoritative copy carrying the registered identity), auto-fetching the published witness + registration anchors. |

### Choosing a mode per session

The server default is `SEQUESIGN_MODE`, but `sequesign_start_session` accepts a
`mode` argument (`direct` or `managed`) so one running server can do both
without editing config. A `mode: "managed"` session still requires the managed
secrets (`SEQUESIGN_API_KEY` + `SEQUESIGN_AGENT_PRIVATE_KEY`); the call fails
fast if they're absent.

### Verifying the stored (registered-identity) receipt

In managed mode the broker stamps the registered `agent_identity_attestation`
into the **stored** receipt, not the local envelope — so a local verify reads
`self_asserted`. Pass the `receipt_url` from `finalize` as `receiptUrl` to
`sequesign_verify`: it fetches the stored receipt (using `SEQUESIGN_API_KEY`),
verifies it against your local package, and auto-fetches the published witness
and registration anchors, so the result shows `external` trust **and** the
`registered` identity.

### Multi-party / deferred attestation (after sealing)

`sequesign_approve_receipt` and `sequesign_countersign_receipt` attest to a
receipt that's **already finalized**, without modifying it. Each produces a
detached **satellite** that's bound to the sealed receipt by hash, independently
witnessed *at its own time*, and written to the package's `attestations.jsonl`
sidecar; the verifier folds a valid satellite into the same approval/counterparty
leg as an in-receipt one. They take the sealed **`packageDirectory`** (not a live
session), so a *different* party — even a different model on a different machine,
as long as it has the package — can approve or countersign later. This is the
basis for a multi-party flow: one agent records and seals the work, a second
party approves it, a third confirms it — three independent, timestamped
signatures on one receipt.

**Binding to the registered (stored) receipt.** By default a satellite binds to
the local `receipt.json`. In managed mode the broker-stored copy carries the
registered `agent_identity_attestation` (a different hash), so pass the
`receipt_url` as **`receiptUrl`** to `approve_receipt` / `countersign_receipt`:
the tool fetches the stored receipt (authenticated, origin-allowlisted) and
binds the satellite to it. A later `sequesign_verify --receiptUrl` then shows
the **registered identity AND the folded approval/counterparty legs on one
receipt**. Set the satellite's `mode` to match how the receipt was sealed.

**Convergence note (cross-platform).** The broker does **not** store satellites
— a sealed satellite is appended to the local package's `attestations.jsonl`.
So for parties on *different* machines/platforms to converge on one verifiable
receipt, the `.sequesign` **package must travel between them** (an orchestrator
moves it, each appends its satellite). Independent submission with server-side
satellite storage is a future broker capability.

### Vouching (verified parties)

`sequesign_record_approval` and `sequesign_record_counterparty_attestation`
mint an **ephemeral** key when you don't pass one, so the leg verifies as
`present_unverified`. To get a `present_verified` (vouched) leg, enroll the
party's key with the platform first and pass both the enrolled private key PEM
and the returned `identityProofRef`. Then `sequesign_verify` flips the leg to
`present_verified` when given the platform's published registration keys.

## Configuration

All configuration is via environment variables:

| Variable | Default | Notes |
| --- | --- | --- |
| `SEQUESIGN_MODE` | `direct` | Default transport: `direct` (local key, independent witness co-signs) or `managed` (broker). Overridable per session via the `mode` tool argument. |
| `SEQUESIGN_WITNESS_URL` | `https://witness.sequesign.com` | Direct-mode witness. |
| `SEQUESIGN_BROKER_URL` | `https://broker.sequesign.com` | Managed-mode broker. |
| `SEQUESIGN_DASHBOARD_API_URL` | `https://dashboard-api.sequesign.com` | Source of the published registration keys for the `receiptUrl` verify path. |
| `SEQUESIGN_RECEIPT_LIBRARY_URL` | `https://library.sequesign.com` | Receipt-store origin. The API key is forwarded **only** to this or the broker origin when fetching a `receiptUrl`; any other origin is rejected before the key is sent (key-exfiltration guard). |
| `SEQUESIGN_API_KEY` | — | Required in managed mode (write-class key). In **direct** mode it's passed to the witness too — the hosted witness authenticates the signing POST, so direct mode needs it unless you point `SEQUESIGN_WITNESS_URL` at a witness that allows unauthenticated signing. |
| `SEQUESIGN_TIER` | `hosted` | Managed tier: `hosted`, `hash-only`, or `ephemeral`. |
| `SEQUESIGN_AGENT_PRIVATE_KEY` | — | Ed25519 PKCS#8 PEM for the agent key. In direct mode, if unset a fresh ephemeral key is minted per session (identity reads `self_asserted`). **Required in managed mode** — it must be the key your API key is registered to (the broker rejects any other agent key). |
| `SEQUESIGN_PACKAGE_DIR` | `<tmpdir>/sequesign-mcp` | Where receipt packages are written. |

> Sessions are held **in memory** for the life of the process. A `sessionId`
> does not survive a server restart or `sequesign_finalize`.

## Install

### As a Claude Desktop Extension (`.mcpb`) — recommended

The one-click path: download `sequesign.mcpb` from the
[GitHub releases](https://github.com/Sequesign/mcp/releases) and open it
with Claude Desktop (Settings → Extensions → install from file). Desktop renders
a setup form from the manifest's `user_config`; fill in:

| Field | Notes |
| --- | --- |
| **Mode** | `direct` (default) or `managed`. |
| **API key** | Your write-class key. Required for `managed`; in `direct` it authenticates the hosted witness. Stored in your OS keychain. |
| **Agent private key (PEM)** | Ed25519 PKCS#8 PEM. Required in `managed` (must match the key your API key is registered to); leave blank in `direct` to mint an ephemeral key per session. Stored in your OS keychain. |
| **Receipt package directory** | Where sealed packages are written. Blank → a temp directory. |

Secrets go to the OS keychain (never the manifest), and blank optional fields
fall back to their defaults. The bundle is self-contained — no `npm`/`node`
project setup required. **Where do the API key and agent key come from?** See
[Getting your keys](#getting-your-keys-and-which-identity-you-get) below.

**Building the `.mcpb` from source:**

```sh
npm run build:mcpb -w @sequesign/mcp
# → packages/sequesign-mcp/sequesign.mcpb (+ the staged mcpb-dist/ directory)
```

The build bundles the server and all dependencies into a single file with
esbuild and copies the protocol registry/schemas/profiles next to it, then packs
and validates via `@anthropic-ai/mcpb`. Attach the resulting `.mcpb` (and its
printed SHA-256) to a GitHub release.

> Releasing to npm and the official MCP registry is automated — see
> [PUBLISHING.md](./PUBLISHING.md).

### Via npm

For non-Desktop MCP clients (or if you prefer managing config yourself), install
from npm and configure via environment variables — see **Usage** below.

## Getting your keys (and which identity you get)

The two secrets — your **API key** and your **agent private key** — come from the
Sequesign dashboard's Create-API-key flow. The key you use in managed mode must
be the one **registered** to your API key.

### Managed mode — registered identity

Create an API key in the dashboard (Settings → API keys → **Create key**).
Registration is **off by default**, so you must opt in:

1. Enable **"Register this key with an agent public key"** (the checkbox in the
   create dialog — it's unchecked by default; without it you get a plain API key
   and **no** private-key PEM, which is not enough for managed mode).
2. Choose **"Generate keypair (recommended)"**. The dashboard then g