@sequesign/mcp

A Model Context Protocol server for Sequesign — 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. 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 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 below.

Building the .mcpb from source:

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.

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 generates an Ed25519 keypair in your browser (the private key never reaches our servers), registers the public key to your account (the platform signs a registration record bound to its fingerprint), and shows you the private-key PEM once — download it then.
3. Copy the API key and that private-key PEM.

Paste both into the setup form (or set SEQUESIGN_API_KEY and SEQUESIGN_AGENT_PRIVATE_KEY). Reuse them across installs and machines — you do not make a new key each time.

Bring your own key (advanced). Instead of "Generate keypair", you can pick "Bring your own public key (advanced)" and paste the public PEM of a key you generated yourself (e.g. in an HSM). You hold the private key; the platform records the public half. Fully supported in managed mode.

The broker accepts only the agent key your API key is registered to — whether the dashboard generated it or you brought your own. An unregistered key (generated locally and never registered) is rejected (agent_public_key_not_registered). That's the rule: the key must be on file against your API key, and that binding happens at API-key creation.

Verifying the broker-stored receipt then shows a registered agent identity (see the receiptUrl verify path below).

Direct mode — self-asserted identity

Direct mode has no account and no registration. The agent key only proves continuity (the same signer produced these receipts), not a platform-vouched identity. Two choices:

• Leave the key blank → the server mints a fresh ephemeral key per session. Good for quick, one-off, anonymous-but-verifiable receipts; each receipt has a different self_asserted key.
• Paste a fixed PEM → one stable identity reused across sessions. Any Ed25519 PKCS#8 PEM works (e.g. the one the dashboard can generate for you, or openssl genpkey -algorithm ed25519). It stays self_asserted unless that key is the one registered to your SEQUESIGN_API_KEY: in that case the witness (which authenticates the same key) confirms the match and the receipt verifies as a registered identity — direct signing and a registered identity. (The witness also rejects signing under a key that isn't the one registered to your API key, so an API key can't mint receipts under an unregistered key.)

Usage

Add it to an MCP client (e.g. Claude Desktop) as a stdio server:

{
  "mcpServers": {
    "sequesign": {
      "command": "npx",
      "args": ["-y", "@sequesign/mcp"],
      "env": {
        "SEQUESIGN_MODE": "direct"
      }
    }
  }
}

Or run it directly:

npm install -g @sequesign/mcp
sequesign-mcp

Example prompts

Drop these into any MCP-capable agent (Claude Desktop, etc.) once the server is configured. They're written the way you'd actually ask — the agent picks the tools.

1. Record and seal a single piece of work, then verify it.

Using Sequesign, open a session for task q3-refund-review delegated by [email protected], record an action refund_approved with the evidence { "invoice": "INV-2231", "amount_usd": 480, "reason": "duplicate charge" }, then finalize the receipt and verify it. Tell me the package directory and whether it verified.

Exercises start_session → record_action → finalize → verify (the local integrity self-check).

2. Multi-party: one agent records, two others attest after the fact.

The receipt at <packageDirectory> is already sealed. Have Sequesign attach an approval to it as [email protected] (a human reviewer), then attach a counterparty confirmation as vendor-globex for the refund_approved action with purpose refund_amount_confirmation. Then verify the package and show me the approval and counterparty legs.

Exercises approve_receipt and countersign_receipt (deferred satellites bound to an already-finalized receipt), then verify. A different party — even a different model on another machine that has the package — can run these.

3. Verify the broker-stored, registered-identity copy (managed mode).

I finalized a managed-mode receipt; its receipt_url is <receipt_url> and the local package is at <packageDirectory>. Use Sequesign to verify the stored receipt against my package and tell me whether it shows external trust and a registered agent identity.

Exercises verify with receiptUrl — fetches the authoritative stored envelope (carrying the registered agent_identity_attestation), auto-fetches the published witness + registration anchors, and reports external trust plus the registered identity.

Example flow

1. sequesign_start_session → { taskId, delegatorId, policyContext } → returns sessionId.
2. sequesign_record_action → { sessionId, actionType, evidence } → returns actionId.
3. (optional) sequesign_record_counterparty_attestation → { sessionId, counterpartyId, attestedActionId, attestationPurpose }.
4. (optional) sequesign_record_approval → { sessionId, approverId, approvedActionType, approvalContext }.
5. sequesign_finalize → { sessionId } → returns the package directory + verification summary.
6. sequesign_verify → { packageDirectory } → re-verify offline any time.

License

Apache-2.0