{
  "markdown": "# @sequesign/mcp\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for\n[Sequesign](https://sequesign.com) — let an MCP-capable agent produce a\ncryptographically verifiable receipt of its own delegated work, then verify it\noffline.\n\nIt is a thin local-stdio wrapper over [`@sequesign/sdk`](../sequesign-sdk). The\nagent's signing key never leaves the machine: in direct mode the SDK signs each\naction locally and the hosted witness only co-signs a hash.\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `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. |\n| `sequesign_record_action` | Append a signed action to the chain. `evidence` is hashed and signed. Returns the `actionId`. |\n| `sequesign_record_approval` | Attach a locally signed approval for a recorded action (e.g. a human or agent reviewer signing off). |\n| `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. |\n| `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. |\n| `sequesign_countersign_receipt` | Attach an independently-witnessed **counterparty confirmation** to an *already-sealed* receipt (a deferred satellite), bound to a specific action. |\n| `sequesign_finalize` | Seal + witness the receipt and run the SDK's own verification. Closes the session. |\n| `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. |\n\n### Choosing a mode per session\n\nThe server default is `SEQUESIGN_MODE`, but `sequesign_start_session` accepts a\n`mode` argument (`direct` or `managed`) so one running server can do both\nwithout editing config. A `mode: \"managed\"` session still requires the managed\nsecrets (`SEQUESIGN_API_KEY` + `SEQUESIGN_AGENT_PRIVATE_KEY`); the call fails\nfast if they're absent.\n\n### Verifying the stored (registered-identity) receipt\n\nIn managed mode the broker stamps the registered `agent_identity_attestation`\ninto the **stored** receipt, not the local envelope — so a local verify reads\n`self_asserted`. Pass the `receipt_url` from `finalize` as `receiptUrl` to\n`sequesign_verify`: it fetches the stored receipt (using `SEQUESIGN_API_KEY`),\nverifies it against your local package, and auto-fetches the published witness\nand registration anchors, so the result shows `external` trust **and** the\n`registered` identity.\n\n### Multi-party / deferred attestation (after sealing)\n\n`sequesign_approve_receipt` and `sequesign_countersign_receipt` attest to a\nreceipt that's **already finalized**, without modifying it. Each produces a\ndetached **satellite** that's bound to the sealed receipt by hash, independently\nwitnessed *at its own time*, and written to the package's `attestations.jsonl`\nsidecar; the verifier folds a valid satellite into the same approval/counterparty\nleg as an in-receipt one. They take the sealed **`packageDirectory`** (not a live\nsession), so a *different* party — even a different model on a different machine,\nas long as it has the package — can approve or countersign later. This is the\nbasis for a multi-party flow: one agent records and seals the work, a second\nparty approves it, a third confirms it — three independent, timestamped\nsignatures on one receipt.\n\n**Binding to the registered (stored) receipt.** By default a satellite binds to\nthe local `receipt.json`. In managed mode the broker-stored copy carries the\nregistered `agent_identity_attestation` (a different hash), so pass the\n`receipt_url` as **`receiptUrl`** to `approve_receipt` / `countersign_receipt`:\nthe tool fetches the stored receipt (authenticated, origin-allowlisted) and\nbinds the satellite to it. A later `sequesign_verify --receiptUrl` then shows\nthe **registered identity AND the folded approval/counterparty legs on one\nreceipt**. Set the satellite's `mode` to match how the receipt was sealed.\n\n**Convergence note (cross-platform).** The broker does **not** store satellites\n— a sealed satellite is appended to the local package's `attestations.jsonl`.\nSo for parties on *different* machines/platforms to converge on one verifiable\nreceipt, the `.sequesign` **package must travel between them** (an orchestrator\nmoves it, each appends its satellite). Independent submission with server-side\nsatellite storage is a future broker capability.\n\n### Vouching (verified parties)\n\n`sequesign_record_approval` and `sequesign_record_counterparty_attestation`\nmint an **ephemeral** key when you don't pass one, so the leg verifies as\n`present_unverified`. To get a `present_verified` (vouched) leg, enroll the\nparty's key with the platform first and pass both the enrolled private key PEM\nand the returned `identityProofRef`. Then `sequesign_verify` flips the leg to\n`present_verified` when given the platform's published registration keys.\n\n## Configuration\n\nAll configuration is via environment variables:\n\n| Variable | Default | Notes |\n| --- | --- | --- |\n| `SEQUESIGN_MODE` | `direct` | Default transport: `direct` (local key, independent witness co-signs) or `managed` (broker). Overridable per session via the `mode` tool argument. |\n| `SEQUESIGN_WITNESS_URL` | `https://witness.sequesign.com` | Direct-mode witness. |\n| `SEQUESIGN_BROKER_URL` | `https://broker.sequesign.com` | Managed-mode broker. |\n| `SEQUESIGN_DASHBOARD_API_URL` | `https://dashboard-api.sequesign.com` | Source of the published registration keys for the `receiptUrl` verify path. |\n| `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). |\n| `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. |\n| `SEQUESIGN_TIER` | `hosted` | Managed tier: `hosted`, `hash-only`, or `ephemeral`. |\n| `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). |\n| `SEQUESIGN_PACKAGE_DIR` | `<tmpdir>/sequesign-mcp` | Where receipt packages are written. |\n\n> Sessions are held **in memory** for the life of the process. A `sessionId`\n> does not survive a server restart or `sequesign_finalize`.\n\n## Install\n\n### As a Claude Desktop Extension (`.mcpb`) — recommended\n\nThe one-click path: download `sequesign.mcpb` from the\n[GitHub releases](https://github.com/Sequesign/mcp/releases) and open it\nwith Claude Desktop (Settings → Extensions → install from file). Desktop renders\na setup form from the manifest's `user_config`; fill in:\n\n| Field | Notes |\n| --- | --- |\n| **Mode** | `direct` (default) or `managed`. |\n| **API key** | Your write-class key. Required for `managed`; in `direct` it authenticates the hosted witness. Stored in your OS keychain. |\n| **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. |\n| **Receipt package directory** | Where sealed packages are written. Blank → a temp directory. |\n\nSecrets go to the OS keychain (never the manifest), and blank optional fields\nfall back to their defaults. The bundle is self-contained — no `npm`/`node`\nproject setup required. **Where do the API key and agent key come from?** See\n[Getting your keys](#getting-your-keys-and-which-identity-you-get) below.\n\n**Building the `.mcpb` from source:**\n\n```sh\nnpm run build:mcpb -w @sequesign/mcp\n# → packages/sequesign-mcp/sequesign.mcpb (+ the staged mcpb-dist/ directory)\n```\n\nThe build bundles the server and all dependencies into a single file with\nesbuild and copies the protocol registry/schemas/profiles next to it, then packs\nand validates via `@anthropic-ai/mcpb`. Attach the resulting `.mcpb` (and its\nprinted SHA-256) to a GitHub release.\n\n> Releasing to npm and the official MCP registry is automated — see\n> [PUBLISHING.md](./PUBLISHING.md).\n\n### Via npm\n\nFor non-Desktop MCP clients (or if you prefer managing config yourself), install\nfrom npm and configure via environment variables — see **Usage** below.\n\n## Getting your keys (and which identity you get)\n\nThe two secrets — your **API key** and your **agent private key** — come from the\nSequesign dashboard's Create-API-key flow. The key you use in managed mode must\nbe the one **registered** to your API key.\n\n### Managed mode — registered identity\n\nCreate an API key in the dashboard (Settings → API keys → **Create key**).\nRegistration is **off by default**, so you must opt in:\n\n1. Enable **\"Register this key with an agent public key\"** (the checkbox in the\n   create dialog — it's unchecked by default; without it you get a plain API key\n   and **no** private-key PEM, which is not enough for managed mode).\n2. Choose **\"Generate keypair (recommended)\"**. The dashboard then generates an\n   Ed25519 keypair **in your browser** (the private key never reaches our\n   servers), registers the **public** key to your account (the platform signs a\n   registration record bound to its fingerprint), and shows you the\n   **private-key PEM once** — download it then.\n3. Copy the **API key** and that **private-key PEM**.\n\nPaste both into the setup form (or set `SEQUESIGN_API_KEY` and\n`SEQUESIGN_AGENT_PRIVATE_KEY`). Reuse them across installs and machines — you do\n**not** make a new key each time.\n\n**Bring your own key (advanced).** Instead of \"Generate keypair\", you can pick\n**\"Bring your own public key (advanced)\"** and paste the **public** PEM of a key\nyou generated yourself (e.g. in an HSM). You hold the private key; the platform\nrecords the public half. Fully supported in managed mode.\n\n> The broker accepts **only** the agent key your API key is registered to —\n> whether the dashboard generated it or you brought your own. An **unregistered**\n> key (generated locally and never registered) is rejected\n> (`agent_public_key_not_registered`). That's the rule: the key must be on file\n> against your API key, and that binding happens at API-key creation.\n\nVerifying the broker-stored receipt then shows a **registered** agent identity\n(see the `receiptUrl` verify path below).\n\n### Direct mode — self-asserted identity\n\nDirect mode has no account and no registration. The agent key only proves\n*continuity* (the same signer produced these receipts), not a platform-vouched\nidentity. Two choices:\n\n- **Leave the key blank** → the server mints a fresh ephemeral key per session.\n  Good for quick, one-off, anonymous-but-verifiable receipts; each receipt has a\n  different `self_asserted` key.\n- **Paste a fixed PEM** → one stable identity reused across sessions. Any\n  Ed25519 PKCS#8 PEM works (e.g. the one the dashboard can generate for you, or\n  `openssl genpkey -algorithm ed25519`). It stays `self_asserted` **unless** that\n  key is the one registered to your `SEQUESIGN_API_KEY`: in that case the witness\n  (which authenticates the same key) confirms the match and the receipt verifies\n  as a **registered** identity — direct signing *and* a registered identity. (The\n  witness also rejects signing under a key that isn't the one registered to your\n  API key, so an API key can't mint receipts under an unregistered key.)\n\n## Usage\n\nAdd it to an MCP client (e.g. Claude Desktop) as a stdio server:\n\n```json\n{\n  \"mcpServers\": {\n    \"sequesign\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@sequesign/mcp\"],\n      \"env\": {\n        \"SEQUESIGN_MODE\": \"direct\"\n      }\n    }\n  }\n}\n```\n\nOr run it directly:\n\n```sh\nnpm install -g @sequesign/mcp\nsequesign-mcp\n```\n\n## Example prompts\n\nDrop these into any MCP-capable agent (Claude Desktop, etc.) once the server is\nconfigured. They're written the way you'd actually ask — the agent picks the\ntools.\n\n**1. Record and seal a single piece of work, then verify it.**\n\n> Using Sequesign, open a session for task `q3-refund-review` delegated by\n> `ops@acme.example`, record an action `refund_approved` with the evidence\n> `{ \"invoice\": \"INV-2231\", \"amount_usd\": 480, \"reason\": \"duplicate charge\" }`,\n> then finalize the receipt and verify it. Tell me the package directory and\n> whether it verified.\n\nExercises `start_session` → `record_action` → `finalize` → `verify` (the local\nintegrity self-check).\n\n**2. Multi-party: one agent records, two others attest after the fact.**\n\n> The receipt at `<packageDirectory>` is already sealed. Have Sequesign attach\n> an approval to it as `cfo@acme.example` (a human reviewer), then attach a\n> counterparty confirmation as `vendor-globex` for the `refund_approved` action\n> with purpose `refund_amount_confirmation`. Then verify the package and show me\n> the approval and counterparty legs.\n\nExercises `approve_receipt` and `countersign_receipt` (deferred satellites bound\nto an already-finalized receipt), then `verify`. A *different* party — even a\ndifferent model on another machine that has the package — can run these.\n\n**3. Verify the broker-stored, registered-identity copy (managed mode).**\n\n> I finalized a managed-mode receipt; its `receipt_url` is `<receipt_url>` and\n> the local package is at `<packageDirectory>`. Use Sequesign to verify the\n> stored receipt against my package and tell me whether it shows external trust\n> and a registered agent identity.\n\nExercises `verify` with `receiptUrl` — fetches the authoritative stored\nenvelope (carrying the registered `agent_identity_attestation`), auto-fetches\nthe published witness + registration anchors, and reports `external` trust plus\nthe `registered` identity.\n\n## Example flow\n\n1. `sequesign_start_session` → `{ taskId, delegatorId, policyContext }` → returns `sessionId`.\n2. `sequesign_record_action` → `{ sessionId, actionType, evidence }` → returns `actionId`.\n3. (optional) `sequesign_record_counterparty_attestation` → `{ sessionId, counterpartyId, attestedActionId, attestationPurpose }`.\n4. (optional) `sequesign_record_approval` → `{ sessionId, approverId, approvedActionType, approvalContext }`.\n5. `sequesign_finalize` → `{ sessionId }` → returns the package directory + verification summary.\n6. `sequesign_verify` → `{ packageDirectory }` → re-verify offline any time.\n\n## License\n\nApache-2.0\n",
  "bytes": 15284,
  "sha": "b80348340b5d246f0d07721ac15478588a7439bca72353908fb9ef760a4b4124",
  "repo_slug": "sequesign/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sequesign_sequesign_cc2ecabd/readme"
}